Get started with ArchByte

Install. Connect. Observe.

New to ArchByte? Just run archbyte run — it walks you through sign-in and provider setup automatically. This page covers each step in detail if you prefer manual control.

Install ArchByte

Single binary, no runtime needed:

$ curl -fsSL archbyte.heartbyte.io/i | bash

Then run:

$ archbyte run

Alternative: direct download

Download the latest binary for your platform:

# macOS (Apple Silicon)
$ curl -fsSL https://api.heartbyte.io/downloads/latest/archbyte-darwin-arm64 -o archbyte && chmod +x archbyte

Also available: archbyte-darwin-x64, archbyte-linux-x64, archbyte-windows-x64.exe

Already installed? Run archbyte update to update to the latest version.

Sign in or create an account

Create a free account to start scanning. No credit card required. Free tier includes unlimited scans.

$ archbyte login

Expected output

Sign in or create a free account to get started.
Opening browser for GitHub sign-in...
Don't have an account? One will be created automatically.
Logged in as your-username (free tier)

Opens your browser for GitHub or Google OAuth. Don't have an account? One is created automatically on first sign-in. Your credentials are stored locally at ~/.archbyte/credentials.json.

Configure your AI provider

ArchByte is BYOK (Bring Your Own Key). Connect your preferred AI provider below.

Already using Claude Code or Codex? No API key needed. ArchByte works with your existing subscription. Run archbyte init and select your tool.

Your keys stay on your machine. ArchByte never transmits or stores your API keys. All model calls go directly from your machine to your chosen provider.

Recommended for best results

Get your API key from console.anthropic.com, then run:

$ archbyte init

Select Anthropic, paste your key. ArchByte validates it automatically.

Expected output

Choose your model provider: Anthropic
API key: ****...****
Validating credentials... valid
Setup complete!

Manual configuration

$ archbyte config set provider anthropic

$ archbyte config set api-key sk-ant-...

Cost: Uses Haiku 4.5 (fast agents) + Sonnet 4.5 (connections). A typical scan costs ~$0.02-0.05.

Get your API key from platform.openai.com, then run:

$ archbyte init

Select OpenAI, paste your key.

Manual configuration

$ archbyte config set provider openai

$ archbyte config set api-key sk-...

Models: Codex (fast agents) + GPT-5.2 (connections).

Get your API key from aistudio.google.com, then run:

$ archbyte init

Select Google, paste your key.

Manual configuration

$ archbyte config set provider google

$ archbyte config set api-key AIza...

Models: Gemini 2.5 Flash for fast agents, Gemini 2.5 Pro for connections. Google offers a generous free tier.

Run your first scan

Navigate to any codebase and run the full pipeline:

$ cd /path/to/your/project

$ archbyte run

This does three things in sequence:

Analyze collects static context + runs AI agents to identify components, connections, and flows
Generate converts the analysis into an interactive architecture diagram
Serve opens the diagram UI in your browser at localhost:3847

Expected output

▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100% | Analysis complete (23.4s)
Diagram generated: .archbyte/architecture.json
UI running at http://localhost:3847

Run without AI (static-only, free)

Skip the AI provider entirely with deterministic static analysis:

$ archbyte run --static

Fast and free, but less detailed than the AI pipeline.

Run each step individually

$ archbyte analyze .archbyte/archbyte.yaml

$ archbyte generate .archbyte/architecture.json

$ archbyte serve localhost:3847

Re-scan after changes

After making code changes, run analyze again. ArchByte detects what changed and only re-analyzes affected components. Faster and cheaper.

$ archbyte analyze incremental scan

$ archbyte analyze --force force full re-scan

Your architecture spec lives at .archbyte/archbyte.yaml. It's human-readable and editable. Changes you make are preserved on re-scan.

CLI reference

Every command at a glance.

Auth & Account

Command	Description	Key flags
`archbyte login`	Sign in or create a free account (interactive provider picker)	`--github` `--google` `--email` `--token <jwt>`
`archbyte logout [email]`	Sign out of ArchByte (active, specific, or all accounts)	`--all`
`archbyte accounts`	List logged-in accounts and switch active account	Subcommand: `accounts switch [email]`
`archbyte status`	Show account status, tier, and usage

Setup

Command	Description	Key flags
`archbyte init`	Configure model provider, API key, and project rules
`archbyte config`	Manage provider, API key, settings	`show` `set <key> <value>` `get <key>` `path` `--raw`

Core Pipeline

Command	Description	Key flags
`archbyte run`	Analyze, generate, and serve in one shot	`-d <dir>` `--static` `--provider <name>` `--api-key <key>` `-p <port>` `-v` `--force` `--dry-run`
`archbyte analyze`	Run AI agent pipeline on your codebase	`-d <dir>` `-o <path>` `-v` `--provider <name>` `--api-key <key>` `--static` `--force` `--dry-run`
`archbyte generate`	Generate diagram from analysis JSON	`-i <path>` `-o <path>` `-v`
`archbyte serve`	Start the visualization UI server	`-p <port>` `-d <path>`

Inspect & Export

Command	Description	Key flags
`archbyte stats`	Show architecture statistics	`-d <path>` `-c <config>`
`archbyte export`	Export to Mermaid, PlantUML, Markdown, DOT, JSON	`-d <path>` `-f <format>` `-o <path>`

Pro Features PRO

Command	Description	Key flags
`archbyte workflow`	Run composable architecture workflows	`-r <id>` `-l, --list` `-s <id>` `--create <name>` `--status` `--reset`

Utility

Command	Description	Key flags
`archbyte version`	Show version and environment info
`archbyte update`	Update ArchByte to the latest version
`archbyte mcp`	Start MCP server for AI agent integration

Global flags: All commands support --json (structured JSON output) and --quiet (suppress non-essential output).

What's next

Case study

See how ArchByte mapped OpenClaw's 41-component architecture.

Pricing

Basic is free forever. Pro is coming soon.

Troubleshooting

archbyte: command not found

Make sure the install directory is in your PATH. The installer puts the binary in /usr/local/bin or ~/.local/bin. Add the directory to your shell profile (~/.bashrc, ~/.zshrc).

No model provider configured

If you run archbyte run or archbyte analyze without a provider, you'll be prompted to set one up interactively. If you decline, it falls back to static-only analysis automatically. To set up manually: archbyte init. To skip AI entirely: archbyte run --static.

API key authentication failed

Verify your key: archbyte config show. Update it: archbyte config set api-key YOUR_KEY. If you're hitting rate limits or quota errors, check your provider dashboard for usage.

Run archbyte login again
If browser didn't open, copy the URL from terminal manually
If login times out after 60s, try archbyte login --token instead: sign in at archbyte.heartbyte.io and copy your token from the dashboard
If you see "Port 19274 is in use", close other ArchByte instances first

Port already in use

If archbyte serve reports the port is taken, it will offer to pick another port or kill the existing process. You can also specify a port manually: archbyte serve -p 4000.

Architecture file not found

This means you need to generate a diagram first. Run archbyte analyze then archbyte generate, or use archbyte run to do everything in one step.

No components detected

Run ArchByte from the root of your project (where package.json, go.mod, or similar lives). If the pipeline fails, it will fall back to static-only analysis automatically.

Where is my config stored?

Global config: ~/.archbyte/config.json. Credentials: ~/.archbyte/credentials.json. Project config: .archbyte/archbyte.yaml. View it: archbyte config show.

Need more help? archbyte@heartbyte.io