Available commands

Full reference for every bitoarch-local subcommand, flag, and environment variable. For install + quick start, see the main documentation.

• index

• serve

• status

• resume

• clean

• config mcp-config

• update

• setup

• info

• Global options and env vars

---

index — Index Git Repositories

bitoarch-local index -i <repos-dir> [options]

Scans <repos-dir> one level deep and indexes every entry that looks like a git repo (has a .git/ subdirectory). <repos-dir> can also be a single repo path — if the directory itself has a .git/, it's indexed as a single repo. For large repos-dir with many unrelated repos, use --repos "name1, name2" to narrow the scope.

Re-running index is cheap: it hashes each repo and skips unchanged ones. No --force needed for normal workflows.

Flag	Description	Default
-i, --input <dir>	Required. Directory of git repos (one level deep) OR a single repo path	—
-o, --output <dir>	Output directory for index data	~/.bito/bitoarch/index
--repos <names>	Comma-separated repo names to index (quote the value)	all repos in <dir>
--skip-metadata	Skip metadata extraction	false
--skip-tfidf	Skip TF-IDF generation	false
--skip-project-info	Skip project-info extraction	false
--skip-edges	Skip dependency extraction	false
--skip-clusters	Skip cluster generation	false
--force	Re-index even if data exists (wipes state, re-runs every phase)	false
--yes	Skip --force --repos confirmation prompt	false
-v, --verbose	Verbose output	false
-d, --debug	Debug mode	false

Examples:

# Index all repos under a directory
bitoarch-local index -i ~/code
​
# Index a single repo
bitoarch-local index -i ~/code/my-api
​
# Index specific repos only (use quotes!)
bitoarch-local index -i ~/code --repos "my-api, my-frontend, shared-lib"
​
# Index to a custom location
bitoarch-local index -i ~/code -o /data/bito-index
​
# Force complete re-index (rarely needed — incremental is the default)
bitoarch-local index -i ~/code --force

Indexing phases (run in order):

1. Code search index

2. Symbol index

3. Local metadata extraction

4. Local edges / dependency extraction

5. Project-info generation

6. Edges finalization

7. TF-IDF index generation

8. Repository clustering

Incremental behavior. On re-run, the tool compares each repo's current hash (git HEAD + file mtimes) against the stored hash from the last run. New or changed repos are reprocessed; unchanged repos are skipped. To force a full re-index of everything, add --force.

---

serve — Start MCP Server

bitoarch-local serve [options]

Starts the MCP server that AI assistants connect to. Stdio mode (the default) is what AI assistants use; HTTP mode is for testing, scripting, or fronting with a reverse proxy.

Flag	Description	Default
-m, --mode <mode>	Transport: stdio or http	stdio
-p, --port <port>	Port for HTTP mode	3000
--data <dir>	Directory containing the pre-built index data	~/.bito/bitoarch/index
--repos <dir>	Directory containing the original git source trees (enables getCode)	—
-v, --verbose	Verbose logging	false
-d, --debug	Debug logging	false

--data vs --repos. --data points at the already-indexed data produced by index; you rarely need to change this unless you indexed to a custom -o location. --repos points at the original git source trees (where the .git/ dirs live) so the getCode tool can read source files on demand. Without --repos, getCode returns errors. Without --data, the server has no indexed data to serve.

Examples:

# Typical usage: default index, point at original source trees
bitoarch-local serve --repos ~/code
​
# Custom index location (if you indexed with -o)
bitoarch-local serve --data /data/bito-index --repos ~/code
​
# HTTP mode for testing / non-stdio clients
bitoarch-local serve --mode http --port 3000 --repos ~/code

HTTP mode health check:

curl http://127.0.0.1:3000/health
# → {"status":"ok","server":"bitoarch-local","transport":"http-unified",...}

Network-exposed deployments. There is no built-in HTTPS mode (TLS on 127.0.0.1 adds nothing). If you need HTTPS, put a reverse proxy (Caddy, nginx) in front for TLS termination.

MCP tools served (13 total):

Tool	Description
getCapabilities	Discover available analysis capabilities
listRepositories	Browse all indexed repositories
searchRepositories	Natural language search across repos
getRepositoryInfo	Get repo metadata, structure, dependencies
getRepositorySchema	Discover repo data structure
getFieldPath	Extract specific nested fields
queryFieldAcrossRepositories	Compare same field across repos
searchWithinRepository	Search within a single repo's data
searchCode	Search code across indexed repos
searchSymbols	Symbol search (functions, classes, etc.)
getCode	Read actual source code from files
listClusters	View repository clusters
getClusterInfo	Examine a specific cluster

---

status — Check Indexing Status

bitoarch-local status [options]

Reads .indexer-state.json and reports which repos are indexed, their last-updated timestamps, and the current indexing status. Does not probe the server — it's a pure state-file read.

Flag	Description	Default
-o, --output <dir>	Index directory to check	~/.bito/bitoarch/index
--json	JSON output	false

---

resume — Resume Interrupted Indexing

bitoarch-local resume [options]

If a previous index run was interrupted (Ctrl+C, crash, power loss), resume picks up where it left off. If the previous run completed successfully, resume prints a message showing the original input directory and exits.

Flag	Description	Default
-o, --output <dir>	Output directory with the interrupted state	~/.bito/bitoarch/index
--concurrency <n>	Number of parallel indexing operations	2
-v, --verbose	Verbose output	false
-d, --debug	Debug mode	false

---

clean — Remove Index Data

bitoarch-local clean [options]

Flag	Description	Default
-o, --output <dir>	Index directory to clean	~/.bito/bitoarch/index
--repo <name>	Remove a single repository from the index (not plural)	—
--all	Remove everything: state + per-repo data + TF-IDF + clusters (requires --force)	false
--force	Required only with --all. Accepted (but no-op) with --repo and default state-only clean, for back-compat with existing scripts.	false

Confirmation policy. --repo <name> and the default state-only clean run without prompting — the user named a specific repo (intent is explicit), and the state-only clean is trivially reversible (just re-run index). --all is the only destructive path that needs a full re-index to recover, so it keeps the --force gate.

Behavior by flag combination:

Command	What it removes
clean (no flags)	Only the state file (.indexer-state.json + repos.json). Next index starts fresh but reuses existing data on disk.
clean --repo <name>	Just that one repo's data: project-info/<name>.json, edges/<name>.json, ctags-indices/<name>.tags, zoekt-indices/<name>_v*.zoekt, and the repo's state entry. TF-IDF and clusters.json are NOT regenerated automatically — re-run index to refresh them.
clean --all	Refuses without --force. Prints a warning explaining recovery requires a full re-index.
clean --all --force	Everything: state + all per-repo data + TF-IDF + clusters. Full wipe.

Examples:

# Remove just one repo (e.g. after deleting it from disk)
bitoarch-local clean --repo my-api
​
# Reset state but keep existing indices
bitoarch-local clean
​
# Full wipe (only path that needs --force)
bitoarch-local clean --all --force

---

config mcp-config — Configure MCP Clients

bitoarch-local config mcp-config [options]

Detects installed AI assistants on your machine and configures them to use bitoarch-local as an MCP server. Creates timestamped backups of existing configs before modifying.

Flag	Description	Default
--all	Configure every detected MCP client	—
--client <name>	Configure a specific client	—
--dry-run	Preview changes without modifying files	false
--list-clients	List supported clients and their detection status	—
--remove	Remove bitoarch-local from configs instead of adding	false
--repos <dir>	Repos directory for the serve command in the generated config	—
--yes	Skip the "Configure for N clients?" confirmation prompt (for scripts / CI)	false

Supported clients (9 total):

claude-desktop · claude-code · cursor · windsurf · cline · vscode-copilot · zed · amazon-q · xcode

Most clients are file-based — the command writes/merges an entry into a JSON config file on disk. claude-code is CLI-based — the command invokes claude mcp add-json bitoarch-local '<json>' via the claude CLI rather than writing a config file directly.

Examples:

# List all supported clients and detection status
bitoarch-local config mcp-config --list-clients
​
# Preview changes without writing
bitoarch-local config mcp-config --dry-run --all
​
# Configure all detected clients
bitoarch-local config mcp-config --all
​
# Configure all clients non-interactively (CI / scripts)
bitoarch-local config mcp-config --all --yes
​
# Configure all clients with a repos directory
bitoarch-local config mcp-config --all --repos ~/code
​
# Configure a specific client
bitoarch-local config mcp-config --client cursor
​
# Remove bitoarch-local from all client configs
bitoarch-local config mcp-config --remove --all

What this does:

1. Detects installed MCP clients on your system

2. Creates a timestamped backup of existing configs

3. Adds/updates the bitoarch-local MCP server entry

4. Preserves all other existing MCP server configurations

---

update — Self-update the binary

bitoarch-local update [options]

Fetches the release manifest from the CDN, downloads the latest binary for your platform, verifies its SHA256 against the manifest, re-applies the ad-hoc code signature (macOS), and atomically replaces the running binary.

Flag	Description	Default
--force	Re-download even if the manifest says you're already at the latest version	false

Examples:

# Normal upgrade
bitoarch-local update
​
# Force re-download (useful during pre-release iteration where
# multiple builds share the same version string)
bitoarch-local update --force

Env var override — point update at a different CDN (mirrors, staging, internal hosts):

BITO_DOWNLOAD_URL=https://my-mirror.example.com bitoarch-local update

If your binary's version is below the published minimum in the manifest, update is exempt from the version-check block — so you can always upgrade out of a blocked state.

---

setup — One-time post-install setup

bitoarch-local setup

On macOS and Linux there are no one-time setup tasks — the installer handles everything. This command exists so setup is discoverable; running it prints a "no setup needed" message and exits.

---

info — Show Binary Information

bitoarch-local info [--json]

Prints version, build ID, build time, platform, and the binary path. Useful for bug reports and verifying which binary is on $PATH.

Flag	Description
--json	JSON output

Example:

=== Bito AI Architect ===
Version:      1.0.0
Build:        2vav654z (2026-04-17T10:35:12.661Z)
Platform:     darwin/arm64
Binary:       /Users/foo/.bito/bitoarch/bin/bitoarch-local
Standalone:   yes

---

Global options and env vars

These apply to every command.

Global flags:

Flag	Description
-V, --version	Print version string and exit
--skip-update-check	Skip the remote version check (useful for offline / CI / air-gapped environments)
-h, --help	Print help for the current command

Environment variables:

Variable	Purpose
BITO_DOWNLOAD_URL	Base URL for the release CDN. Overrides the baked-in default in install.sh / the update command. Use this for enterprise mirrors, staging tests, or internal hosts.
BITO_SKIP_UPDATE_CHECK	Set to 1 to skip the version check on every command (same effect as --skip-update-check but globally).
BITO_INSTALL_DIR	Where install.sh places the binary. Defaults to ~/.bito/bitoarch/bin.
BITO_LOCAL_BINARY	Path to a local binary for install.sh --local. Alternative to passing the path as an argument.

Exit codes:

Code	Meaning
0	Success
1	User error, validation failure, or version-check block
126	Binary not executable (missing chmod +x)
127	Binary not found on PATH
137	SIGKILL — OS killed the process
139	SIGSEGV — arch mismatch, GLIBC mismatch, truncated binary