CLI Overview - sudocode

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.

Install sudocode

npm install -g sudocode

Initialize a project

cd your-project
sudocode init

Create your first spec

sudocode spec create "Authentication System" --priority 1

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

spec create - Create new specs
spec list - List and filter specs
spec show - View spec details
spec update - Update existing specs
spec delete - Delete specs

Issue Management

Create and manage work items

issue create - Create new issues
issue list - List and filter issues
issue show - View issue details
issue update - Update existing issues
issue close - Close completed issues
issue delete - Delete issues

Relationships

Model dependencies and connections

link - Create typed relationships
add-ref - Add inline references

Feedback System

Provide anchored feedback on specs

feedback add - Add feedback to specs
feedback list - List feedback
feedback show - View feedback details
feedback dismiss - Dismiss feedback

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:

boolean

Output results as JSON for scripting

sudocode --json issue list --status open

Useful for programmatic processing with tools like jq.

boolean

Display help for any command

sudocode --help
sudocode spec create --help

boolean

Display sudocode version

sudocode --version

Command Reference

Project Setup

sudocode init

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

sudocode spec create

Create a new specification document.

sudocode spec create "<title>" [-p <priority>] [-d <description>] [--parent <id>] [--tags <tags>]

​Quick Start

​Command Categories

Project Setup

Spec Management

Issue Management

Relationships

Feedback System

Query & Planning

Sync & Export

​Common Command Patterns

​Creating Entities

​Listing and Filtering

​Viewing Details

​Updating Entities

​Global Options

​Command Reference

​Project Setup

​Spec Commands

​Issue Commands

​Relationship Commands

​Feedback Commands

​Query & Planning Commands

​Sync & Export Commands

​Typical Workflows

​Starting a New Feature

​Agent Workflow

​Daily Standup

​Tips & Best Practices

​Error Handling

​Next Steps

Initialize Your Project

Create Your First Spec

Manage Issues

MCP Integration

​Additional Resources

Core Concepts

Workflows

GitHub

Quick Start

Command Categories

Common Command Patterns

Creating Entities

Listing and Filtering

Viewing Details

Updating Entities

Global Options

Command Reference

Project Setup

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Planning Commands

Sync & Export Commands

Typical Workflows

Starting a New Feature

Agent Workflow

Daily Standup

Tips & Best Practices

Error Handling

Next Steps

Additional Resources