> ## Documentation Index
> Fetch the complete documentation index at: https://thebettercontextapp-davis-web-resource.mintlify.site/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.            |
| `--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.

REPL commands:

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

The REPL supports `@resource` mentions.

## `btca add [url-or-path]`

Adds a git repo, website, or local directory 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|website|local>` forces the resource type.
* `--max-pages <number>` sets a website crawl page cap (default `200`).
* `--max-depth <number>` sets a website crawl depth cap (default `3`).
* `--ttl-hours <number>` sets website cache TTL hours (default `24`).

Behavior: If no argument is provided, the CLI starts an interactive wizard. When `--type` is omitted, it auto-detects URL vs path (`git` for URLs, `local` for paths). GitHub URLs are normalized to the base repo. Local paths are resolved to absolute paths.

Example (local path):

```bash theme={null}
btca add -n my-docs -t local /absolute/path/to/docs
```

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

## `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 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: Prompts for setup type: MCP (remote) or CLI (local). The MCP path validates an API key if needed and creates `btca.remote.config.jsonc`. The CLI path creates `btca.config.jsonc` and handles `.btca/` and `.gitignore`.

## `btca clear`

Clears all locally cloned resources.

## `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.
* `btca mcp remote` scaffolds editor config for remote HTTP MCP (stubs an API key).

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.

## Remote commands (`btca remote`)

All remote commands require an API key linked with `btca remote link`.

### `btca remote link`

Authenticates with the btca cloud API.

Options:

* `--key <apiKey>` provides the API key directly.

Behavior: If `--key` is omitted, it prompts for a key and validates it by calling MCP `listResources`.

### `btca remote unlink`

Removes the stored API key.

### `btca remote status`

Shows sandbox state, plan, version, and current project info.

### `btca remote wake`

Pre-warms the sandbox and returns when ready.

### `btca remote add [url]`

Adds a git resource to local remote config and syncs to the cloud.

Options:

* `-n, --name <name>` sets a resource name.
* `-b, --branch <branch>` sets a branch.
* `-s, --search-path <path...>` sets one or more search paths.
* `--notes <notes>` sets special notes.

Behavior: Creates local config if missing and prompts for a project name. GitHub URLs are normalized. Syncs to cloud and warns if the sync fails.

### `btca remote sync`

Syncs local remote config with the cloud.

Options:

* `--force` overwrites cloud config on conflicts.

Behavior: Detects conflicts when a resource name exists with different settings.

### `btca remote ask`

Asks a question via the cloud sandbox.

Options:

* `-q, --question <text>` is required.
* `-r, --resource <name...>` can be repeated.

Behavior: Validates resources by calling `listResources`. If none are specified, it uses all available resources.

### `btca remote grab <threadId>`

Fetches the full thread transcript.

Options:

* `--json` outputs JSON.
* `--markdown` outputs Markdown (default).

### `btca remote init`

Creates `btca.remote.config.jsonc`.

Options:

* `-p, --project <name>` sets the project name.

### `btca remote mcp [agent]`

Outputs an MCP configuration snippet. Supported agents are `opencode` (JSON config block) and `claude` (Claude Code CLI command).