bool-cli

Using bool-cli

CLI tool for managing projects on Bool.com. Requires Node.js >=18.

Prerequisites

1. Install: npm install -g bool-cli 2. Authenticate: Set BOOL_API_KEY env var, or run bool auth login interactively 3. Verify: Run bool auth status to confirm the connection

The API key is saved to ~/.config/bool-cli/config.json. The BOOL_API_KEY environment variable takes precedence over the saved config.

Important: Non-Interactive Commands

The bool auth login and bool bools delete commands are interactive (they prompt for input). When using them from an agent:

Commands Reference

Authentication

bool auth login          # Interactive: prompts for API key
bool auth status         # Check auth + API health (non-interactive)

Managing Bools

bool bools list [count]        # List Bools (default: 5)
bool bools create        # Create a new Bool
bool bools info [slug]         # Show Bool details + latest version info
bool bools update [slug] --name "New Name" --description "desc" --visibility public
bool bools delete [slug] -y    # Delete a Bool (always use -y to skip prompt)
bool bools open [slug]         # Open Bool in browser
bool bools visibility [slug]         # Show current visibility
bool bools visibility [slug] --set private    # Change visibility

Visibility options: private, team, unlisted, public

Versions & Deployment

bool versions [slug]                           # List version history
bool deploy [slug] [dir] -m "commit message"   # Deploy local files (auto-creates Bool if needed)
bool pull [slug] [dir] --version N             # Download files locally

Quick Ship (Anonymous Bools)

Ship a project without needing an API key:

bool shipit [directory]                        # Create anonymous Bool + deploy
bool shipit --slug  -m "update message"  # Update existing anonymous Bool
bool shipit --name "My Project"                # Set a custom name

The shipit command stores the slug and secret in .bool/config so subsequent runs in the same directory automatically update the same Bool.

JSON Output

All commands support --json for machine-readable output. Always use --json when you need to parse output programmatically.

bool bools list --json
bool bools info my-project --json
bool versions my-project --json

Project Config (.bool/config)

When you deploy, pull, or shipit in a directory, bool-cli stores project metadata in .bool/config:

{
  "slug": "my-project",
  "name": "My Project",
  "secret": "optional_anonymous_secret"
}

This allows you to omit the [slug] argument on subsequent commands when working in the same directory. For example:

# First time: specify slug explicitly
bool deploy my-project ./src -m "Initial deploy"
After that, run from the same directory and slug is read from .bool/config
bool deploy -m "Another deploy"
bool versions
bool bools info

Add .bool/ to your .gitignore to keep secrets local.

Common Workflows

Create and deploy a new Bool (Option A: explicit)

bool bools create "My Project"
note the slug from the output, e.g. "my-project"
bool deploy my-project ./src -m "Initial deploy"

Create and deploy a new Bool (Option B: auto-create)

# Deploy without a slug—a new Bool is created automatically
bool deploy ./src -m "Initial deploy"

This creates a Bool named after the directory and displays the live URL.

Quick anonymous ship (no API key needed)

bool shipit ./my-project
outputs: https://.bool01.com
subsequent updates from same directory:
bool shipit ./my-project -m "Updated version"

Pull, edit, and redeploy

bool pull my-project ./my-project
... make changes to files in ./my-project/ ...
bool deploy my-project ./my-project -m "Updated files"

Check what's deployed

bool bools info my-project            # See latest version summary
bool versions my-project              # See full version history
bool pull my-project ./tmp            # Download current files to inspect

Manage visibility

bool bools visibility my-project                 # Show current visibility
bool bools visibility my-project --set private    # Make it private
bool bools visibility my-project --set public     # Make it public

Deploy a specific subdirectory with exclusions

bool deploy my-project ./src --exclude "*.test.js" --exclude "*.spec.js" -m "Production build"

Deploy Behavior

Pull Behavior

Environment Variables

| Variable | Purpose | Default | |----------|---------|---------| | BOOL_API_KEY | API key (overrides saved config) | — | | BOOL_API_URL | API base URL | https://bool.com/api | | BOOL_BASE_URL | Base URL for shipit | https://bool.com |

Error Handling

Tips

1. Install: npm install -g bool-cli 2. Authenticate: Set BOOL_API_KEY env var, or run bool auth login interactively 3. Verify: Run bool auth status to confirm the connection

The API key is saved to ~/.config/bool-cli/config.json. The BOOL_API_KEY environment variable takes precedence over the saved config.