@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 remote codespaces spawn \
  --branch develop \
  --port 5000 \
  --machine "standardLinux32gb" \
  --idle-timeout 1440 \
  --keep-alive 48 \
  --retention 7

Auto-Detection:

• Repository is detected from git remote origin
• Branch is detected from current git HEAD
• Configuration defaults from .sudocode/spawn-config.json are applied
• If repository has uncommitted changes, you'll be prompted to commit or stash them

List Deployments

List all active deployments for the specified provider.

sudocode remote <provider> list

Examples:

# List Codespaces deployments
sudocode remote codespaces list

# JSON output
sudocode remote codespaces list --json

Output:

Active Deployments (codespaces):

┌─────────────────────────┬──────────────────┬─────────────┬──────────┐
│ ID                      │ Repository       │ Branch      │ Status   │
├─────────────────────────┼──────────────────┼─────────────┼──────────┤
│ codespace-ab12cd        │ myorg/myproject  │ main        │ running  │
│ codespace-xy98zf        │ myorg/myproject  │ feature/new │ running  │
│ codespace-mn34kl        │ myorg/other      │ develop     │ starting │
└─────────────────────────┴──────────────────┴─────────────┴──────────┘

To view details: sudocode remote codespaces status <id>
To stop a deployment: sudocode remote codespaces stop <id>

Empty State:

No active deployments found for codespaces.

Spawn with: sudocode remote codespaces spawn

JSON Output:

sudocode remote codespaces list --json

[
  {
    "id": "codespace-ab12cd",
    "name": "deployment-ab12cd",
    "provider": "codespaces",
    "status": "running",
    "git": {
      "owner": "myorg",
      "repo": "myproject",
      "branch": "main"
    },
    "urls": {
      "workspace": "https://myorg-myproject-ab12cd.github.dev",
      "sudocode": "https://myorg-myproject-ab12cd-3000.app.github.dev",
      "ssh": "gh cs ssh -c codespace-ab12cd"
    },
    "createdAt": "2026-01-14T10:30:00Z",
    "keepAliveHours": 72,
    "idleTimeout": 4320
  }
]

Deployment Status

Get detailed information about a specific deployment.

sudocode remote <provider> status <id>

Arguments:

• <id> - Deployment ID (from list output)

Examples:

# Get status
sudocode remote codespaces status codespace-ab12cd

# JSON output
sudocode remote codespaces status codespace-ab12cd --json

Output:

Deployment: codespace-ab12cd
Provider: codespaces

Status: running
Repository: myorg/myproject
Branch: main
Created: 2026-01-14T10:30:00Z

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

Configuration:
  Port: 3000
  Machine: basicLinux32gb
  Keep-alive: 72 hours
  Idle timeout: 4320 minutes
  Retention: 14 days

Status Values:

• running - Deployment is active and ready
• starting - Deployment is being provisioned
• stopped - Deployment has been stopped
• stopping - Deployment is shutting down
• failed - Deployment failed to start

Error Handling:

If deployment is not found:

✗ Deployment not found: codespace-invalid

List deployments with: sudocode remote codespaces list

JSON Output:

sudocode remote codespaces status codespace-ab12cd --json

{
  "id": "codespace-ab12cd",
  "name": "deployment-ab12cd",
  "provider": "codespaces",
  "status": "running",
  "git": {
    "owner": "myorg",
    "repo": "myproject",
    "branch": "main"
  },
  "urls": {
    "workspace": "https://myorg-myproject-ab12cd.github.dev",
    "sudocode": "https://myorg-myproject-ab12cd-3000.app.github.dev",
    "ssh": "gh cs ssh -c codespace-ab12cd"
  },
  "createdAt": "2026-01-14T10:30:00Z",
  "keepAliveHours": 72,
  "idleTimeout": 4320
}

Stop Deployment

Stop and delete a running deployment.

sudocode remote <provider> stop <id> [options]

Arguments:

• <id> - Deployment ID (from list output)

Options:

• -f, --force - Skip confirmation prompt

Examples:

# With confirmation prompt
sudocode remote codespaces stop codespace-ab12cd

# Skip confirmation
sudocode remote codespaces stop codespace-ab12cd --force

# JSON output
sudocode remote codespaces stop codespace-ab12cd --force --json

Confirmation Prompt:

⚠  Stop deployment codespace-ab12cd?
  This will delete the codespace and all uncommitted changes.
  
  Continue? (y/N):

Output:

Stopping deployment...

✓ Deployment stopped: codespace-ab12cd

JSON Output:

{
  "success": true,
  "id": "codespace-ab12cd"
}

Warning: Stopping a deployment:

• Deletes the Codespace immediately
• Loses all uncommitted changes in the Codespace
• Cannot be undone
• Committed changes on git branches are preserved

Error Handling:

If deployment is not found:

✗ Deployment not found: codespace-invalid

List deployments with: sudocode remote codespaces list

Configuration Management

Manage deployment configuration for a provider.

sudocode remote <provider> config [options]

Options:

• --port <number> - Set server port (1024-65535)
• --idle-timeout <minutes> - Set idle timeout in minutes (min: 1)
• --keep-alive <hours> - Set keep-alive duration in hours (min: 1)
• --retention <days> - Set retention period in days (min: 1)
• --machine <type> - Set machine type/size
• --reset - Reset to default configuration (cannot be combined with other options)

Examples:

# View current configuration
sudocode remote codespaces config

# Update individual values
sudocode remote codespaces config --port 8080
sudocode remote codespaces config --idle-timeout 60
sudocode remote codespaces config --keep-alive 24

# Update multiple values at once
sudocode remote codespaces config \
  --port 8080 \
  --idle-timeout 60 \
  --keep-alive 24 \
  --machine "premiumLinux"

# Reset to defaults
sudocode remote codespaces config --reset

# JSON output
sudocode remote codespaces config --json

View Configuration Output:

{
  "provider": "codespaces",
  "port": 3000,
  "idleTimeout": 4320,
  "keepAliveHours": 72,
  "machine": "basicLinux32gb",
  "retentionPeriod": 14
}

Update Output:

✓ Spawn configuration updated for codespaces
  Port: 8080
  Idle timeout: 60 minutes
  Keep-alive: 24 hours
  Machine: premiumLinux

Updated: .sudocode/spawn-config.json

Reset Output:

✓ Spawn configuration reset to defaults for codespaces
{
  "provider": "codespaces",
  "port": 3000,
  "idleTimeout": 4320,
  "keepAliveHours": 72,
  "machine": "basicLinux32gb",
  "retentionPeriod": 14
}

Updated: .sudocode/spawn-config.json

Configuration File Location:

• File: .sudocode/spawn-config.json
• Git tracked (shared across team)
• Created automatically with defaults on first use

Validation Rules:

• Port: 1024-65535 (non-privileged ports only)
• Idle Timeout: Minimum 1 minute
• Keep-Alive: Minimum 1 hour
• Retention Period: Minimum 1 day
• Machine: Non-empty string

Error Examples:

Invalid port:

✗ Port must be between 1024 and 65535

Cannot combine --reset:

Error: Cannot combine --reset with other options

Unknown provider:

✗ Unknown provider 'azure'
Supported providers: codespaces, coder

Common Workflows

Quick Task Deployment

For short-lived AI tasks (e.g., bug fixes, small features):

# Configure aggressive cleanup
sudocode remote codespaces config \
  --idle-timeout 30 \
  --keep-alive 2 \
  --retention 1

# Deploy and run task
sudocode remote codespaces spawn --branch feature/quick-fix

# List deployments
sudocode remote codespaces list

# Stop when done
sudocode remote codespaces stop <id> --force

Long-Running Project Deployment

For extended AI assistance sessions or demos:

# Configure longer retention
sudocode remote codespaces config \
  --idle-timeout 1440 \
  --keep-alive 168 \
  --retention 30 \
  --machine "premiumLinux"

# Deploy
sudocode remote codespaces spawn --branch main

# Check status
sudocode remote codespaces status <id>

Multi-Issue Parallel Execution

Deploy multiple branches simultaneously:

# Deploy multiple branches for different issues
sudocode remote codespaces spawn --branch feature/auth-system
sudocode remote codespaces spawn --branch feature/payment-flow
sudocode remote codespaces spawn --branch bugfix/memory-leak

# Monitor all deployments
sudocode remote codespaces list

# Check individual progress
sudocode remote codespaces status <id-1>
sudocode remote codespaces status <id-2>
sudocode remote codespaces status <id-3>

# Stop completed ones
sudocode remote codespaces stop <id-1> --force

Team Collaboration

Share deployment URLs with team members:

# Deploy with team-friendly configuration
sudocode remote codespaces config --machine "basicLinux32gb"

# Deploy
sudocode remote codespaces spawn

# Share URLs from output
# Team members can access:
# - Workspace URL for viewing code in browser
# - Sudocode URL for monitoring AI execution in UI
# - SSH command for terminal access

Configuration for Different Use Cases

Development environment (quick iterations):

sudocode remote codespaces config \
  --idle-timeout 30 \
  --keep-alive 4 \
  --retention 1

Production/long-running environment:

sudocode remote codespaces config \
  --idle-timeout 1440 \
  --keep-alive 168 \
  --retention 30 \
  --machine "premiumLinux"

Cost optimization (minimal resources):

sudocode remote codespaces config \
  --idle-timeout 15 \
  --keep-alive 1 \
  --retention 1 \
  --machine "basicLinux32gb"

How It Works

Deployment Lifecycle

1. Preparation

   • Detect git repository and current branch
   • Load configuration from .sudocode/deploy-config.json
   • Validate prerequisites (gh CLI, git remote, auth)
   • Apply command-line option overrides

2. Provisioning

   • Create GitHub Codespace via gh codespace create
   • Apply machine type, timeout, and retention settings
   • Wait for Codespace to become available

3. Initialization

   • Clone repository and checkout specified branch
   • Install dependencies (npm install)
   • Build sudocode packages
   • Transfer user credentials securely

4. Server Startup

   • Start sudocode server on configured port
   • Configure AI services from transferred credentials
   • Expose ports for web access
   • Register URLs

5. Ready

   • Print access URLs
   • Codespace is ready for AI execution
   • Server accepts API requests
   • Frontend UI is accessible

Credential Transfer

User credentials (configured via sudocode auth) are securely transferred:

1. Credentials read from ~/.config/sudocode/user_credentials.json on local machine
2. Transferred to Codespace using secure GitHub APIs
3. Written to ~/.config/sudocode/user_credentials.json in Codespace
4. File permissions set to 600 (owner read/write only)
5. Used by sudocode server for AI service authentication

Security Notes:

• Credentials are never committed to git
• Transfer uses GitHub's secure Codespace APIs
• File permissions prevent unauthorized access
• Credentials are isolated per Codespace

Auto-Cleanup

Codespaces are automatically cleaned up based on configuration:

• Idle Timeout: Codespace stops after configured idle period (default: 72 hours)
• Retention Period: Stopped Codespace is deleted after retention period (default: 14 days)
• Keep-Alive: Active connections reset idle timer

Manual cleanup:

sudocode remote codespaces stop <id>

Usage Examples

Example 1: Deploy Current Branch

# Working on feature branch
git checkout feature/user-auth
git add .
git commit -m "WIP: implementing OAuth"
git push origin feature/user-auth

# Deploy this branch
sudocode remote codespaces spawn

Output:

✓ Detected repository: myorg/myproject
✓ Detected branch: feature/user-auth
✓ Creating Codespace...
✓ Codespace created: codespace-xyz123
✓ Installing dependencies...
✓ Starting server...
✓ Deployment complete

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

Example 2: Deploy Different Branch

# From any branch, deploy main
sudocode remote codespaces spawn --branch main

Example 3: Custom Configuration

# Deploy with custom settings for intensive task
sudocode remote codespaces spawn \
  --branch feature/refactor-db \
  --machine "premiumLinux" \
  --keep-alive 48 \
  --idle-timeout 480

Example 4: Monitor Multiple Deployments

# Deploy multiple branches
sudocode remote codespaces spawn --branch feature/api-v2
sudocode remote codespaces spawn --branch bugfix/cors-issue
sudocode remote codespaces spawn --branch feature/new-ui

# List all
sudocode remote codespaces list

# Check each status
sudocode remote codespaces status <id-1>
sudocode remote codespaces status <id-2>
sudocode remote codespaces status <id-3>

# Stop completed ones
sudocode remote codespaces stop <id-1> --force

Example 5: JSON Automation

# Deploy and capture ID
DEPLOY_ID=$(sudocode remote codespaces spawn --json | jq -r '.id')

# Monitor status
while true; do
  STATUS=$(sudocode remote codespaces status $DEPLOY_ID --json | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "running" ]; then
    break
  fi
  sleep 5
done

# Get Sudocode URL
SUDOCODE_URL=$(sudocode remote codespaces status $DEPLOY_ID --json | jq -r '.urls.sudocode')
echo "Sudocode UI: $SUDOCODE_URL"

Example 6: Full Lifecycle

# 1. Configure for your needs
sudocode remote codespaces config \
  --port 8080 \
  --machine "standardLinux32gb" \
  --idle-timeout 120 \
  --keep-alive 24

# 2. Deploy
sudocode remote codespaces spawn --branch feature/new-feature

# 3. Monitor
sudocode remote codespaces list
sudocode remote codespaces status <id>

# 4. Access via SSH to check logs
gh cs ssh -c <codespace-name>
tail -f ~/.sudocode/server.log

# 5. Clean up when done
sudocode remote codespaces stop <id> --force

Troubleshooting

GitHub CLI Not Found

Error:

Error: gh CLI not found. Please install GitHub CLI first.

Solution:

# macOS
brew install gh

# Windows  
winget install GitHub.cli

# Linux
sudo apt install gh

# Verify installation
gh --version

Not Authenticated with GitHub

Error:

Error: Not authenticated with GitHub

Solution:

# Login to GitHub
gh auth login

# Select GitHub.com
# Choose HTTPS or SSH
# Authenticate in browser

No Git Repository

Error:

Error: Not a git repository

Solution:

# Initialize git repository
git init

# Add remote
git remote add origin https://github.com/myorg/myproject.git

# Commit and push
git add .
git commit -m "Initial commit"
git push -u origin main

Uncommitted Changes

Error:

Error: Repository has uncommitted changes

Solution:

# Option 1: Commit changes
git add .
git commit -m "Work in progress"
git push

# Option 2: Stash changes
git stash
sudocode remote codespaces spawn
git stash pop

# Option 3: Deploy different branch
sudocode remote codespaces spawn --branch main

No Authentication Configured

Error:

Error: No AI credentials configured

Solution:

# Configure Claude
sudocode auth claude

# Verify
sudocode auth status

# Should show "Claude Code: ✓ Configured"

Port Already in Use

Error:

Error: Port 3000 is already in use

Solution:

# Use different port
sudocode remote codespaces spawn --port 8080

# Or update config
sudocode remote codespaces config --port 8080
sudocode remote codespaces spawn

Deployment Not Found

Error:

✗ Deployment not found: codespace-abc123

Solution:

# List all deployments
sudocode remote codespaces list

# Use correct ID from list
sudocode remote codespaces status <correct-id>

Codespace Creation Failed

Error:

Error: Failed to create Codespace

Common Causes:

• GitHub API rate limit exceeded
• Repository not accessible
• Insufficient permissions
• GitHub Codespaces not enabled for repository

Solution:

# Check GitHub authentication
gh auth status

# Verify repository access
gh repo view myorg/myproject

# Check Codespaces status
gh codespace list

# Try again with specific repo
sudocode remote codespaces spawn --repo myorg/myproject

Deployment Stuck in Starting

Issue: Deployment shows "starting" status for extended period.

Solution:

# Check detailed status
sudocode remote codespaces status <id>

# If stuck > 5 minutes, stop and retry
sudocode remote codespaces stop <id> --force
sudocode remote codespaces spawn

Cannot Access Sudocode URL

Issue: Sudocode URL returns connection error.

Solutions:

# 1. Check deployment status
sudocode remote codespaces status <id>
# Status should be "running"

# 2. Wait for port forwarding
# Codespace port forwarding can take 30-60 seconds

# 3. Try SSH access
gh cs ssh -c <codespace-name>
curl http://localhost:3000/health

# 4. Check logs in Codespace
gh cs ssh -c <codespace-name>
cd /workspaces/myproject
cat ~/.sudocode/server.log

Deployment Stops Unexpectedly

Issue: Deployment status changes to "stopped" without manual intervention.

Causes:

• Idle timeout reached (no activity for configured period)
• GitHub Codespaces automatic cleanup
• Insufficient credits/quota

Solution:

# Check configuration
sudocode remote codespaces config

# Increase timeouts for longer tasks
sudocode remote codespaces config \
  --idle-timeout 1440 \
  --keep-alive 168

# Redeploy
sudocode remote codespaces spawn --branch <branch>

Machine Types

GitHub Codespaces offers different machine types with varying resources:

| Machine Type | vCPUs | RAM | Storage | Use Case | |-------------|-------|-----|---------|----------| | basicLinux32gb | 2 | 8 GB | 32 GB | Small projects, quick tasks | | standardLinux32gb | 4 | 16 GB | 32 GB | Medium projects | | premiumLinux | 8 | 32 GB | 64 GB | Large projects, intensive tasks |

Cost Considerations:

• Larger machines consume GitHub Codespaces quota faster
• Free tier provides limited monthly minutes
• Paid plans offer more quota

Selecting Machine:

# Configure default machine
sudocode remote codespaces config --machine "standardLinux32gb"

# Override for specific deployment
sudocode remote codespaces spawn --machine "premiumLinux"

Best Practices

1. Commit Before Deploy

   • Always commit and push changes before deploying
   • Deployments clone from git, not local working directory

2. Use Configuration Defaults

   • Set project defaults in .sudocode/spawn-config.json
   • Commit configuration to share with team
   • Override per-deployment as needed

3. Monitor Active Deployments

   • Regularly check sudocode remote codespaces list
   • Stop unused deployments to save quota
   • Use --force flag for batch cleanup

4. Right-Size Resources

   • Start with basicLinux32gb for most tasks
   • Upgrade to larger machines only when needed
   • Use shorter timeouts for quick tasks

5. Secure Credentials

   • Never commit credentials to git
   • Credentials are automatically secured in Codespaces
   • Use sudocode auth clear if credentials are compromised

6. Branch Strategy

   • Deploy feature branches for isolated work
   • Keep deployments aligned with git workflow
   • Use configuration to set consistent defaults

7. Team Sharing

   • Share Sudocode URLs with team members for review
   • Use descriptive branch names for clarity
   • Document deployment purpose in commit messages

8. Cleanup Routine

   • Stop deployments when work is complete
   • Don't rely solely on auto-cleanup
   • Check monthly to avoid quota surprises

9. Provider-Specific Commands

   • Always specify provider in commands: sudocode remote <provider> <command>
   • Currently only codespaces is fully supported
   • coder support coming soon

Error Messages

All deploy commands provide consistent, actionable error messages with clear guidance on how to resolve issues.

Error Message Format

All errors follow this consistent format:

✗ Error Title

  Detailed explanation of what went wrong
  
  Suggested action:
    command to run or steps to take

Example Error Messages

Authentication Error:

✗ GitHub CLI is not authenticated

  Sudocode needs GitHub CLI to deploy to Codespaces.
  
  To authenticate:
    gh auth login

Git Repository Not Found:

✗ Git repository not found

  This command must be run from within a git repository.
  
  To initialize a repository:
    git init

Port Conflict:

✗ Port 3000 is already in use

  The requested port is not available on your system.
  
  To use a different port:
    sudocode remote codespaces spawn --port 3001

Deployment Not Found:

✗ Deployment 'codespace-xyz' not found

  The specified deployment does not exist or has been deleted.
  
  To list all deployments:
    sudocode remote codespaces list

Network Connection Failed:

✗ Network connection failed

  Unable to list deployments due to network issues.
  
  Suggested actions:
    • Check your internet connection
    • Verify VPN or proxy settings
    • Try again in a few moments

Invalid Configuration:

✗ Invalid configuration: port

  Port must be between 1024 and 65535
  
  To view current configuration:
    sudocode remote codespaces config

Error Types

The deploy system uses typed errors for consistent handling:

• AuthenticationError - Missing or invalid credentials (GitHub, Claude)
• GitContextError - Git repository issues (not a repo, no remote, invalid branch)
• ConfigurationError - Invalid configuration values
• ProviderError - Deployment provider failures (Codespaces API errors)
• NetworkError - Network connectivity issues
• PortConflictError - Port already in use
• DeploymentNotFoundError - Deployment ID not found

Each error type provides context-specific guidance for resolution.

Example Workflows

Creating and Working on a Feature

# Create a spec for the feature
sudocode spec create "Add OAuth authentication" -p 4 --tags auth,security

# Create implementation issues
sudocode issue create "Set up OAuth provider" -p 3 -a alice
sudocode issue create "Create login flow" -p 3 -a bob

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

# Mark an issue as blocking another
sudocode link ISSUE-1 ISSUE-2 --type blocks

# Check what's ready to work on
sudocode ready

# Start working
sudocode issue update ISSUE-1 --status in_progress

# Complete the work
sudocode issue close ISSUE-1 -r "OAuth provider configured"

Adding Feedback to Specs

# Add feedback at a specific line
sudocode feedback add ISSUE-3 SPEC-1 \
  --line 42 \
  --content "Consider adding rate limiting" \
  --type suggestion

# Add feedback by searching for text
sudocode feedback add ISSUE-4 SPEC-1 \
  --text "password requirements" \
  --content "Should we support passkeys?" \
  --type comment

# List all feedback for a spec
sudocode feedback list --spec SPEC-1

# Check for stale anchors
sudocode feedback stale