# BugTape CLI `npx -y bugtape` connects coding agents and chatbots to BugTape with one click, and sets up capture in a repository. Node.js 20 or later, no dependencies. The package is [`bugtape` on npm](https://www.npmjs.com/package/bugtape). If your network cannot reach the npm registry, run the same reviewed package from BugTape: `npx -y https://app.bugtape.ai/cli/bugtape-0.1.10.tgz`. ## Connect an agent ```bash npx -y bugtape connect claude # Claude Code npx -y bugtape connect cursor # writes .cursor/mcp.json npx -y bugtape connect codex # codex mcp add, token from BUGTAPE_MCP_TOKEN npx -y bugtape connect grok # grok mcp add, token from BUGTAPE_TOKEN npx -y bugtape connect grok-bot # prints the xAI remote MCP tool for your bot ``` The first run signs in with a code. The CLI prints a link and an 8-letter code; open the link, check the code matches, pick the workspace and what the agent may do, and click **Allow**. No browser on that machine? Send the link to whoever owns the workspace; one click finishes it. The sign-in appears on the Team page under its name (`--name`), where you can remove it. `--oauth` adds only the URL, and Claude Code, Cursor or Codex opens the BugTape sign-in page itself. `--global` writes user-wide settings instead of this project's. After `connect`, the CLI says what it did in plain words, which workspace it used, and what to do next and not to do. It never prints a command for you to run again. For Claude Code it then asks Claude Code itself (`claude mcp get bugtape`) and shows the answer as `Status`: it says "connected" only when that check passes, "added to" when the check cannot answer, and gives the fix when Claude Code cannot connect (for example a revoked sign-in). Run `connect` in your project folder: a folder-only entry in your home folder works only when the agent opens exactly there, so the CLI warns and offers `--global`. In a terminal the output is in colour; `--no-colour`, `NO_COLOR=1` or a pipe give plain text, and `--json` gives the same facts for agents. ### Which workspace You can belong to several workspaces; one sign-in belongs to one. The CLI saves your sign-in and reuses it, so `connect` and `init` print the workspace they use (`Workspace Go-Live Tester (your saved sign-in)`) and the project this folder reports to: - It looks for this repo's capture key (`BUGTAPE_KEY`, `.env`, `.env.local`, `.dev.vars`, or a `bt_live_` browser key in tracked files) and asks BugTape which project it belongs to. If that project is in another workspace, it warns you: your agent would not see this repo's errors. - With no key, it looks for a project with this folder's name (only inside a git repository; elsewhere the folder name says nothing). Case, spaces and punctuation do not count, so `mcpcensus` finds "MCP Census". - To use another workspace, add `--switch`: it signs in again so you can pick the workspace on the approval page, and replaces the agent's old entry. ```bash npx -y bugtape connect claude --switch npx -y bugtape whoami # shows the workspace of your saved sign-in ``` Codex and Grok read the token from the environment, so it never sits in a file in the repository: ```bash export BUGTAPE_TOKEN="$(npx -y bugtape token)" ``` ## Set up capture in a repository ```bash npx -y bugtape init ``` 1. Detects the stack: browser app, Node.js, Python, Cloudflare Workers, iOS or any other server (`--platform` to choose). 2. Uses the project this repo's capture key reports to, or the project named after the repository (case, spaces and punctuation do not count), or creates it (`--project`, `--project-id`). On Free, which has one project, it uses that project and says so. **It stops instead of creating a second project** when the repo's key reports to another workspace, or when the workspace already has projects and none matches the folder. It then lists the choices: `--switch` to sign in to the right workspace, `--project-id ` to use a project that is there, or `--new-project` to create one anyway. 3. Makes a capture key and, for server code, writes `BUGTAPE_KEY` to `.env` (`--no-env` to skip). It warns when `.env` is not git-ignored. 4. Prints the install steps for that stack, with the release set to the git SHA, because a report without a release cannot tell a regression from old noise. 5. Sends one low-severity `SetupCheckError: BugTape is connected` report with the new key and the current git SHA, and prints the receipt (`--no-check` to skip). An agent connected over MCP can do the same with the `setup_capture` tool. Both need the **Set up capture** permission, which `init`'s sign-in asks for by default. ## Live terminal ```bash npx -y bugtape live ``` Arrows navigate, Space selects, P previews, S and Enter confirm. T changes theme; F filters High and Critical issues. The header names your workspace, repository and project. W chooses a project, L or `:login` signs in inside Live, and M enables optional mouse controls. Only selected issue IDs and project/repository labels pass to the local coding agent. [Full how-to](/docs/terminal-live/). ## Other commands | Command | What it does | |---|---| | `npx -y bugtape login` | Sign in with a code (`--no-browser`, `--name`) | | `npx -y bugtape whoami` | Show the plan and what this sign-in may do | | `npx -y bugtape token` | Print the token, for a bot's secret store | | `npx -y bugtape logout` | Revoke this sign-in and forget it | Every command takes `--json` (one JSON object per line, for agents) and `--api ` for another BugTape address (or `BUGTAPE_API_URL`). The sign-in is stored in `~/.config/bugtape/credentials.json` with mode 0600; `BUGTAPE_TOKEN` in the environment overrides it. Tokens refresh on their own. ## How the sign-in works The CLI uses the OAuth device flow (RFC 8628) with the client `bugtape-cli`. The token it receives is an ordinary BugTape agent token with the permissions you picked and the expiry you chose (30, 90, 180 or 365 days). `logout` revokes it on the server. ## Live inbox `npx -y bugtape live` guides sign-in and project choice before opening the inbox. Shortcut: `npx -y bugtape` with no command opens Live in a terminal. Install once with `npm i -g bugtape`, then type `bugtape`. Scripts, pipes and `--json` still get the help text. Use `--project `, `--project-id ` or `--all-projects` to choose scope. Inside Live use W to choose a project, L or `:login` to sign in, and M or `--mouse` for optional click and wheel controls. Use `--switch` to choose a workspace or `--no-browser` to open the link yourself. `--once` and `--json` require an existing sign-in or `BUGTAPE_TOKEN`; auth errors exit with status 1.