> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# sudocode init

> Initialize a new sudocode project by creating the `.sudocode/` directory structure and configuration files.

## Syntax

```bash theme={null}
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.

<Note>
  Running `init` in a directory that already has `.sudocode/` is safe - it preserves existing data and only creates missing files.
</Note>

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

<AccordionGroup>
  <Accordion title="cache.db - SQLite Database">
    **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
  </Accordion>

  <Accordion title="specs.jsonl & issues.jsonl - Source of Truth">
    **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
  </Accordion>

  <Accordion title="config.json - Configuration">
    **Purpose:** Project configuration

    * Stores version info
    * **Git-tracked** - committed to version control

    Example content:

    ```json theme={null}
    {
      "version": "1.0.0"
    }
    ```
  </Accordion>

  <Accordion title="specs/ & issues/ - Markdown Files">
    **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)
  </Accordion>

  <Accordion title=".gitignore">
    **Purpose:** Exclude cache files from git

    Content:

    ```
    cache.db*
    issues/
    specs/
    ```

    The SQLite cache and markdown directories are gitignored because JSONL files are the source of truth.
  </Accordion>
</AccordionGroup>

## Examples

### Basic Initialization

Initialize with default settings:

```bash theme={null}
cd your-project
sudocode init
```

<Accordion title="Expected output">
  ```
  ✓ Initialized sudocode in .sudocode
    Database: .sudocode/cache.db
  ```
</Accordion>

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:

```bash theme={null}
sudocode init
```

<Accordion title="Expected output">
  ```
  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
  ```
</Accordion>

<Check>
  Existing files are preserved and imported. Only missing files are created.
</Check>

## After Initialization

After running `init`, you can:

<CardGroup cols={2}>
  <Card title="Create Your First Spec" icon="file-lines" href="/cli/spec-create">
    ```bash theme={null}
    sudocode spec create "Feature Name"
    ```
  </Card>

  <Card title="Create Your First Issue" icon="list-check" href="/cli/issue-create">
    ```bash theme={null}
    sudocode issue create "Task Name"
    ```
  </Card>

  <Card title="Import Existing Data" icon="file-import" href="/cli/import">
    ```bash theme={null}
    sudocode import --input path/to/data
    ```
  </Card>

  <Card title="Start File Watcher" icon="eye" href="/cli/sync">
    ```bash theme={null}
    sudocode sync --watch
    ```
  </Card>
</CardGroup>

## Common Questions

<AccordionGroup>
  <Accordion title="What if .sudocode/ already exists?">
    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.
  </Accordion>

  <Accordion title="Should I commit .sudocode/ to git?">
    **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.
  </Accordion>

  <Accordion title="Can I have multiple .sudocode/ directories?">
    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.
  </Accordion>

  <Accordion title="What if init fails?">
    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.
  </Accordion>
</AccordionGroup>

## Git Workflow

After initialization, add sudocode files to git:

```bash theme={null}
# 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>"
```

<Info>
  The `.sudocode/.gitignore` automatically excludes cache files, so you won't accidentally commit them.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: EACCES: permission denied">
    **Cause:** No write permission in the directory

    **Solution:**

    ```bash theme={null}
    # Check permissions
    ls -la

    # Fix permissions if needed
    chmod u+w .

    # Or run with sudo (not recommended)
    sudo sudocode init
    ```
  </Accordion>

  <Accordion title="Error: Database is locked">
    **Cause:** Another process is using the database

    **Solution:**

    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
  </Accordion>

  <Accordion title="Already initialized message">
    **Message:** "✓ Initialized sudocode... Preserved existing: ..."

    **Solution:** This is normal! Init detected existing files and preserved them. You're good to go.
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="spec create" icon="file-plus" href="/cli/spec-create">
    Create your first spec
  </Card>

  <Card title="issue create" icon="list-check" href="/cli/issue-create">
    Create your first issue
  </Card>

  <Card title="sync" icon="arrows-rotate" href="/cli/sync">
    Sync between JSONL and database
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Initialize project">
    ```bash theme={null}
    sudocode init
    ```
  </Step>

  <Step title="Create a spec">
    ```bash theme={null}
    sudocode spec create "My First Feature"
    ```
  </Step>

  <Step title="Create an issue">
    ```bash theme={null}
    sudocode issue create "Implement feature"
    ```
  </Step>

  <Step title="Link them together">
    ```bash theme={null}
    sudocode link ISSUE-001 SPEC-001 --type implements
    ```
  </Step>
</Steps>

<Card title="Quick Start Guide" icon="rocket" href="/quickstart">
  Follow the complete quick start for a guided walkthrough
</Card>