Skip to main content

​
Syntax

​
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:

​
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:
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:
The SQLite cache and markdown directories are gitignored because JSONL files are the source of truth.

​
Examples

​
Basic Initialization

Initialize with default settings:
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:
Existing files are preserved and imported. Only missing files are created.

​
After Initialization

After running init, you can:

Create Your First Spec

Create Your First Issue

Import Existing Data

Start File Watcher

​
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:
The .sudocode/.gitignore automatically excludes cache files, so you won’t accidentally commit them.

​
Troubleshooting

Cause: No write permission in the directorySolution:
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

2

Create a spec

3

Create an issue

4

Link them together

Quick Start Guide

Follow the complete quick start for a guided walkthrough