ButterStack ButterStack CLI (butter) Guide
The ButterStack CLI (butter) is your command-line interface to manage tasks, builds, assets, and overall project operations right from your terminal.
Installation
Install the CLI globally from npm:
npm install -g butterstack-cli
This puts butter on your $PATH. Source is on GitHub at ButterStack/butterstack-cli.
Authentication
Before using the CLI, you must log in to your ButterStack account.
butter auth login
This opens your default web browser to authorize the CLI (browser-based OAuth 2.0 PKCE loopback). Once approved, an access token is exchanged (via /api/v1/cli/token_exchange) and saved to ~/.config/butterstack/credentials.json. Issued tokens expire after 90 days.
By default, login requests the full CLI permission set. To mint a narrower token, pass --scope:
butter auth login --scope read-only
butter auth login --scope read:projects,read:builds
The full set and the read-only preset both include read:changes, which the changes commands need. A token issued before read:changes joined the CLI scope set does not carry it and gets a 403 insufficient_scope; run butter auth login again to reissue.
To check your authentication status (including remaining token lifetime):
butter auth whoami
To log out:
butter auth logout
Managing Projects
List projects:
# List projects you can access
butter projects list
Show a project:
# Show a project's name, type, task/build/asset counts, pending asset count, and its latest build
butter projects show <id>
Add --json for machine-readable output.
Managing Tasks
List tasks:
butter tasks list --project <id> --state in_progress
Create a task:
butter tasks create "Fix character collision" --project <id> --type bug --priority high
Managing Builds
List recent builds:
butter builds list --project <id>
Trigger an AI failure investigation on a failed build:
butter builds investigate <build_id> --project <id>
Requires a token with write:builds and spends account credits for the AI investigation; it does not trigger a new build run.
Browsing Changes
Changes are commits and changelists across the git, Perforce, and Lore rails.
List changes:
butter changes list --project <id>
butter changes list --project <id> --source lore --since 2026-09-01 --limit 20
Filters: --source lore|git|perforce, --since <date>, --identifier <id>, --orphaned (include ghost commits, excluded by default), --limit <n>, and --after <cursor> for the next page (the command prints it when there is one).
Show a change, or find the change a build came from:
butter changes show <change_id> --project <id>
butter changes show <commit> --project <id>
changes show takes the id that changes list prints, or a commit reference: a full git SHA, a Perforce build’s p4-<n>, or lore-<n>. Pass it the Commit: value from butter builds show to get the change behind that build. Matching is exact, and an all-digit argument is always read as a change id; look up a bare Perforce changelist number with changes list --identifier <n>.
Requires read:changes. Add --json to either command for machine-readable output.
Managing Assets
List assets:
butter assets list --project <id> --pending
Approve an asset:
butter assets approve <asset_id> --project <id> --comment "Looks good"
Deny an asset:
butter assets deny <asset_id> --project <id> --reason "Texture resolution too high"
Options and Configuration
Most commands support a --project flag to specify the project context, or fall back to defaultProject in ~/.config/butterstack/config.json.
butter tasks list --project my-game-proj
Other global flags: --host <url> (API host, default https://www.butterstack.com), --token <token> (explicit override, otherwise read from stored credentials or BUTTERSTACK_API_TOKEN), --json (machine-readable output).
MCP Server
The Model Context Protocol server for AI assistant integrations is a separate package, butterstack-mcp, not a subcommand of this CLI. See the MCP Integration Guide.
butter mcp install writes the ButterStack MCP entry into detected AI clients (OpenCode, Claude Desktop, Cursor), each in its own config schema.
# Detect and configure whichever supported clients are installed
butter mcp install
Flags --opencode, --claude, and --cursor limit it to one client and create the file if missing.
# Limit to a single client, creating its config file if it doesn't exist
butter mcp install --claude
--dry-run shows changes without writing.
# Preview changes without writing them
butter mcp install --dry-run
Re-running is safe: only the butterstack entry is touched. A config file containing comments is never rewritten; the command prints the entry and the file path to paste it into instead.
Claude Code registers servers itself:
# Register the ButterStack MCP server with Claude Code
claude mcp add butterstack -- npx -y butterstack-mcp
See the MCP Integration Guide for more.