CLI tool for managing projects on bool.com.

bool follows the Printing Press agent-native CLI conventions: machine-readable output by default when piped, typed exit codes, and standard flags on every command.

npm install -g bool-cli

This installs the bool command globally.

bool auth login      # Paste your API key from the bool.com web UI
bool auth status     # Verify connection
bool auth doctor     # Diagnose auth + API connectivity

Your API key is saved to ~/.config/bool-cli/config.json. You can also set the BOOL_API_KEY environment variable, or pipe a key into login:

echo "$BOOL_API_KEY" | bool auth login

These flags work on every command. They can appear in any position.

Status messages (✔ ✖ ℹ ⚠) go to stderr. Structured data goes to stdout. This means you can pipe JSON without losing log output:

bool list | jq '.[].slug'
bool show my-project --select slug,visibility,url
bool list --csv > bools.csv

Errors are written to stderr in the format ✖ <message> followed by an indented hint pointing at the flag, value, or remediation step — so agents can self-correct in one retry without parsing free-text errors.

The fastest way to get code live — no account or API key required:

bool shipit [directory]

Creates an anonymous Bool and uploads files in one step. On subsequent runs from the same directory, it updates the existing Bool automatically (tracked via .bool/config).

Aliases:

• bool ls for bool list
• bool get / bool info for bool show
• bool rm for bool delete

Slug resolution: When [slug] is omitted, commands read it from the .bool/config file in the current directory. This file is created automatically by shipit, deploy, pull, and show.

bool deploy my-project ./src --message "Added dark mode" --exclude "*.test.js"

• Auto-create: If no slug is provided and .bool/config doesn't exist, a new Bool is created automatically (named after the directory)
• --message / -m — Commit message
• --exclude — Exclude pattern (repeatable)
• Binary files are automatically skipped
• Respects .boolignore files (gitignore syntax)
• Default excludes: .git, node_modules, __pycache__, .DS_Store, .bool
• Live URL: Displayed in output after successful deployment

bool pull my-project ./local-copy --version 3

• --version — Specific version number (default: latest)

Deploy with git push instead of bool deploy:

bool git init                # writes: git remote add bool bool::<slug>
git push bool main           # deploys the pushed commit

bool git init reads the slug from .bool/config in the current directory (or pass --slug <slug>). After that, any git push bool <branch> extracts the pushed commit into a temporary git worktree and runs bool deploy <slug> against it — so the deploy reflects exactly what's committed, not whatever is dirty in your working tree.

The commit message becomes git push <branch> (<sha7>). Authentication uses your existing BOOL_API_KEY / ~/.config/bool-cli/config.json.

Under the hood this ships a git-remote-bool helper that git invokes when it sees the bool::<slug> URL scheme. The helper is installed alongside bool by npm, so anything that has bool on PATH also has the helper on PATH.

bool claim [slug-or-directory] [--secret <secret>]

Transfers an anonymous Bool to your account using the secret stored in .bool/config.

bool skill [directory]

Installs the bool-cli agent skill into the target directory's .agents/ folder so coding agents discover the available CLI surface.

Running shipit, deploy, pull, or show creates a .bool/config file in the project directory. This JSON file stores slug and name so you can run commands without specifying the slug each time:

cd my-project
bool deploy              # slug read from .bool/config
bool show                # slug read from .bool/config
bool versions            # slug read from .bool/config

Add .bool/ to your .gitignore.

bool-cli/
  bin/
    bool.js              # Entry point + global flags
    git-remote-bool.js   # `git push bool main` helper
  src/
    commands/
      auth.js            # auth login, status, doctor
      bools.js           # list, create, show, update, delete, open
      shipit.js          # shipit (anonymous create + deploy)
      versions.js        # versions, deploy, pull
      claim.js           # claim anonymous Bool
      skill.js           # install agent skill
      git.js             # bool git init (configure push-to-deploy remote)
    utils/
      action.js          # action wrapper: typed errors + global flag plumbing
      api.js             # API client → typed CliError on HTTP failure
      config.js          # Global config + project-level .bool/config
      exit.js            # Typed exit codes (Printing Press convention)
      files.js           # File reading, .boolignore, binary detection
      output.js          # Output: auto-JSON on pipe, CSV, --select, --compact