Submit
All skills
Skillintermediate

@sudocode-ai/cli

Command-line interface for [sudocode](https://github.com/sudocode-ai/sudocode) - Git-native spec and issue management for AI-assisted software development.

Claude Code Knowledge Pack7/10/2026

Overview

@sudocode-ai/cli

Command-line interface for sudocode - Git-native spec and issue management for AI-assisted software development.

Overview

The sudocode CLI provides a complete toolkit for managing specifications and issues in a git-native workflow. All data is stored in .sudocode/ as JSONL files that can be versioned alongside your code, with a local SQLite cache for fast queries.

Features

  • Git-native workflow - All specs and issues stored as JSONL in .sudocode/
  • Fast local cache - SQLite database for instant queries
  • Bidirectional sync - Export to markdown for editing, import back to database
  • Relationship tracking - Link specs and issues with typed relationships
  • Cross-references - Add inline Obsidian-style [[ID]] references in markdown
  • Anchored feedback - Attach issue feedback to specific lines in specs
  • Priority management - 5-level priority system (0-4)
  • Flexible queries - Filter by status, assignee, priority, or grep content
  • Watch mode - Auto-sync markdown changes to database

Installation

npm install -g @sudocode-ai/cli

Or install the meta-package that includes the CLI:

npm install -g sudocode

Authentication

Overview

Sudocode supports multiple AI service credentials for remote deployment. Configure at least one service to enable Codespace deployment.

Supported Services

  1. Claude Code (Available now)
  2. LLM Key (OpenAI/LiteLLM) - Coming soon
  3. LiteLLM (Custom LLM configs) - Coming soon

Setup Claude Code

Interactive Setup (Recommended)

Run the interactive authentication flow:

sudocode auth claude

This will:

  1. Check for Claude CLI installation
  2. Launch OAuth flow in your browser
  3. Store the token securely
  4. Verify configuration

Non-Interactive Setup

If you already have a token:

sudocode auth claude --token sk-ant-api03-xxxxx

Check Authentication Status

View all configured credentials:

sudocode auth status

Output:

Authentication Status:

Claude Code: ✓ Configured
  Token: sk-ant-api03-***************************xxx

LLM Key: ✗ Not configured
  Run: sudocode auth llm --key <key> (coming soon)

LiteLLM: ✗ Not configured
  Run: sudocode auth litellm (coming soon)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Configured: 1/3 services
Storage: ~/.config/sudocode/user_credentials.json

✓ Ready for remote deployment

Clear Credentials

Remove all stored credentials:

sudocode auth clear

Or skip confirmation:

sudocode auth clear --force

How It Works

  1. Configure one or more services locally
  2. Credentials stored in ~/.config/sudocode/user_credentials.json (600 permissions)
  3. When deploying to Codespace, all credentials are passed to the deployment system
  4. AI services are configured in the remote environment
  5. Sudocode server can use any configured service for executions

Security

  • Credentials stored in ~/.config/sudocode/ with restrictive permissions (600)
  • File is never committed to git (user-level config)
  • Tokens are masked in command output
  • Atomic file writes prevent corruption

Troubleshooting

Claude CLI Not Found

If you see "claude CLI not found":

npm install -g @anthropic-ai/claude-cli

Invalid Token Format

Tokens must:

  • Start with sk-ant-
  • Be at least 20 characters long
  • Contain only alphanumeric characters, dashes, and underscores

Permission Errors

If you get permission errors:

# Check permissions
ls -la ~/.config/sudocode/user_credentials.json

# Fix permissions
chmod 600 ~/.config/sudocode/user_credentials.json

File Corrupted

If credentials file is corrupted, clear and reconfigure:

sudocode auth clear --force
sudocode auth claude

Quick Start

# Initialize sudocode in your project
sudocode init

# Create a spec
sudocode spec create "User authentication system" -p 4

# Create an issue
sudocode issue create "Implement login endpoint" -p 3 -a alice

# Link issue to spec
sudocode link ISSUE-1 SPEC-1 --type implements

# Show ready work
sudocode ready

# Update issue status
sudocode issue update ISSUE-1 --status in_progress

Commands

Initialization

sudocode init [options]

Initialize .sudocode/ directory structure with database, JSONL files, and configuration.

Options:

  • --spec-prefix <prefix> - ID prefix for specs (default: "SPEC")
  • --issue-prefix <prefix> - ID prefix for issues (default: "ISSUE")

Creates:

  • .sudocode/cache.db - SQLite database (gitignored)
  • .sudocode/specs.jsonl - Spec storage (versioned)
  • .sudocode/issues.jsonl - Issue storage (versioned)
  • .sudocode/config.json - Metadata config (versioned)
  • .sudocode/.gitignore - Ignores cache and markdown files

Spec Management

# Create a new spec
sudocode spec create <title> [options]
  -p, --priority <0-4>        Priority level (default: 2)
  -d, --description <text>    Description
  --design <text>             Design notes
  --file-path <path>          Custom markdown file path
  --parent <id>               Parent spec ID
  --tags <tags>               Comma-separated tags

# List specs
sudocode spec list [options]
  -p, --priority <priority>   Filter by priority
  -g, --grep <query>          Search title or content
  --limit <num>               Limit results (default: 50)

# Show spec details
sudocode spec show <id>

# Delete specs
sudocode spec delete <id...>

Issue Management

# Create a new issue
sudocode issue create <title> [options]
  -p, --priority <0-4>        Priority level (default: 2)
  -d, --description <text>    Description
  -a, --assignee <name>       Assignee username
  --parent <id>               Parent issue ID
  --tags <tags>               Comma-separated tags

# List issues
sudocode issue list [options]
  -s, --status <status>       Filter by status (open, in_progress, blocked, needs_review, closed)
  -a, --assignee <assignee>   Filter by assignee
  -p, --priority <priority>   Filter by priority
  -g, --grep <query>          Search title, description, or content
  --limit <num>               Limit results (default: 50)

# Show issue details
sudocode issue show <id>

# Update issue
sudocode issue update <id> [options]
  -s, --status <status>       New status
  -p, --priority <priority>   New priority
  -a, --assignee <assignee>   New assignee
  --title <title>             New title
  --description <desc>        New description

# Close issues
sudocode issue close <id...> [options]
  -r, --reason <text>         Reason for closing

# Delete issues
sudocode issue delete <id...> [options]
  --hard                      Permanently delete (default: close)

Relationships

# Link entities
sudocode link <from> <to> [options]
  -t, --type <type>           Relationship type (default: "references")

Relationship types:

  • blocks - From blocks To (e.g., ISSUE-1 blocks ISSUE-2)
  • implements - From implements To (e.g., ISSUE-1 implements SPEC-1)
  • references - From references To (general reference)
  • depends-on - From depends on To
  • related - General relation
  • discovered-from - Issue discovered from spec feedback

Cross-References

Add inline references to specs or issues using Obsidian-style [[ID]] syntax.

# Add reference to a spec or issue
sudocode spec add-ref <entity-id> <reference-id> [options]
sudocode issue add-ref <entity-id> <reference-id> [options]
  -l, --line <number>         Line number to insert reference
  -t, --text <text>           Text to search for insertion point
  --display <text>            Display text for reference (creates [[ID|text]])
  --type <type>               Relationship type (creates [[ID]]{ type })
  --format <format>           Format: inline or newline (default: inline)
  --position <position>       Position: before or after (default: after)

Notes:

  • Either --line or --text is required (mutually exclusive)
  • References use Obsidian-style syntax: [[ISSUE-001]]
  • Display text: [[ISSUE-001|OAuth Implementation]]
  • With relationship: [[SPEC-002]]{ implements }
  • Combined: [[SPEC-002|Auth Spec]]{ blocks }
  • Inline format adds reference on same line with surrounding text
  • Newline format adds reference on its own line

Examples:

# Add reference inline after line 45
sudocode spec add-ref SPEC-001 ISSUE-003 --line 45

# Add reference after specific text
sudocode spec add-ref SPEC-001 ISSUE-003 --text "Requirements:"

# Add with display text
sudocode spec add-ref SPEC-001 ISSUE-003 --line 45 --display "OAuth implementation"

# Add with relationship type
sudocode issue add-ref ISSUE-001 SPEC-002 --text "Design" --type implements

# Add on new line before text
sudocode spec add-ref SPEC-001 ISSUE-004 --text "## Tasks" --format newline --position before

Query Commands

# Show ready work (no blockers)
sudocode ready

# Show blocked issues
sudocode blocked

Status & Stats

# Quick project status
sudocode status [options]
  -v, --verbose               Show detailed status

# Detailed statistics
sudocode stats

Feedback Management

Feedback allows issues to reference specific locations in specs with anchored comments.

# Add feedback to a spec
sudocode feedback add <issue-id> <spec-id> [options]
  -l, --line <number>         Line number in spec
  -t, --text <text>           Text to search for anchor
  --type <type>               Feedback type (comment, suggestion, request)
  -c, --content <text>        Feedback content (required)
  -a, --agent <name>          Agent name

# List feedback
sudocode feedback list [options]
  -i, --issue <id>            Filter by issue ID
  -s, --spec <id>             Filter by spec ID
  -t, --type <type>           Filter by type
  --status <status>           Filter by status (open, acknowledged, resolved, wont_fix)
  --limit <num>               Limit results (default: 50)

# Show feedback details
sudocode feedback show <id>

# Dismiss feedback
sudocode feedback dismiss <id> [options]
  -c, --comment <text>        Optional comment

# List stale feedback anchors
sudocode feedback stale

# Manually relocate stale anchor
sudocode feedback relocate <id> --line <number>

Sync & Export

# Sync between markdown, JSONL, and database
sudocode sync [options]
  --watch                     Watch for changes and auto-sync
  --from-markdown             Sync from markdown to database
  --to-markdown               Sync from database to markdown

# Export database to JSONL
sudocode export [options]
  -o, --output <dir>          Output directory (default: ".sudocode")

# Import JSONL to database
sudocode import [options]
  -i, --input <dir>           Input directory (default: ".sudocode")

Global Options

--db <path>                   Custom database path (auto-discovers by default)
--json                        Output in JSON format

Remote Deployment

Overview

Sudocode supports deploying your project to remote development environments for AI-assisted development. Currently supports GitHub Codespaces, with additional providers planned for future releases.

What is Remote Deployment?

Remote deployment creates an isolated cloud environment where:

  • Your project code is cloned from git
  • Sudocode server runs automatically
  • AI agents can execute tasks remotely
  • Changes are committed back to git branches
  • Multiple deployments can run in parallel

Use Cases:

  • Run long-running AI tasks without keeping your laptop running
  • Enable team members to review AI execution progress
  • Execute tasks in a clean, reproducible environment
  • Scale AI assistance across multiple issues simultaneously

Supported Providers:

  • GitHub Codespaces - Fully supported (requires GitHub CLI)
  • Coder - Coming soon

Prerequisites

Before deploying to remote environments, ensure you have:

  1. GitHub CLI - Required for Codespaces deployment

    # macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
sudo apt install gh  # Debian/Ubuntu

  2. Git Repository - Your project must be:

    • Committed to a git repository
    • Pushed to GitHub
    • You have write access to the repository

  3. Claude Authentication - Configure at least one AI service

    sudocode auth claude

    See the Authentication section for details.

  4. GitHub Authentication - Login to GitHub CLI

    gh auth login

Quick Start

Deploy your current project to a Codespace:

# From your project directory
cd /path/to/your/project
sudocode init  # If not already initialized

# Authenticate with Claude
sudocode auth claude

# Deploy to Codespaces
sudocode remote codespaces spawn

The deployment process will:

  1. Detect your git repository and branch
  2. Create a new GitHub Codespace
  3. Clone your code and install dependencies
  4. Start the sudocode server
  5. Configure AI credentials
  6. Print access URLs

Output:

✓ Created Codespace: sudocode-myproject-ab12cd
✓ Installing dependencies...
✓ Starting sudocode server...
✓ Deployment complete

URLs:
  Workspace: https://myorg-myproject-ab12cd.github.dev
  Sudocode:  https://myorg-myproject-ab12cd-3000.app.github.dev
  SSH:       gh cs ssh -c sudocode-myproject-ab12cd

Command Reference

All remote deployment commands follow the pattern:

sudocode remote <provider> <command> [options]

Where <provider> is currently codespaces (with coder coming soon).

Spawn Deployment

Create a new remote deployment from your current project.

sudocode remote codespaces spawn [options]

Options:

  • --repo <owner/repo> - Override repository (default: auto-detected from git remote)
  • --branch <name> - Override branch (default: current branch or from config)
  • --port <number> - Server port (default: 3000 or from config)
  • --machine <type> - Machine type (default: "basicLinux32gb" or from config)
  • --idle-timeout <minutes> - Idle timeout in minutes (default: 4320 or from config)
  • --keep-alive <hours> - Keep-alive duration in hours (default: 72 or from config)
  • --retention <days> - Retention period in days (default: 14 or from config)

Examples:

# Deploy with defaults
sudocode remote codespaces spawn

# Deploy specific branch
sudocode remote codespaces spawn --branch feature/new-auth

# Deploy with custom port
sudocode remote codespaces spawn --port 8080

# Deploy with larger machine
sudocode remote codespaces spawn --machine "premiumLinux"

# Deploy with shorter timeout for quick tasks
sudocode remote codespaces spawn --idle-timeout 30 --keep-alive 2

# Deploy different repository
sudocode remote codespaces spawn --repo myorg/other-project --branch main

# Deploy with all custom options
sudocode remo