CLI Reference

All btca commands and what each one does

Global options

These options apply to local CLI commands.

Option	Description
--server <url>	Use an existing server (health checked).
--port <port>	Port for an auto-started server (default 0, OS-assigned).
--no-tui	Use REPL instead of TUI.
--no-thinking	Hide reasoning output (REPL and ask).
--no-tools	Hide tool traces (REPL and ask).
--sub-agent	Clean output (no reasoning or tool traces).

btca

Launches the TUI by default. Use --no-tui for the REPL.

Passing an unknown top-level command now exits with error: unknown command '<command>' and a non-zero status code, and may include a suggestion for a known command.

REPL commands:

• /help shows help.
• /resources lists resources.
• /clear clears session resources.
• /quit or /exit exits.

The REPL supports @resource mentions.

TUI command palette (/):

• /connect configures provider and model.
• /add opens the add-resource wizard.
• /clear clears chat history.
• /resume opens thread resume.
• /new is an alias for /clear.

TUI keyboard shortcuts:

• Enter sends message.
• Escape cancels streaming response (press twice to confirm).
• Ctrl+C clears input or quits.
• Ctrl+Q quits.
• Tab autocompletes commands/mentions.
• Up/Down navigates palettes/history.

btca add [url-or-path]

Adds a git repo, local directory, or npm package resource.

Options:

• -g, --global sets the flag, but target resolution still depends on whether a project config exists.
• -n, --name <name> sets a resource name.
• -b, --branch <branch> sets a branch (default main).
• -s, --search-path <path...> sets one or more search paths.
• --notes <notes> sets special notes.
• -t, --type <git|local|npm> forces the resource type.

Behavior: If no argument is provided, the CLI starts an interactive wizard. When --type is omitted, it auto-detects git URL vs local path vs npm reference. GitHub URLs are normalized to the base repo. Local paths are resolved to absolute paths. npm references accept package specs (react, @types/node, npm:react) and npmjs package URLs.

Examples:

# Git resource
btca add https://github.com/sveltejs/svelte.dev -n svelte-docs -t git -b main -s apps/svelte.dev

# Local resource
btca add -n my-docs -t local /absolute/path/to/docs

# npm resource
btca add npm:@types/node@22.10.1 -n node-types -t npm

btca remove [name]

Removes a resource by name. If omitted, it opens an interactive picker.

Options:

• -g, --global sets the flag, but is not a strict global override.

btca resources

Lists all configured resources.

btca ask

Asks a one-shot question with streaming output.

Options:

• -q, --question <text> is required.
• -r, --resource <name...> can be repeated.
• --no-thinking, --no-tools, --sub-agent control output detail.

Behavior: @resource mentions are resolved and merged with -r flags. Mentions are stripped from the query text before sending. If no resources are provided, it uses all configured resources. Uses the /question/stream SSE endpoint.

You can also pass raw HTTPS git URLs directly instead of a configured resource name. These URLs are treated as one-off resources:

• They are normalized (for example, GitHub .../blob/main/... URLs become the base repo URL).
• They use a short-lived cache key derived from a hash of the URL.
• They are cloned into a temporary folder under .tmp and removed after the request finishes.
• Branch detection tries main, then master, then trunk, then dev.
• If none of those branches exist, the request fails with an instruction to add the repo as a named resource instead.

You can also pass one-off npm references directly:

• npm:<package> (for example npm:react)
• npm:<package>@<version-or-tag> (for example npm:@types/node@22.10.1)
• npmjs URLs (for example https://www.npmjs.com/package/react)

These references are hydrated into temporary resources and removed automatically after the request.

Examples:

# Normal configured resource ask
btca ask -r svelte -q "How do runes work in Svelte 5?"

# Anonymous one-off git repo ask
btca ask -r https://github.com/sveltejs/svelte -q "Where is the implementation of writable stores?"

# Anonymous one-off npm package ask
btca ask -r npm:react@19.0.0 -q "How is useTransition exported?"

btca connect

Configures provider and model.

Options:

• -g, --global targets the global config if no project config exists.
• -p, --provider <id> sets the provider.
• -m, --model <id> sets the model.

Behavior: When provider and model are provided, it updates the config directly. Otherwise, it walks an interactive provider selection (connected providers first), then model selection. If auth is required, it prompts for credentials.

For openai-compat, the interactive flow additionally prompts for:

• Base URL (required): root URL of your OpenAI-compatible server.
• Provider name (required): AI SDK provider identifier.
• Model ID (required): saved as model in btca.config.jsonc.
• API key (optional): only if your server requires auth, stored in OpenCode auth.

btca status

Shows current btca status.

Output includes:

• selected model
• selected provider
• selected model source (project, global, or default)
• selected provider source (project, global, or default)
• whether the selected provider is authenticated
• resources from ~/.config/btca/btca.config.jsonc
• resources from ./btca.config.jsonc (if the file exists)
• installed btca version and latest npm version
• update hint if your version is behind

If an update is available, it prints:

Update available: run "bun add -g btca@latest"

btca disconnect

Disconnects provider credentials.

Options:

• -p, --provider <id> selects a provider to disconnect.

Behavior: If omitted, it opens an interactive picker.

btca skill

Runs the skills.sh installer for the btca CLI skill (interactive).

btca init

Project setup wizard.

Options:

• -f, --force overwrites existing config.

Behavior: Creates btca.config.jsonc and prompts for storage mode (local .btca/ or global). If local storage is selected, it also handles .gitignore updates for .btca/.

btca clear

Clears all locally cloned resources.

btca wipe

Permanently deletes BTCA config files for the current directory and global config.

Options:

• -y, --yes skips the interactive confirmation prompt.

Behavior:

• Targets ./btca.config.jsonc.
• Targets ~/.config/btca/btca.config.jsonc.
• Prints removed, missing, and failed paths.
• Shows a confirmation prompt unless --yes is passed.

btca serve

Starts the local server.

Options:

• -p, --port <port> sets the port (default 8080).

btca mcp

Runs the local MCP server over stdio by default.

Subcommands:

• btca mcp local scaffolds editor config for local stdio MCP.

Behavior:

• Starts (or reuses) the local server and exposes MCP tools over stdin/stdout.
• Intended for agent configs that support stdio transport.

Tools:

• listResources - list local resources.
• ask - ask a question against local resources, HTTPS git URLs, or npm references.