@secondcontext/btx-cli

Canonical source for the BTX CLI.

This package owns the shared BTX command surface used by:

• standalone coding sessions that should run btx ...
• the BTX desktop app, which bundles this package into code/projects/desktop-app/resources/btx-cli.cjs

Current state

• Source of truth: src/bin.ts and src/runtime-cli.ts
• Desktop bundle is generated from this package
• Public npm package name: @secondcontext/btx-cli
• Public binary name: btx
• --json is the machine-readable mode for commands that return BTX data

Local workflow

npm run build --prefix code/packages/btx-cli
npm run build:btx-cli --prefix code/projects/desktop-app
npm run test:btx-cli --prefix code/projects/desktop-app
npm run validate --prefix code

Local package testing

Build and pack the package:

npm run pack:btx-cli --prefix code

Install the tarball into a clean repo or temp directory:

npm init -y
npm install /absolute/path/to/code/packages/btx-cli/secondcontext-btx-cli-<version>.tgz
./node_modules/.bin/btx --help
./node_modules/.bin/btx status --json

Supported standalone flow

btx status
btx version
btx update
btx login
btx login status
btx logout
btx setup
btx setup codex
btx projects
btx messages list
btx messages send "Shipped the fix"
btx messages send "Can you review this?" --peer [email protected]
btx messages conversations
btx messages members
btx repo link <project-id>
btx setup all
btx context get --json
btx tasks list --json
btx session start --runtime codex --label "Investigate feature X"
btx session checkpoint --type decision --content "Keep desktop and standalone CLI on one contract"
btx session finish --summary "Recorded outcome and next steps"

Recording analysis flow

btx recordings list --date 2026-04-10 --compact --json
btx recordings transcript --date 2026-04-10
btx recordings feedback --date 2026-04-10
btx sessions list --workflow recording_review --recording-id <recording-id>

Auth and repo state

• btx status shows the CLI version, repo linkage, auth source, agent-file setup state, and active session in one place
• btx version shows the current version, the latest npm version seen by the CLI, and whether an update is available
• btx update updates the standalone globally installed npm package when the current install supports self-update
• btx login reuses an existing desktop or standalone auth session when it is still valid, or opens a browser flow that writes ~/.btx/auth-session.json
• btx login status shows whether the CLI is authenticated and whether desktop fallback is enabled
• btx logout clears the standalone CLI session and disables desktop fallback so the CLI stays logged out. Use btx logout --all to also clear the desktop session file
• btx messages list reads BTX project chat, with --peer for direct messages and --conversation for named group chats
• btx messages send sends a BTX project chat message from inline text or piped stdin
• btx setup is the first-run path for sign-in, repo linking, and syncing AGENTS.md, CLAUDE.md, or both
• Auth is read from ~/.btx/auth-session.json, with a fallback to the desktop app auth session store
• The standalone globally installed npm package checks npm for newer versions and auto-updates before running commands when a newer version is available
• Repo linkage is stored in .btx/btx.json
• External session state is stored in ~/.btx/runtime-state.json
• The standalone CLI no longer reads repo-local API_URL env files by default, so running btx inside this monorepo no longer forces the CLI onto http://localhost:3000

First npm publish

Dry-run the publish from the monorepo root:

npm run publish:btx-cli:dry-run --prefix code

Publish from the monorepo root:

npm run publish:btx-cli --prefix code

Expected manual npm steps:

• Log in to npm with an account that can publish under @secondcontext
• Set NPM_TOKEN in code/packages/btx-cli/.env or export it in your shell
• The publish helper in code/scripts/publish-btx-cli.sh creates a temporary npm user config so workspace-local .npmrc files are not needed. Do not run raw npm publish from code/packages/btx-cli
• If npm run publish:btx-cli:dry-run --prefix code succeeds but the real publish returns npm 404 for @secondcontext/btx-cli, the token is authenticated but does not have publish permission for the package. Fix the npm token or package access instead of retrying raw publish commands
• Ensure the @secondcontext scope is configured for public packages
• If you want an open-source package, add a real LICENSE file before publishing and replace the current UNLICENSED marker in package.json