Skip to main content

​
Quick Start

The sudocode CLI is a powerful command-line tool 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.
The CLI is the primary interface for sudocode. All operations (create, update, query) are performed through intuitive commands that sync automatically to git-tracked JSONL files.
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