---
title: "@sudocode-ai/cli"
description: "Command-line interface for [sudocode](https://github.com/sudocode-ai/sudocode) - Git-native spec and issue management for AI-assisted software development."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/readme-648
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:36:48.879Z
license: CC-BY-4.0
attribution: "@sudocode-ai/cli — Claudary (https://claudary.paisolsolutions.com/skills/readme-648)"
---

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

## Overview

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

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

```bash
npm install -g @sudocode-ai/cli
```

Or install the meta-package that includes the CLI:

```bash
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:

```bash
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:

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

### Check Authentication Status

View all configured credentials:

```bash
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:

```bash
sudocode auth clear
```

Or skip confirmation:

```bash
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":

```bash
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:

```bash
# 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:

```bash
sudocode auth clear --force
sudocode auth claude
```

## Quick Start

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

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

```bash
# 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:**

```bash
# 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

```bash
# Show ready work (no blockers)
sudocode ready

# Show blocked issues
sudocode blocked
```

### Status & Stats

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

```bash
# 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

```bash
# 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

```bash
--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
   ```bash
   # 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
   ```bash
   sudocode auth claude
   ```
   See the [Authentication](#authentication) section for details.

4. **GitHub Authentication** - Login to GitHub CLI
   ```bash
   gh auth login
   ```

### Quick Start

Deploy your current project to a Codespace:

```bash
# 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:

```bash
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.

```bash
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:**

```bash
# 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

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/readme-648) · https://claudary.paisolsolutions.com