⚠️

You're viewing documentation for Sugar V2 (Legacy)

Sugar V3 with Claude Agent SDK integration is now available. View V3 docs →

Version:
← All V2 Docs

CLI Reference

Complete reference for all Sugar command-line interface commands.

Global Options

sugar [OPTIONS] COMMAND [ARGS]...
  • --config TEXT - Configuration file path (default: .sugar/config.yaml)
  • --help - Show help message and exit

Commands

sugar help

Show comprehensive Sugar help and getting started guide.

sugar help

Displays quick start steps, core commands, configuration basics, and troubleshooting tips.

sugar init

Initialize Sugar in a project directory.

sugar init [OPTIONS]

Options:

  • --project-dir PATH - Project directory to initialize (default: current directory)

Examples:

# Initialize in current directory
sugar init

# Initialize in specific directory
sugar init --project-dir /path/to/my/project

What it creates:

  • .sugar/ directory with configuration and database
  • .sugar/config.yaml - project configuration
  • .sugar/sugar.db - SQLite task database
  • logs/errors/ - Error log monitoring directory

sugar add

Add a new task to the Sugar work queue.

sugar add TITLE [OPTIONS]

Arguments:

  • TITLE - Task title (required)

Standard Options:

  • --type TYPE - Task type: bug_fix, feature, test, refactor, documentation (default: feature)
  • --priority INTEGER - Priority level 1-5 (1=low, 5=urgent, default: 3)
  • --description TEXT - Detailed task description
  • --urgent - Mark as urgent (sets priority to 5)

Complex Data Input Options:

  • --input-file PATH - JSON file containing task data
  • --stdin - Read task data from stdin (JSON format)
  • --json - Parse description as JSON and store in context

Examples:

# Basic task
sugar add "Implement user login"

# Feature with priority
sugar add "Add search functionality" --type feature --priority 4

# Urgent bug fix
sugar add "Fix authentication crash" --type bug_fix --urgent

# With detailed description
sugar add "Refactor API endpoints" --type refactor --description "Clean up REST API structure"

sugar list

List tasks in the Sugar work queue.

sugar list [OPTIONS]

Options:

  • --status TYPE - Filter by status: pending, active, completed, failed, all
  • --type TYPE - Filter by type: bug_fix, feature, test, refactor, documentation, all
  • --limit INTEGER - Number of tasks to show (default: 10)
# List all tasks
sugar list

# List only pending tasks
sugar list --status pending

# List only bug fixes
sugar list --type bug_fix

sugar view

View detailed information about a specific task.

sugar view TASK_ID

Shows complete task details, execution history, context, and results.

sugar update

Update an existing task.

sugar update TASK_ID [OPTIONS]

Options:

  • --title TEXT - Update task title
  • --description TEXT - Update task description
  • --priority INTEGER - Update priority (1-5)
  • --type TYPE - Update task type
  • --status STATUS - Update status
# Update priority
sugar update task-abc123 --priority 5

# Mark as completed
sugar update task-abc123 --status completed

sugar priority

Change the priority of a task with intuitive shortcuts.

sugar priority TASK_ID [OPTIONS]

Options:

  • --priority, -p INTEGER - Set priority (1=highest, 5=lowest)
  • --urgent - Set priority to urgent (1)
  • --high - Set priority to high (2)
  • --normal - Set priority to normal (3)
  • --low - Set priority to low (4)
sugar priority task-abc123 --urgent
sugar priority task-abc123 --high
sugar priority task-abc123 -p 2

sugar remove

Remove a task from the work queue.

sugar remove TASK_ID

sugar status

Show Sugar system status and queue statistics.

sugar status

Shows total tasks, tasks by status, recent activity, and next pending tasks.

sugar run

Start the Sugar autonomous development system.

sugar run [OPTIONS]

Options:

  • --dry-run - Run in simulation mode (no actual changes)
  • --once - Run one cycle and exit
  • --validate - Validate configuration and exit
# Test run (safe mode)
sugar run --dry-run --once

# Validate configuration
sugar run --validate

# Start continuous operation
sugar run

sugar debug

Generate diagnostic information for troubleshooting.

sugar debug [OPTIONS]

Options:

  • --format [json|yaml|text] - Output format (default: json)
  • -o, --output TEXT - Write output to file
  • --include-sensitive - Include sensitive information

Task Status Lifecycle

pending → active → completed
            ↓
         failed
  • pending - Task added but not yet started
  • active - Task currently being executed
  • completed - Task finished successfully
  • failed - Task execution failed (can be retried)

Task Types

  • bug_fix - Fixing bugs, errors, or issues
  • feature - Adding new functionality
  • test - Writing or updating tests
  • refactor - Improving code structure
  • documentation - Writing or updating documentation

Priority Levels

  • 1 - Low priority (nice to have)
  • 2 - Below normal priority
  • 3 - Normal priority (default)
  • 4 - High priority (important)
  • 5 - Urgent priority (critical)

Environment Variables

  • SUGAR_CONFIG - Override default config file path
  • SUGAR_LOG_LEVEL - Set logging level (DEBUG, INFO, WARNING, ERROR)