> ## Documentation Index
> Fetch the complete documentation index at: https://docs.btca.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.
* `/copy` copies the latest user question and assistant response.
* `/copy-all` copies the full thread (all user and assistant messages).

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:

```bash theme={null}
# 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 reference <repo>`

Clones a git repository into `./references/<repo-name>` for local reference use.

Behavior:

* Destination is always `references/<repo-name>`, where `<repo-name>` is derived from the clone target.
* If destination already exists, the command fails and does not overwrite.
* In a git repository, it adds `references/` to `.git/info/exclude` (local-only, not committed) if missing.
* Outside a git repository, clone still succeeds and prints a warning that exclude was not updated.
* Prints optional copy-paste snippets for `AGENTS.md` and `CLAUDE.md` to let agents use `references/` as read-only supplemental context.

Example:

```bash theme={null}
btca reference https://github.com/sveltejs/svelte.git
```

## `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:

```bash theme={null}
# 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.

Current curated model choices in the interactive flow:

* `openai`: `gpt-5.3-codex-spark`, `gpt-5.4`
* `opencode`: `claude-haiku-4-5`, `claude-sonnet-4-6`, `gemini-3-flash`, `glm-4.7`, `kimi-k2.5`, `gpt-5.4`, `gpt-5.3-codex-spark`

For `github-copilot`, model selection is best-effort. GitHub Copilot may reject model IDs that
appear in public model catalogs depending on the specific API endpoint, account, or org policy.

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:

```bash theme={null}
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.