Core Commands
All core CLI commands for the Codified Orchestrator, including ask, version, doctor, plan, task, and more.
cco ask
Ask an ad-hoc query to the model. This is useful for quick questions without creating a task.
Parameters
| Parameter | Type | Description |
|---|---|---|
query |
required | The question or query to ask the model |
--json |
optional | Output response as JSON |
--system-prompt |
optional | Override the system prompt for this query |
--temperature |
optional | Set temperature (0.0-2.0, default: from config) |
--timeout-seconds |
optional | Request timeout in seconds |
Examples
# Ask a simple question cco ask "What is the current branch structure?" # Ask with JSON output cco ask "Explain this error" --json # Ask with custom system prompt cco ask "Act as a security expert" --system-prompt "You are a security auditor" # Ask with specific temperature cco ask "Generate creative alternatives" --temperature 1.2 # Ask with custom timeout cco ask "Complex analysis task" --timeout-seconds 120
Use cco ask for exploratory queries. For focused development tasks that require file changes, use cco task instead.
cco version
Display version information about the CCO installation.
Parameters
| Parameter | Type | Description |
|---|---|---|
--verbose |
optional | Show extended version information including dependencies |
Examples
# Show basic version cco version # Show verbose version with all dependencies cco version --verbose
The --verbose flag shows Python version, installed packages, and configuration paths - useful for debugging installation issues.
cco help
Display all available CCO commands with descriptions. No parameters required.
Parameters
None - this command takes no parameters.
Examples
# Show all available commands cco help
This is equivalent to running cco --help. It shows all top-level commands and their descriptions.
cco doctor
Verify CCO installation and runtime dependencies. Essential for diagnosing setup issues.
Parameters
| Parameter | Type | Description |
|---|---|---|
--repo |
required | Path to the repository to check |
--json |
optional | Output results as JSON |
--verbose |
optional | Show detailed diagnostic information |
--scan-only |
optional | Only scan for issues without proposing fixes |
--validate-refs |
optional | Validate cross-references and links |
Examples
# Basic doctor check cco doctor --repo /path/to/repo # Get JSON output for automation cco doctor --repo /path/to/repo --json # Verbose output with full details cco doctor --repo /path/to/repo --verbose # Only scan, don't propose fixes cco doctor --repo /path/to/repo --scan-only # Validate cross-references cco doctor --repo /path/to/repo --validate-refs
Doctor Exit Codes
cco doctor returns specific exit codes:
0- All checks passed1- Warnings found (non-critical)2- Errors found (critical issues)
cco plan
Plan a task and generate a prompt bundle for review. Creates a detailed execution plan before any changes are made.
Parameters
| Parameter | Type | Description |
|---|---|---|
--repo |
required | Path to the repository |
--task |
required | Task description to plan |
--json |
optional | Output plan as JSON |
--no-redact |
optional | Include full file paths in output (default: redacted) |
--timeout-seconds |
optional | Planning timeout in seconds |
--preflight |
optional | Run pre-flight checks before planning |
Examples
# Plan a task cco plan --repo /path/to/repo --task "Add user authentication" # Get JSON output for tooling cco plan --repo /path/to/repo --task "Fix login bug" --json # Include full paths (no redaction) cco plan --repo /path/to/repo --task "Refactor API" --no-redact # Custom timeout cco plan --repo /path/to/repo --task "Complex migration" --timeout-seconds 180 # Run with pre-flight checks cco plan --repo /path/to/repo --task "Add feature" --preflight
Use cco plan to review what CCO intends to do before committing to execution. This is useful for security-sensitive changes or when you want to verify the approach.
cco task
Execute a task with optional mutation guardrails. This is the primary command for development work.
Parameters
| Parameter | Type | Description |
|---|---|---|
--repo |
required | Path to the repository |
--task |
required | Task description to execute |
--guarded |
optional | Enable mutation guardrails (safe mode) |
--allow-file |
optional | Explicitly allow file mutations (use with guarded) |
--verify-command |
optional | Command to run to verify changes (use with guarded) |
--allow-noop |
optional | Allow no-op tasks (no changes required) |
--no-memory |
optional | Skip AOMA memory recording |
--json |
optional | Output results as JSON |
--no-redact |
optional | Include full file paths in output |
--timeout-seconds |
optional | Task execution timeout in seconds |
--preflight |
optional | Run pre-flight checks before execution |
Examples
# Execute a task (unguarded) cco task --repo /path/to/repo --task "Add logging to API" # Execute with guardrails cco task --repo /path/to/repo --task "Refactor auth module" --guarded # Guarded with verification cco task --repo /path/to/repo --task "Fix tests" --guarded --verify-command "pytest" # Allow file mutations explicitly cco task --repo /path/to/repo --task "Update config" --guarded --allow-file # Allow no-op tasks cco task --repo /path/to/repo --task "Check status" --allow-noop # Skip memory recording cco task --repo /path/to/repo --task "Quick check" --no-memory # JSON output for scripting cco task --repo /path/to/repo --task "Generate report" --json # Full paths in output cco task --repo /path/to/repo --task "Audit code" --no-redact # With pre-flight checks cco task --repo /path/to/repo --task "Deploy" --preflight --timeout-seconds 300
Guardrails Mode
When --guarded is enabled:
- File mutations require explicit
--allow-file - A verification command can be specified with
--verify-command - All changes are recorded in AOMA memory
- Execution is logged for audit purposes
cco task-ready
Check if a task is ready for guarded execution. Validates prerequisites before running cco task --guarded.
Parameters
| Parameter | Type | Description |
|---|---|---|
--repo |
required | Path to the repository |
--task |
required | Task description to check |
--allow-file |
optional | Check if file mutations are permitted |
--verify-command |
optional | Check if verification command is valid |
--allow-noop |
optional | Check no-op allowance |
--json |
optional | Output readiness check as JSON |
Examples
# Check if task is ready cco task-ready --repo /path/to/repo --task "Add feature" # Check with JSON output cco task-ready --repo /path/to/repo --task "Fix bug" --json # Check file mutation readiness cco task-ready --repo /path/to/repo --task "Update code" --allow-file # Check with verify command cco task-ready --repo /path/to/repo --task "Run tests" --verify-command "pytest"
Use cco task-ready as a pre-flight check in scripts or CI pipelines before executing cco task --guarded.
cco task-proof
Run proof cases to validate CCO against fixture repos. Used for regression testing and validation.
Parameters
| Parameter | Type | Description |
|---|---|---|
--profile |
default: direct-minimax | Configuration profile to use |
--case |
default: greeting-source | Specific test case to run |
--suite |
optional | Test suite to run (runs all cases if not specified) |
--json |
optional | Output results as JSON |
--timeout-seconds |
optional | Proof execution timeout in seconds |
Examples
# Run default proof case cco task-proof # Run with specific profile cco task-proof --profile direct-minimax # Run specific test case cco task-proof --case greeting-source # Run entire test suite cco task-proof --suite regression # Run with JSON output cco task-proof --suite integration --json # Custom timeout cco task-proof --case complex-task --timeout-seconds 300
Proof cases are stored in tests/fixtures/sample_repo/. Each case validates specific CCO functionality against known inputs and expected outputs.
cco review
Review uncommitted changes and generate a code review report. Analyzes diffs and provides feedback.
Parameters
| Parameter | Type | Description |
|---|---|---|
--repo |
required | Path to the repository |
--since |
optional | Review changes since this commit/branch/tag |
--json |
optional | Output review as JSON |
Examples
# Review uncommitted changes cco review --repo /path/to/repo # Review changes since last commit cco review --repo /path/to/repo --since HEAD # Review changes since a specific commit cco review --repo /path/to/repo --since abc123 # Review changes since a branch cco review --repo /path/to/repo --since main # JSON output for tooling cco review --repo /path/to/repo --json
The review command analyzes file diffs, checks for common issues, and provides suggestions. It does not modify files.
cco trace
Inspect run artifacts and trace a completed run's execution. Useful for debugging and auditing.
Parameters
| Parameter | Type | Description |
|---|---|---|
run_id |
required | ID of the run to trace |
--json |
optional | Output trace as JSON |
--format |
default: auto | Output format: auto or json |
Examples
# Trace a run (auto format) cco trace run_20240115_143022 # Trace with JSON output cco trace run_20240115_143022 --json # Force JSON format cco trace run_20240115_143022 --format json
Run IDs are stored in ~/.codified-orchestrator/runs/. Use cco trace --list (if available) to see recent runs.
cco cleanup
Clean up old run artifacts to free disk space. Supports dry-run mode for safe exploration.
Parameters
| Parameter | Type | Description |
|---|---|---|
--dry-run |
optional | Show what would be deleted without actually deleting |
--list |
optional | List all run artifacts without deleting |
--force |
optional | Skip confirmation prompt |
--json |
optional | Output as JSON |
Examples
# Preview what would be deleted cco cleanup --dry-run # List all run artifacts cco cleanup --list # Delete with confirmation cco cleanup --force # Delete with JSON output cco cleanup --force --json # Combine list with dry-run cco cleanup --list --dry-run
Caution
Run artifacts are important for debugging and auditing. Use --dry-run first to see what would be deleted.