# Available commands Full reference for every `bitoarch-local` subcommand, flag, and environment variable. For install + quick start, see the [main documentation](/ai-architect/local-repository-intelligence-for-ai-assistants.md). * [`index`](#index-index-git-repositories) * [`serve`](#serve-start-mcp-server) * [`status`](#status-check-indexing-status) * [`resume`](#resume-resume-interrupted-indexing) * [`clean`](#clean-remove-index-data) * [`config mcp-config`](#config-mcp-config-configure-mcp-clients) * [`update`](#update-self-update-the-binary) * [`setup`](#setup-one-time-post-install-setup) * [`info`](#info-show-binary-information) * [Global options and env vars](#global-options-and-env-vars) *** ### `index` — Index Git Repositories ```shellscript bitoarch-local index -i [options] ``` Scans `` one level deep and indexes every entry that looks like a git repo (has a `.git/` subdirectory). `` 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 ` | **Required.** Directory of git repos (one level deep) OR a single repo path | — | | `-o, --output ` | Output directory for index data | `~/.bito/bitoarch/index` | | `--repos ` | Comma-separated repo names to index (quote the value) | all repos in `` | | `--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:** ```shellscript # 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 ```shellscript 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 ` | Transport: `stdio` or `http` | `stdio` | | `-p, --port ` | Port for HTTP mode | `3000` | | `--data ` | Directory containing the pre-built index data | `~/.bito/bitoarch/index` | | `--repos ` | 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:** ```shellscript # 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:** ```shellscript 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 ```shellscript 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 ` | Index directory to check | `~/.bito/bitoarch/index` | | `--json` | JSON output | false | *** ### `resume` — Resume Interrupted Indexing ```shellscript 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 ` | Output directory with the interrupted state | `~/.bito/bitoarch/index` | | `--concurrency ` | Number of parallel indexing operations | `2` | | `-v, --verbose` | Verbose output | false | | `-d, --debug` | Debug mode | false | *** ### `clean` — Remove Index Data ```shellscript bitoarch-local clean [options] ``` | Flag | Description | Default | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `-o, --output ` | Index directory to clean | `~/.bito/bitoarch/index` | | `--repo ` | 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 ` 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 ` | Just that one repo's data: `project-info/.json`, `edges/.json`, `ctags-indices/.tags`, `zoekt-indices/_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:** ```shellscript # 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 ```shellscript 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 ` | 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 ` | 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 ''` via the `claude` CLI rather than writing a config file directly. **Examples:** ```shellscript # 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 ```shellscript 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:** ```shellscript # 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): ```shellscript 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 ```shellscript 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 ```shellscript 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 | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bito.ai/ai-architect/local-repository-intelligence-for-ai-assistants/available-commands.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.