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)
--orchestrate - Enable task orchestration for complex features
--skip-stages TEXT - Skip specific orchestration stages (comma-separated)
--acceptance-criteria TEXT - JSON array of acceptance criteria for task verification (New in v3.3)

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

Ralph Wiggum Options:

--ralph - Enable Ralph Wiggum iterative execution mode
--max-iterations INTEGER - Maximum iterations for Ralph mode (default: 10)

Intelligent Triage Options: (New in v3.3)

--triage - Auto-detect execution mode and generate completion criteria. Analyzes task complexity and codebase capabilities (test frameworks, linters, CI). Auto-enables Ralph when confidence is 60%+.

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"

# Ralph Wiggum mode for iterative execution
sugar add "Build complete auth system" --ralph --max-iterations 15

# Intelligent triage - let Sugar decide (v3.3+)
sugar add "Refactor auth to repository pattern" --triage

See Ralph Wiggum for iterative task execution and intelligent triage documentation.

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 learnings

View Sugar's learning progress log with session summaries and recommendations. (New in v3.3)

sugar learnings [OPTIONS]

Options:

--lines INTEGER - Number of recent lines to show
--sessions INTEGER - Number of recent sessions to show (default: 5)
--clear - Clear the learnings log (creates backup first)

Examples:

# View all learnings
sugar learnings

# View last 3 sessions
sugar learnings --sessions 3

# Clear and start fresh
sugar learnings --clear

The learnings log tracks session summaries, success/failure patterns, task completion rates, and automated recommendations. Stored at .sugar/LEARNINGS.md.

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

sugar orchestrate

View or manage task orchestration status.

sugar orchestrate [TASK_ID] [OPTIONS]

Arguments:

TASK_ID - Task ID to view orchestration details (optional)

Options:

--stages - Show detailed stage information

# View all orchestrating tasks
sugar orchestrate

# View specific task's orchestration status
sugar orchestrate task-abc123

# View stage details
sugar orchestrate task-abc123 --stages

See Task Orchestration for detailed documentation.

sugar context

View accumulated context for an orchestrated task.

sugar context TASK_ID

Shows research findings, implementation plans, subtask results, and files modified across all stages.

sugar mcp serve

Start the Sugar MCP server for Goose and other MCP client integration.

sugar mcp serve [OPTIONS]

Options:

--host TEXT - Host to bind to (default: 0.0.0.0)
--port INTEGER - Port to listen on (default: 8080)
--repo TEXT - Default repository (owner/repo)

Requirements:

# Install with MCP dependencies
pip install sugarai[mcp]

Example:

# Start MCP server
sugar mcp serve --port 8080

# With default repository
sugar mcp serve --repo myorg/myrepo

See MCP Server Integration for configuration with Goose and other clients.

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)

Model Routing (New in v3.3)

Sugar automatically routes tasks to the optimal Claude model based on complexity:

Tier	Task Types	Default Model
`simple`	docs, style, chore	Claude Haiku
`standard`	bug_fix, test, ci	Claude Sonnet
`complex`	feature, refactor, security	Claude Sonnet/Opus

Configure model mappings in .sugar/config.yaml:

sugar:
  models:
    simple: "claude-haiku-3-5-20241022"
    standard: "claude-sonnet-4-20250514"
    complex: "claude-sonnet-4-20250514"
    dynamic_routing: true

Completion Signals (New in v3.3)

Sugar recognizes these completion signal patterns in task output:

Pattern	Example	Description
`<promise>TEXT</promise>`	`<promise>DONE</promise>`	Standard Ralph completion
`<complete>TEXT</complete>`	`<complete>Feature done</complete>`	Explicit completion
`<done reason="...">`	`<done reason="Tests pass"/>`	XML-style completion
`TASK_COMPLETE: desc`	`TASK_COMPLETE: Bug fixed`	Plain text completion

Acceptance Criteria (New in v3.3)

Default acceptance criteria templates are applied per task type. Custom criteria can be specified with --acceptance-criteria:

# Bug fix with test requirements
sugar add "Fix login bug" --type bug_fix \
  --acceptance-criteria '[{type: test_suite, command: pytest tests/auth/}]'

# Feature requiring new test file
sugar add "Add profile endpoint" --type feature \
  --acceptance-criteria '[{type: test_suite}, {type: file_exists}]'

Supported criterion types: test_suite, file_exists, string_in_file, code_change, no_regressions, http_status

Thinking Capture (New in v3.4)

View Claude's reasoning process during task execution for debugging, learning, and verification.

sugar thinking

View or list Claude's thinking logs captured during task execution.

sugar thinking [TASK_ID] [OPTIONS]

Arguments:

TASK_ID - Task ID to view thinking for (required unless using --list)

Options:

--list, -l - List all available thinking logs
--stats, -s - Show thinking statistics only (blocks count, characters, tools considered)

Examples:

# View full thinking log for a task
sugar thinking task-abc123

# View statistics only
sugar thinking task-abc123 --stats

# List all available thinking logs
sugar thinking --list

Thinking logs are stored at .sugar/thinking/<task_id>.md with timestamped blocks showing Claude's reasoning, tool considerations, and decision-making process.

Task Type Management (New in v3.4)

Create custom task types with specific tool restrictions, bash permissions, and execution hooks.

sugar task-type list

List all available task types with their configurations.

sugar task-type list

sugar task-type add

Create a new custom task type.

sugar task-type add TYPE_KEY [OPTIONS]

Options:

--name TEXT - Display name for the task type
--description TEXT - Description of what this task type is for
--agent TEXT - Default agent to use (e.g., tech-lead, qa-engineer)
--emoji TEXT - Emoji icon for the task type
--tier TEXT - Security tier: simple, standard, or complex

# Create a security audit task type
sugar task-type add security_audit \
  --name "Security Audit" \
  --description "Security vulnerability scanning" \
  --agent "security-engineer" \
  --emoji "🔒" \
  --tier complex

sugar task-type show

Show detailed configuration for a task type.

sugar task-type show TYPE_KEY

sugar task-type edit

Modify an existing task type's configuration.

sugar task-type edit TYPE_KEY [OPTIONS]

sugar task-type remove

Remove a custom task type (cannot remove default types).

sugar task-type remove TYPE_KEY

Tool Restrictions (New in v3.4)

Control which tools Claude can use per task type using tier-based security:

Tier	Allowed Tools	Restrictions
`simple`	Read, Write, Edit, Glob, Grep	No Bash, no web access
`standard`	All except WebSearch	WebSearch disabled by default
`complex`	All tools	No restrictions

Bash Permissions (New in v3.4)

Control which bash commands can be executed using fnmatch wildcard patterns:

# Example patterns in task type configuration
bash_permissions:
  - "pytest *"           # Allow pytest with any arguments
  - "git status*"        # Allow git status commands
  - "npm run *"          # Allow npm run scripts
  - "python -m pytest*"  # Allow pytest via python module

Dangerous commands (rm -rf, sudo, etc.) are always blocked regardless of permissions.

Task Hooks (New in v3.4)

Run shell commands before and after task execution with variable substitution:

# Configure hooks per task type
sugar task-type edit feature \
  --pre-hooks '["git stash", "npm install"]' \
  --post-hooks '["pytest tests/", "npm run lint"]'

Available Variables:

${ task_id } - The task ID
${ task_type } - Task type (bug_fix, feature, etc.)
${ title } - Task title
${ priority } - Task priority (1-5)

Behavior:

Pre-hooks run before task execution; failure cancels the task
Post-hooks run after execution; failure marks task for review
Hooks execute in the project directory with configurable timeout