Skip to main content

​
Syntax

sudocode init [options]

​
Description

The init command sets up sudocode in the current directory by creating:
  • .sudocode/ directory structure
  • SQLite database for caching
  • Empty JSONL files for specs and issues
  • Configuration file
  • .gitignore to exclude cache files
This is typically the first command you run when starting to use sudocode in a project.
Running init in a directory that already has .sudocode/ is safe - it preserves existing data and only creates missing files.

​
What Gets Created

When you run sudocode init, the following structure is created: 
.sudocode/
├── cache.db           # SQLite database (gitignored)
├── cache.db-shm       # SQLite shared memory (gitignored)
├── cache.db-wal       # SQLite write-ahead log (gitignored)
├── specs.jsonl        # Spec source of truth (git-tracked)
├── issues.jsonl       # Issue source of truth (git-tracked)
├── config.json        # Configuration (git-tracked)
├── .gitignore         # Ignores cache files
├── specs/             # Markdown spec files (gitignored)
└── issues/            # Markdown issue files (gitignored)

​
Files Explained

Purpose: Fast queries and relationship graph traversal
  • Created automatically on init
  • Rebuilt from JSONL after git pull
  • Contains tables for specs, issues, relationships, tags, feedback
  • Gitignored - not committed to version control
Purpose: Version-controlled source of truth
  • JSONL format (one JSON object per line)
  • Git-tracked - committed to version control
  • Append-only log structure for git-friendly diffs
  • Contains all spec/issue data with metadata
Purpose: Project configuration
  • Stores version info
  • Git-tracked - committed to version control
Example content:
{
  "version": "1.0.0"
}
Purpose: Human-editable interface
  • Created on-demand when you create/edit entities
  • YAML frontmatter + markdown content
  • Synced to JSONL automatically
  • Gitignored by default (JSONL is source of truth)
Purpose: Exclude cache files from gitContent:
cache.db*
issues/
specs/
The SQLite cache and markdown directories are gitignored because JSONL files are the source of truth.

​
Examples

​
Basic Initialization

Initialize with default settings: 
cd your-project
sudocode init

✓ Initialized sudocode in .sudocode
  Database: .sudocode/cache.db
This creates IDs like:
  • Specs: SPEC-001, SPEC-002, SPEC-003
  • Issues: ISSUE-001, ISSUE-002, ISSUE-003

​
Re-initializing (Safe)

Running init again is safe and preserves existing data: 
sudocode init

Importing from existing JSONL files...
  Specs: 0 added, 5 updated
  Issues: 0 added, 12 updated
✓ Initialized sudocode in .sudocode
  Database: .sudocode/cache.db
  Preserved existing: cache.db, specs.jsonl, issues.jsonl
Existing files are preserved and imported. Only missing files are created.

​
After Initialization

After running init, you can:

Create Your First Spec

sudocode spec create "Feature Name"

Create Your First Issue

sudocode issue create "Task Name"

Import Existing Data

sudocode import --input path/to/data

Start File Watcher

sudocode sync --watch

​
Common Questions

Running init is safe - it preserves existing files and only creates missing ones. If JSONL files have data, they’re automatically imported into the database.
Yes, commit these:
  • specs.jsonl
  • issues.jsonl
  • config.json
  • .gitignore
No, don’t commit these (automatically ignored):
  • cache.db and cache.db-*
  • specs/ directory
  • issues/ directory
The JSONL files are the source of truth and should be version controlled. The SQLite cache is rebuilt automatically.
sudocode looks for .sudocode/ in the current directory and parent directories (like git does with .git/). You typically want one .sudocode/ at your project root.However, you can have multiple sudocode projects in subdirectories if needed.
Common failure reasons:
  • Permission denied: Ensure you have write permissions in the directory
  • Disk full: Free up disk space
  • Path too long: Use a shorter directory path
Check the error message for specific details.

​
Git Workflow

After initialization, add sudocode files to git: 
# Initialize sudocode
sudocode init

# Add version-controlled files
git add .sudocode/config.json
git add .sudocode/specs.jsonl
git add .sudocode/issues.jsonl
git add .sudocode/.gitignore

# Commit
git commit -m "Initialize sudocode

\ud83e\udd16 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"
The .sudocode/.gitignore automatically excludes cache files, so you won’t accidentally commit them.

​
Troubleshooting

Cause: No write permission in the directorySolution:
# Check permissions
ls -la

# Fix permissions if needed
chmod u+w .

# Or run with sudo (not recommended)
sudo sudocode init
Cause: Another process is using the databaseSolution:
  1. Close any other sudocode commands
  2. Check for zombie processes: ps aux | grep sudocode
  3. Delete WAL files if safe: rm .sudocode/cache.db-*
  4. Try init again
Message: ”✓ Initialized sudocode… Preserved existing: …”Solution: This is normal! Init detected existing files and preserved them. You’re good to go.

spec create

Create your first spec

issue create

Create your first issue

sync

Sync between JSONL and database

​
Next Steps

1

Initialize project

sudocode init
2

Create a spec

sudocode spec create "My First Feature"
3

Create an issue

sudocode issue create "Implement feature"
4

Link them together

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

Quick Start Guide

Follow the complete quick start for a guided walkthrough