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 <slug> commands are interactive (they prompt for input). When using them from an agent:

• Auth: Set the BOOL_API_KEY environment variable instead of running bool auth login
• Delete: Always pass -y / --yes to skip the confirmation prompt: bool bools delete <slug> -y

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 <name>       # 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 <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://<slug>.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

• bool deploy recursively reads the directory and uploads all text files
• Auto-create Bool: If no slug is provided (and no .bool/config exists), a new Bool is created automatically, named after the directory
• Live URL: The live deployment URL is displayed in the output after successful deployment
• Binary files (images, PDFs, archives, fonts, etc.) are automatically skipped
• Default excludes: .git, node_modules, __pycache__, .DS_Store, .bool
• Custom excludes: Use --exclude <pattern> (repeatable) for additional patterns
• .boolignore: If a .boolignore file exists in the deploy directory, it is respected (gitignore syntax)
• File paths in the payload are relative to the deploy directory

Pull Behavior

• bool pull <slug> downloads files to ./<slug>/ by default
• Specify a custom output directory: bool pull <slug> ./my-dir
• Pull a specific version: bool pull <slug> --version 3
• Creates subdirectories as needed

Environment Variables

Error Handling

• All errors print to stderr with a non-zero exit code
• API errors surface the server's error message (e.g., "Bool not found")
• If no API key is configured, commands fail with: No API key configured. Run: bool auth login

Tips

• Use bool bools list --json | jq '.[].slug' to get all slugs for scripting
• The Bool slug (not name) is the identifier used in all commands
• After bool bools create, the slug is derived from the name (e.g., "My Project" -> my-project)
• Use bool bools info <slug> --json to get the latest version number programmatically
• The live URL for any Bool is https://<slug>.bool01.com