Skip to main content

​
Step 1: Install the CLI

Install sudocode globally using npm: 
npm install -g sudocode

added 42 packages in 3s
Verify the installation: 
sudocode --version

sudocode/1.0.0
If you see the version number, sudocode is successfully installed!

​
Step 2: Initialize Your Project

Navigate to your project directory and initialize sudocode: 
cd your-project
sudocode init

✓ Created .sudocode/ directory
✓ Created .sudocode/specs/specs.jsonl
✓ Created .sudocode/issues/issues.jsonl
✓ Created .sudocode/cache.db
✓ Created .sudocode/.gitignore
✓ Initialized metadata

sudocode initialized successfully!
This creates a .sudocode/ directory in your project with the following structure: 
your-project/
└── .sudocode/
    ├── cache.db           # SQLite cache (gitignored)
    ├── specs/
    │   └── specs.jsonl    # Spec source of truth (git-tracked)
    ├── issues/
    │   └── issues.jsonl   # Issue source of truth (git-tracked)
    ├── meta.json          # Configuration
    └── .gitignore
Your project is now ready to use sudocode!

​
Step 3: Create Your First Spec

Let’s create a spec for a simple feature. Specs capture user intent - what you want to build: 
sudocode spec create "User Authentication System" \
  --description "Implement user login and registration" \
  --priority 0 \
  --tags auth,security

✓ Created spec SPEC-001

Title: User Authentication System
ID: SPEC-001
Priority: 0 (highest)
Tags: auth, security
Status: draft

View details: sudocode spec show SPEC-001
Priority levels: 0 (highest) to 4 (lowest). Default is 2.
View your spec: 
sudocode spec show SPEC-001

SPEC-001: User Authentication System
=====================================

Status: draft
Priority: 0
Tags: auth, security
Created: 2025-10-29 09:00:00

Description:
Implement user login and registration

Relationships:
  None yet

File: .sudocode/specs/SPEC-001.md
You’ve created your first spec! It’s now tracked in git.

​
Step 4: Create Your First Issue

Now let’s create an issue - an actionable work item for implementing part of the spec: 
sudocode issue create "Implement login endpoint" \
  --description "Create POST /api/auth/login endpoint" \
  --priority 1 \
  --tags auth,backend

✓ Created issue ISSUE-001

Title: Implement login endpoint
ID: ISSUE-001
Priority: 1
Tags: auth, backend
Status: open

View details: sudocode issue show ISSUE-001
Connect your issue to the spec it implements: 
sudocode link ISSUE-001 SPEC-001 --type implements

✓ Created relationship: ISSUE-001 implements SPEC-001

Relationships for ISSUE-001:
  implements → SPEC-001 (User Authentication System)
Now when you view the spec, you’ll see the linked issue: 
sudocode spec show SPEC-001

SPEC-001: User Authentication System
=====================================

Status: draft
Priority: 0
Tags: auth, security

Description:
Implement user login and registration

Relationships:
  Implemented by:
    - ISSUE-001: Implement login endpoint

File: .sudocode/specs/SPEC-001.md
Your issue is now linked to the spec with an implements relationship!

​
Step 6: View Ready Work

See what work is ready to be done (no blockers): 
sudocode ready

Ready Issues (1)
================

ISSUE-001: Implement login endpoint
  Priority: 1
  Tags: auth, backend
  Implements: SPEC-001

No blockers - ready to work!

​
Step 7: List All Your Work

View all specs: 
sudocode spec list

Specs (1)
=========

ID        Title                          Status  Priority  Tags
SPEC-001  User Authentication System     draft   0         auth, security
View all issues: 
sudocode issue list

Issues (1)
==========

ID        Title                      Status  Priority  Tags
ISSUE-001 Implement login endpoint   open    1         auth, backend
Congratulations! You’ve successfully:
  • ✅ Installed sudocode
  • ✅ Initialized a project
  • ✅ Created your first spec
  • ✅ Created your first issue
  • ✅ Linked them together
  • ✅ Queried your work

​
Next Steps

Now that you have the basics down, explore these topics:

Core Concepts

Deep dive into specs, issues, relationships, and feedback

MCP Integration

Set up AI agents to work with sudocode

CLI Reference

Complete command reference and advanced usage

Workflows

Learn spec-driven development workflow

​
Common Next Actions

Here are some common things you might want to do next: 
sudocode issue create "Implement registration endpoint" \
  --priority 1 \
  --tags auth,backend

sudocode link ISSUE-002 SPEC-001 --type implements

sudocode spec create "OAuth 2.0 Integration" \
  --parent SPEC-001 \
  --priority 1

# ISSUE-002 depends on ISSUE-001 completing first
sudocode link ISSUE-002 ISSUE-001 --type blocks

# Start working on an issue
sudocode issue update ISSUE-001 --status in_progress

# Close when done
sudocode issue close ISSUE-001

sudocode feedback add ISSUE-001 SPEC-001 \
  --content "Need to specify token expiration policy" \
  --type request \
  --line 15

​
Troubleshooting

Make sure npm global bin directory is in your PATH:
npm config get prefix
Add this to your PATH in ~/.bashrc or ~/.zshrc:
export PATH="$PATH:$(npm config get prefix)/bin"
Use npx to run without global install:
npx sudocode init
Or fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
If you see “Project already initialized”, you’re good! You can skip sudocode init.To reinitialize (⚠️ this will reset your data):
rm -rf .sudocode
sudocode init
Check your .gitignore. Make sure it’s not excluding .sudocode/:
# .gitignore should NOT have:
.sudocode/

# .sudocode/.gitignore should have:
cache.db
cache.db-shm
cache.db-wal
Need help? Check out the GitHub Discussions or open an issue.