BugTape docs

BugTape CLI

npx -y bugtape: connect an agent with one click, set up capture in a repo.

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

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.

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:

export BUGTAPE_TOKEN="$(npx -y bugtape token)"

Set up capture in a repository

npx -y bugtape init

Detects the stack: browser app, Node.js, Python, Cloudflare Workers, iOS or any other server (--platform to choose).
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 <id> to use a project that is there, or --new-project to create one anyway.
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.
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.
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

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.

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 <url> 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.

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 <name>, --project-id <uuid> 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.