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

butter is a zero-dependency Node script (bin/butter in the ButterStack repo, Node builtins only). Run it directly, or symlink it onto your $PATH:

ln -s /path/to/butter_stack/bin/butter /usr/local/bin/butter

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

To check your authentication status (including remaining token lifetime):

butter auth whoami

To log out:

butter auth logout

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 (CreditService::AI_ACTION_COST); it does not trigger a new build run.

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 http://localhost:3000), --token <token> (explicit override, otherwise read from stored credentials or BUTTERSTACK_API_TOKEN), --json (machine-readable output).

MCP Server

butter mcp starts the ButterStack Model Context Protocol server over stdio, for AI assistant integrations. See the MCP Integration Guide.