Skip to main content

​
Quick Start

The sudocode CLI is a powerful command-line tool that agents and users can utilize for managing specs, issues, relationships, and feedback in your git-native context management system. It provides a complete interface for spec-driven development with AI agents.
Users are not expected to use most of the CLI commands directly, except for project initialization and configuration. However, advanced users and integrators may find the CLI useful for scripting and automation.
1

Install sudocode

npm install -g sudocode
2

Initialize a project

cd your-project
sudocode init
3

Create your first spec

sudocode spec create "Authentication System" --priority 1
4

Create an implementation issue

sudocode issue create "Implement login endpoint" --priority 1
sudocode link ISSUE-001 SPEC-001 --type implements

​
Command Categories

The CLI is organized into logical command groups:

Project Setup

Initialize and configure sudocode projects
  • init - Initialize .sudocode directory

Spec Management

Create and manage specifications

Issue Management

Create and manage work items

Relationships

Model dependencies and connections
  • link - Create typed relationships
  • add-ref - Add inline references

Feedback System

Provide anchored feedback on specs

Query & Planning

Find ready work and track progress
  • ready - Show unblocked issues
  • blocked - Show blocked issues
  • status - Project status overview
  • stats - Project statistics

Sync & Export

Manage data synchronization
  • sync - Sync markdown ↔ JSONL ↔ SQLite
  • export - Export to various formats
  • import - Import external data

​
Common Command Patterns

​
Creating Entities

All create commands follow a similar pattern: 
# Basic creation
sudocode [entity] create "<title>" [options]

# With common options
sudocode spec create "My Spec" --priority 1 --tags "auth,security"
sudocode issue create "My Issue" --priority 0 --assignee "alice"

​
Listing and Filtering

List commands support powerful filtering: 
# List all entities
sudocode [entity] list

# Filter by various criteria
sudocode spec list --priority 1 --grep "auth"
sudocode issue list --status open --assignee "alice" --limit 100

​
Viewing Details

Show commands display complete entity information: 
sudocode spec show SPEC-001
sudocode issue show ISSUE-042
Output includes:
  • Entity metadata (title, priority, status, timestamps)
  • Content/description
  • Relationships (incoming and outgoing)
  • Tags
  • Feedback (for specs)

​
Updating Entities

Update commands support partial updates: 
# Update specific fields
sudocode spec update SPEC-001 --priority 0 --title "New Title"
sudocode issue update ISSUE-001 --status in_progress --assignee "bob"

​
Global Options

These options work with all commands:
​
--json
boolean
Output results as JSON for scripting
sudocode --json issue list --status open
Useful for programmatic processing with tools like jq.
​
--help
boolean
Display help for any command
sudocode --help
sudocode spec create --help
​
--version
boolean
Display sudocode version
sudocode --version

​
Command Reference

​
Project Setup

Initialize a new sudocode project in the current directory.
sudocode init
Creates .sudocode/ directory with database, JSONL files, and configuration.View full documentation →

​
Spec Commands

Create a new specification document.
sudocode spec create "<title>" [-p <priority>] [-d <description>] [--parent <id>] [--tags <tags>]
View full documentation →
List all specs with optional filtering.
sudocode spec list [-p <priority>] [-g <search>] [--archived <bool>] [--limit <num>]
View full documentation →
Display detailed information about a spec.
sudocode spec show <spec-id>
View full documentation →
Update an existing spec.
sudocode spec update <spec-id> [--title <title>] [-p <priority>] [-d <description>]
View full documentation →
Delete one or more specs.
sudocode spec delete <spec-id> [<spec-id>...]
View full documentation →

​
Issue Commands

Create a new issue.
sudocode issue create "<title>" [-p <priority>] [-d <description>] [-a <assignee>] [--parent <id>]
View full documentation →
List all issues with filtering.
sudocode issue list [-s <status>] [-a <assignee>] [-p <priority>] [-g <search>]
View full documentation →
Display detailed information about an issue.
sudocode issue show <issue-id>
View full documentation →
Update an existing issue.
sudocode issue update <issue-id> [-s <status>] [-p <priority>] [-a <assignee>]
View full documentation →
Close one or more issues.
sudocode issue close <issue-id> [<issue-id>...]
View full documentation →
Delete one or more issues (soft or hard delete).
sudocode issue delete <issue-id> [--hard]
View full documentation →

​
Relationship Commands

Add an inline reference to a spec or issue.
sudocode add-ref <entity-id> <reference-id> [--line <num>] [--text <search>]
View full documentation →

​
Feedback Commands

Add anchored feedback from an issue to a spec.
sudocode feedback add <issue-id> <spec-id> --content "<feedback>" [--type <type>] [--line <num>]
Feedback types: comment, suggestion, requestView full documentation →
List feedback with filtering.
sudocode feedback list [--spec <id>] [--issue <id>] [--status <status>]
View full documentation →
Display detailed information about feedback.
sudocode feedback show <feedback-id>
View full documentation →
Dismiss feedback as resolved.
sudocode feedback dismiss <feedback-id> [--comment "<reason>"]
View full documentation →

​
Query & Planning Commands

Show issues ready to work on (unblocked, open).
sudocode ready
Returns issues with no blocking dependencies, sorted by priority.View full documentation →
Show blocked issues and what’s blocking them.
sudocode blocked
View full documentation →
Display project status overview.
sudocode status
View full documentation →
Display project statistics.
sudocode stats
View full documentation →

​
Sync & Export Commands

Synchronize between markdown files, JSONL, and SQLite.
sudocode sync [--watch] [--direction <direction>]
View full documentation →
Export specs and issues to various formats.
sudocode export --format <format> --output <path>
View full documentation →
Import data from external sources.
sudocode import --input <path> [--format <format>]
View full documentation →

​
Typical Workflows

​
Starting a New Feature

1

Create a spec

sudocode spec create "User Dashboard" --priority 1 --tags "frontend,ux"
2

Break into implementation issues

sudocode issue create "Build dashboard layout" --priority 1
sudocode issue create "Add data visualizations" --priority 1
sudocode issue create "Implement filters" --priority 2
3

Link issues to spec

sudocode link ISSUE-001 SPEC-001 --type implements
sudocode link ISSUE-002 SPEC-001 --type implements
sudocode link ISSUE-003 SPEC-001 --type implements
4

Model dependencies

sudocode link ISSUE-001 ISSUE-002 --type blocks
5

Find ready work

sudocode ready

​
Agent Workflow

1

Query for ready work

sudocode ready
2

Claim an issue

sudocode issue update ISSUE-001 --status in_progress --assignee "agent-backend"
3

Implement the feature

Write code, run tests, commit changes
4

Provide feedback if needed

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Token expiration policy not specified" \
  --type request \
  --line 42
5

Close the issue

sudocode issue close ISSUE-001

​
Daily Standup

1

What's in progress?

sudocode issue list --status in_progress
2

What's blocked?

sudocode blocked
3

What's ready to work on?

sudocode ready
4

Project statistics

sudocode stats

​
Tips & Best Practices

The --json flag makes it easy to integrate sudocode into scripts:
# Get all open issue IDs
sudocode --json issue list --status open | jq -r '.[] | .id'

# Count critical specs
sudocode --json spec list --priority 0 | jq 'length'
If your shell supports completion, enable it for faster command entry:
# Example for bash
complete -C sudocode sudocode
Create shell aliases for frequently-used commands:
alias sc='sudocode'
alias scr='sudocode ready'
alias scb='sudocode blocked'
alias scil='sudocode issue list'
sudocode is git-native. Commit JSONL files regularly:
# After creating/updating entities
git add .sudocode/*.jsonl .sudocode/config.json
git commit -m "Update specs and issues"
The --grep flag supports fuzzy searching:
# Find all auth-related work
sudocode issue list --grep "auth"
sudocode spec list --grep "authentication"

​
Error Handling

Common errors and solutions:
Solution: Run sudocode init in your project directory
Solution: Verify the ID with spec list or issue list
Solution: Close other sudocode processes or wait for sync to complete
Solution: Use valid values (priority: 0-4, status: open/in_progress/blocked/needs_review/closed)

​
Next Steps

Initialize Your Project

Get started with sudocode init

Create Your First Spec

Learn about spec creation

Manage Issues

Create actionable work items

MCP Integration

Integrate with AI agents

​
Additional Resources

Core Concepts

Learn about specs, issues, and relationships

Workflows

See common development workflows

GitHub

View source code and contribute