CLI Reference¶

Cub provides a comprehensive command-line interface for managing autonomous AI coding sessions. This reference covers all available commands, their options, and usage patterns.

Command Overview¶

Commands are organized into logical groups based on their function:

Key Commands¶

The primary commands for everyday use:

Status Commands¶

Commands for monitoring and inspecting runs:

Task Commands¶

Commands for working with individual tasks:

Epic Commands¶

Commands for managing epics and branches:

Install Commands¶

Commands for managing your Cub installation:

Capture Commands¶

Commands for managing idea captures:

Global Options¶

These options are available on all commands:

Debug Mode¶

Enable verbose logging with the --debug flag:

cub run --debug
cub status --debug

Debug mode outputs additional information:

• Configuration loading details
• Harness detection and version
• Task backend initialization
• File paths and session IDs

Command Notation¶

Throughout this reference, commands use the following notation:

Examples¶

# Required argument
cub run --task <task-id>

# Optional arguments
cub monitor [session-id]

# Multiple options
cub run --harness claude --once --stream

Environment Variables¶

Cub respects several environment variables for configuration:

Core Variables¶

Budget Variables¶

Harness Variables¶

Path Variables¶

Example Usage¶

# Run with specific harness
CUB_HARNESS=claude cub run

# Set budget limits
CUB_BUDGET=10.00 CUB_MAX_ITERATIONS=50 cub run

# Use different config directory
CUB_CONFIG_DIR=/custom/path cub init --global

# Enable debug mode via environment
CUB_DEBUG=true cub status

Exit Codes¶

Cub commands return meaningful exit codes:

Scripting Example¶

#!/bin/bash
cub run --once

case $? in
    0) echo "Task completed successfully" ;;
    1) echo "Task failed or error occurred" ;;
    130) echo "Interrupted by user" ;;
esac

Configuration Precedence¶

When the same setting is available in multiple places, Cub uses this precedence (highest to lowest):

1. Command-line flags - cub run --harness claude
2. Environment variables - CUB_HARNESS=claude
3. Project config - .cub.json or .cub/config.json
4. Global config - ~/.config/cub/config.json
5. Built-in defaults

Example¶

# CLI flag takes precedence over everything
CUB_HARNESS=codex cub run --harness claude
# Uses claude (CLI flag wins)

Shell Completion¶

Enable tab completion for your shell:

# Add to ~/.bashrc
eval "$(_CUB_COMPLETE=bash_source cub)"

# Add to ~/.zshrc
eval "$(_CUB_COMPLETE=zsh_source cub)"

# Add to ~/.config/fish/completions/cub.fish
_CUB_COMPLETE=fish_source cub | source

Getting Help¶

Every command supports the --help flag:

cub --help           # General help
cub run --help       # Help for run command
cub prep --help      # Help for prep command

For troubleshooting, see:

• Common Issues
• Error Reference
• FAQ