> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Command-line interface for managing sudocode projects

## 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.

<Note>
  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.
</Note>

<Steps>
  <Step title="Install sudocode">
    ```bash theme={null}
    npm install -g sudocode
    ```
  </Step>

  <Step title="Initialize a project">
    ```bash theme={null}
    cd your-project
    sudocode init
    ```
  </Step>

  <Step title="Create your first spec">
    ```bash theme={null}
    sudocode spec create "Authentication System" --priority 1
    ```
  </Step>

  <Step title="Create an implementation issue">
    ```bash theme={null}
    sudocode issue create "Implement login endpoint" --priority 1
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>
</Steps>

## Command Categories

The CLI is organized into logical command groups:

<CardGroup cols={2}>
  <Card title="Project Setup" icon="folder-tree">
    Initialize and configure sudocode projects

    * [`init`](/cli/init) - Initialize .sudocode directory
  </Card>

  <Card title="Spec Management" icon="file-lines">
    Create and manage specifications

    * [`spec create`](/cli/spec-create) - Create new specs
    * [`spec list`](/cli/spec-list) - List and filter specs
    * [`spec show`](/cli/spec-show) - View spec details
    * [`spec update`](/cli/spec-update) - Update existing specs
    * [`spec delete`](/cli/spec-delete) - Delete specs
  </Card>

  <Card title="Issue Management" icon="list-check">
    Create and manage work items

    * [`issue create`](/cli/issue-create) - Create new issues
    * [`issue list`](/cli/issue-list) - List and filter issues
    * [`issue show`](/cli/issue-show) - View issue details
    * [`issue update`](/cli/issue-update) - Update existing issues
    * [`issue close`](/cli/issue-close) - Close completed issues
    * [`issue delete`](/cli/issue-delete) - Delete issues
  </Card>

  <Card title="Relationships" icon="diagram-project">
    Model dependencies and connections

    * [`link`](/cli/link) - Create typed relationships
    * [`add-ref`](/cli/add-ref) - Add inline references
  </Card>

  <Card title="Feedback System" icon="comments">
    Provide anchored feedback on specs

    * [`feedback add`](/cli/feedback-add) - Add feedback to specs
    * [`feedback list`](/cli/feedback-list) - List feedback
    * [`feedback show`](/cli/feedback-show) - View feedback details
    * [`feedback dismiss`](/cli/feedback-dismiss) - Dismiss feedback
  </Card>

  <Card title="Query & Planning" icon="magnifying-glass">
    Find ready work and track progress

    * [`ready`](/cli/ready) - Show unblocked issues
    * [`blocked`](/cli/blocked) - Show blocked issues
    * [`status`](/cli/status) - Project status overview
    * [`stats`](/cli/stats) - Project statistics
  </Card>

  <Card title="Sync & Export" icon="arrows-rotate">
    Manage data synchronization

    * [`sync`](/cli/sync) - Sync markdown ↔ JSONL ↔ SQLite
    * [`export`](/cli/export) - Export to various formats
    * [`import`](/cli/import) - Import external data
  </Card>
</CardGroup>

## Common Command Patterns

### Creating Entities

All create commands follow a similar pattern:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
# 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:

<ParamField path="--json" type="boolean">
  Output results as JSON for scripting

  ```bash theme={null}
  sudocode --json issue list --status open
  ```

  Useful for programmatic processing with tools like `jq`.
</ParamField>

<ParamField path="--help" type="boolean">
  Display help for any command

  ```bash theme={null}
  sudocode --help
  sudocode spec create --help
  ```
</ParamField>

<ParamField path="--version" type="boolean">
  Display sudocode version

  ```bash theme={null}
  sudocode --version
  ```
</ParamField>

## Command Reference

### Project Setup

<AccordionGroup>
  <Accordion title="sudocode init" icon="folder-plus">
    Initialize a new sudocode project in the current directory.

    ```bash theme={null}
    sudocode init
    ```

    Creates `.sudocode/` directory with database, JSONL files, and configuration.

    [View full documentation →](/cli/init)
  </Accordion>
</AccordionGroup>

### Spec Commands

<AccordionGroup>
  <Accordion title="sudocode spec create" icon="plus">
    Create a new specification document.

    ```bash theme={null}
    sudocode spec create "<title>" [-p <priority>] [-d <description>] [--parent <id>] [--tags <tags>]
    ```

    [View full documentation →](/cli/spec-create)
  </Accordion>

  <Accordion title="sudocode spec list" icon="list">
    List all specs with optional filtering.

    ```bash theme={null}
    sudocode spec list [-p <priority>] [-g <search>] [--archived <bool>] [--limit <num>]
    ```

    [View full documentation →](/cli/spec-list)
  </Accordion>

  <Accordion title="sudocode spec show" icon="eye">
    Display detailed information about a spec.

    ```bash theme={null}
    sudocode spec show <spec-id>
    ```

    [View full documentation →](/cli/spec-show)
  </Accordion>

  <Accordion title="sudocode spec update" icon="pen-to-square">
    Update an existing spec.

    ```bash theme={null}
    sudocode spec update <spec-id> [--title <title>] [-p <priority>] [-d <description>]
    ```

    [View full documentation →](/cli/spec-update)
  </Accordion>

  <Accordion title="sudocode spec delete" icon="trash">
    Delete one or more specs.

    ```bash theme={null}
    sudocode spec delete <spec-id> [<spec-id>...]
    ```

    [View full documentation →](/cli/spec-delete)
  </Accordion>
</AccordionGroup>

### Issue Commands

<AccordionGroup>
  <Accordion title="sudocode issue create" icon="plus">
    Create a new issue.

    ```bash theme={null}
    sudocode issue create "<title>" [-p <priority>] [-d <description>] [-a <assignee>] [--parent <id>]
    ```

    [View full documentation →](/cli/issue-create)
  </Accordion>

  <Accordion title="sudocode issue list" icon="list">
    List all issues with filtering.

    ```bash theme={null}
    sudocode issue list [-s <status>] [-a <assignee>] [-p <priority>] [-g <search>]
    ```

    [View full documentation →](/cli/issue-list)
  </Accordion>

  <Accordion title="sudocode issue show" icon="eye">
    Display detailed information about an issue.

    ```bash theme={null}
    sudocode issue show <issue-id>
    ```

    [View full documentation →](/cli/issue-show)
  </Accordion>

  <Accordion title="sudocode issue update" icon="pen-to-square">
    Update an existing issue.

    ```bash theme={null}
    sudocode issue update <issue-id> [-s <status>] [-p <priority>] [-a <assignee>]
    ```

    [View full documentation →](/cli/issue-update)
  </Accordion>

  <Accordion title="sudocode issue close" icon="circle-check">
    Close one or more issues.

    ```bash theme={null}
    sudocode issue close <issue-id> [<issue-id>...]
    ```

    [View full documentation →](/cli/issue-close)
  </Accordion>

  <Accordion title="sudocode issue delete" icon="trash">
    Delete one or more issues (soft or hard delete).

    ```bash theme={null}
    sudocode issue delete <issue-id> [--hard]
    ```

    [View full documentation →](/cli/issue-delete)
  </Accordion>
</AccordionGroup>

### Relationship Commands

<AccordionGroup>
  <Accordion title="sudocode link" icon="link">
    Create a typed relationship between entities.

    ```bash theme={null}
    sudocode link <from-id> <to-id> --type <relationship-type>
    ```

    Relationship types: `blocks`, `implements`, `depends-on`, `references`, `related`, `discovered-from`

    [View full documentation →](/cli/link)
  </Accordion>

  <Accordion title="sudocode add-ref" icon="at">
    Add an inline reference to a spec or issue.

    ```bash theme={null}
    sudocode add-ref <entity-id> <reference-id> [--line <num>] [--text <search>]
    ```

    [View full documentation →](/cli/add-ref)
  </Accordion>
</AccordionGroup>

### Feedback Commands

<AccordionGroup>
  <Accordion title="sudocode feedback add" icon="comment-plus">
    Add anchored feedback from an issue to a spec.

    ```bash theme={null}
    sudocode feedback add <issue-id> <spec-id> --content "<feedback>" [--type <type>] [--line <num>]
    ```

    Feedback types: `comment`, `suggestion`, `request`

    [View full documentation →](/cli/feedback-add)
  </Accordion>

  <Accordion title="sudocode feedback list" icon="list">
    List feedback with filtering.

    ```bash theme={null}
    sudocode feedback list [--spec <id>] [--issue <id>] [--status <status>]
    ```

    [View full documentation →](/cli/feedback-list)
  </Accordion>

  <Accordion title="sudocode feedback show" icon="eye">
    Display detailed information about feedback.

    ```bash theme={null}
    sudocode feedback show <feedback-id>
    ```

    [View full documentation →](/cli/feedback-show)
  </Accordion>

  <Accordion title="sudocode feedback dismiss" icon="check">
    Dismiss feedback as resolved.

    ```bash theme={null}
    sudocode feedback dismiss <feedback-id> [--comment "<reason>"]
    ```

    [View full documentation →](/cli/feedback-dismiss)
  </Accordion>
</AccordionGroup>

### Query & Planning Commands

<AccordionGroup>
  <Accordion title="sudocode ready" icon="circle-check">
    Show issues ready to work on (unblocked, open).

    ```bash theme={null}
    sudocode ready
    ```

    Returns issues with no blocking dependencies, sorted by priority.

    [View full documentation →](/cli/ready)
  </Accordion>

  <Accordion title="sudocode blocked" icon="ban">
    Show blocked issues and what's blocking them.

    ```bash theme={null}
    sudocode blocked
    ```

    [View full documentation →](/cli/blocked)
  </Accordion>

  <Accordion title="sudocode status" icon="chart-simple">
    Display project status overview.

    ```bash theme={null}
    sudocode status
    ```

    [View full documentation →](/cli/status)
  </Accordion>

  <Accordion title="sudocode stats" icon="chart-bar">
    Display project statistics.

    ```bash theme={null}
    sudocode stats
    ```

    [View full documentation →](/cli/stats)
  </Accordion>
</AccordionGroup>

### Sync & Export Commands

<AccordionGroup>
  <Accordion title="sudocode sync" icon="arrows-rotate">
    Synchronize between markdown files, JSONL, and SQLite.

    ```bash theme={null}
    sudocode sync [--watch] [--direction <direction>]
    ```

    [View full documentation →](/cli/sync)
  </Accordion>

  <Accordion title="sudocode export" icon="file-export">
    Export specs and issues to various formats.

    ```bash theme={null}
    sudocode export --format <format> --output <path>
    ```

    [View full documentation →](/cli/export)
  </Accordion>

  <Accordion title="sudocode import" icon="file-import">
    Import data from external sources.

    ```bash theme={null}
    sudocode import --input <path> [--format <format>]
    ```

    [View full documentation →](/cli/import)
  </Accordion>
</AccordionGroup>

## Typical Workflows

### Starting a New Feature

<Steps>
  <Step title="Create a spec">
    ```bash theme={null}
    sudocode spec create "User Dashboard" --priority 1 --tags "frontend,ux"
    ```
  </Step>

  <Step title="Break into implementation issues">
    ```bash theme={null}
    sudocode issue create "Build dashboard layout" --priority 1
    sudocode issue create "Add data visualizations" --priority 1
    sudocode issue create "Implement filters" --priority 2
    ```
  </Step>

  <Step title="Link issues to spec">
    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    sudocode link ISSUE-002 SPEC-001 --type implements
    sudocode link ISSUE-003 SPEC-001 --type implements
    ```
  </Step>

  <Step title="Model dependencies">
    ```bash theme={null}
    sudocode link ISSUE-001 ISSUE-002 --type blocks
    ```
  </Step>

  <Step title="Find ready work">
    ```bash theme={null}
    sudocode ready
    ```
  </Step>
</Steps>

### Agent Workflow

<Steps>
  <Step title="Query for ready work">
    ```bash theme={null}
    sudocode ready
    ```
  </Step>

  <Step title="Claim an issue">
    ```bash theme={null}
    sudocode issue update ISSUE-001 --status in_progress --assignee "agent-backend"
    ```
  </Step>

  <Step title="Implement the feature">
    Write code, run tests, commit changes
  </Step>

  <Step title="Provide feedback if needed">
    ```bash theme={null}
    sudocode feedback add ISSUE-001 SPEC-001 \
      --content "Token expiration policy not specified" \
      --type request \
      --line 42
    ```
  </Step>

  <Step title="Close the issue">
    ```bash theme={null}
    sudocode issue close ISSUE-001
    ```
  </Step>
</Steps>

### Daily Standup

<Steps>
  <Step title="What's in progress?">
    ```bash theme={null}
    sudocode issue list --status in_progress
    ```
  </Step>

  <Step title="What's blocked?">
    ```bash theme={null}
    sudocode blocked
    ```
  </Step>

  <Step title="What's ready to work on?">
    ```bash theme={null}
    sudocode ready
    ```
  </Step>

  <Step title="Project statistics">
    ```bash theme={null}
    sudocode stats
    ```
  </Step>
</Steps>

## Tips & Best Practices

<AccordionGroup>
  <Accordion title="Use JSON output for scripting">
    The `--json` flag makes it easy to integrate sudocode into scripts:

    ```bash theme={null}
    # 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'
    ```
  </Accordion>

  <Accordion title="Leverage tab completion">
    If your shell supports completion, enable it for faster command entry:

    ```bash theme={null}
    # Example for bash
    complete -C sudocode sudocode
    ```
  </Accordion>

  <Accordion title="Use aliases for common commands">
    Create shell aliases for frequently-used commands:

    ```bash theme={null}
    alias sc='sudocode'
    alias scr='sudocode ready'
    alias scb='sudocode blocked'
    alias scil='sudocode issue list'
    ```
  </Accordion>

  <Accordion title="Combine with git workflows">
    sudocode is git-native. Commit JSONL files regularly:

    ```bash theme={null}
    # After creating/updating entities
    git add .sudocode/*.jsonl .sudocode/config.json
    git commit -m "Update specs and issues"
    ```
  </Accordion>

  <Accordion title="Use grep for quick searches">
    The `--grep` flag supports fuzzy searching:

    ```bash theme={null}
    # Find all auth-related work
    sudocode issue list --grep "auth"
    sudocode spec list --grep "authentication"
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

Common errors and solutions:

<AccordionGroup>
  <Accordion title="Error: sudocode not initialized">
    **Solution:** Run `sudocode init` in your project directory
  </Accordion>

  <Accordion title="Error: Entity not found">
    **Solution:** Verify the ID with `spec list` or `issue list`
  </Accordion>

  <Accordion title="Error: Database locked">
    **Solution:** Close other sudocode processes or wait for sync to complete
  </Accordion>

  <Accordion title="Error: Invalid priority/status value">
    **Solution:** Use valid values (priority: 0-4, status: open/in\_progress/blocked/needs\_review/closed)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Initialize Your Project" icon="rocket" href="/cli/init">
    Get started with `sudocode init`
  </Card>

  <Card title="Create Your First Spec" icon="file-lines" href="/cli/spec-create">
    Learn about spec creation
  </Card>

  <Card title="Manage Issues" icon="list-check" href="/cli/issue-create">
    Create actionable work items
  </Card>

  <Card title="MCP Integration" icon="plug" href="/mcp/setup-claude-code">
    Integrate with AI agents
  </Card>
</CardGroup>

## Additional Resources

<CardGroup cols={3}>
  <Card title="Core Concepts" icon="book" href="/concepts/specs">
    Learn about specs, issues, and relationships
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/workflows/spec-driven-development">
    See common development workflows
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/sudocode-ai/sudocode">
    View source code and contribute
  </Card>
</CardGroup>