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

> Export sudocode database to JSONL files for backup, migration, or external processing

## Syntax

```bash theme={null}
sudocode export --output <directory>
```

## Description

The `export` command writes the current state of the SQLite database to JSONL (JSON Lines) files. This creates machine-readable, line-delimited JSON files that serve as the source of truth for sudocode projects.

**Exported files:**

* `specs.jsonl` - All specifications
* `issues.jsonl` - All issues
* `relationships.jsonl` - All relationships (optional)

Use `export` to:

* Create backups
* Prepare for migration
* Generate data for external tools
* Manually inspect database state
* Share project state

<Note>
  Most commands automatically export after making changes. Manual export is useful for backups or when working with the database directly.
</Note>

## Arguments

<ParamField path="--output" type="string" required>
  Output directory for JSONL files

  **Example:** `--output /backup/sudocode-export`

  Directory will be created if it doesn't exist. Existing files will be overwritten.
</ParamField>

## Examples

### Basic Export

Export to default location (`.sudocode/`):

```bash theme={null}
sudocode export --output .sudocode/
```

<Accordion title="Expected output">
  ```
  ✓ Exported to JSONL
    Output: .sudocode/
  ```
</Accordion>

This creates:

* `.sudocode/specs.jsonl`
* `.sudocode/issues.jsonl`

### Export to Backup Directory

Create a dated backup:

```bash theme={null}
sudocode export --output backups/sudocode-$(date +%Y-%m-%d)
```

<Accordion title="Expected output">
  ```
  ✓ Exported to JSONL
    Output: backups/sudocode-2025-10-29
  ```
</Accordion>

Creates timestamped backup directory with all JSONL files.

### Export for External Processing

Export to temporary directory for analysis:

```bash theme={null}
sudocode export --output /tmp/sudocode-export
```

<Accordion title="Expected output">
  ```
  ✓ Exported to JSONL
    Output: /tmp/sudocode-export
  ```
</Accordion>

### JSON Output

Get machine-readable output:

```bash theme={null}
sudocode --json export --output backups/export
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "success": true,
    "outputDir": "backups/export"
  }
  ```
</Accordion>

## JSONL Format

JSONL (JSON Lines) format stores one JSON object per line:

### specs.jsonl

```json theme={null}
{"id":"SPEC-001","uuid":"...","title":"Authentication System","content":"...","priority":0,"archived":0,"created_at":"2025-10-29T08:00:00Z","updated_at":"2025-10-29T09:00:00Z","parent_id":null,"file_path":"specs/authentication-system.md"}
{"id":"SPEC-002","uuid":"...","title":"API Design","content":"...","priority":1,"archived":0,"created_at":"2025-10-29T08:00:00Z","updated_at":"2025-10-29T09:00:00Z","parent_id":"SPEC-001","file_path":"specs/api-design.md"}
```

Each line is a complete spec object.

### issues.jsonl

```json theme={null}
{"id":"ISSUE-001","uuid":"...","title":"Implement OAuth 2.0","content":"...","status":"open","priority":0,"assignee":"alice","archived":0,"created_at":"2025-10-29T08:00:00Z","updated_at":"2025-10-29T09:00:00Z","closed_at":null,"parent_id":null}
{"id":"ISSUE-002","uuid":"...","title":"Add rate limiting","content":"...","status":"in_progress","priority":1,"assignee":"bob","archived":0,"created_at":"2025-10-29T08:00:00Z","updated_at":"2025-10-29T09:00:00Z","closed_at":null,"parent_id":null}
```

Each line is a complete issue object.

## Common Workflows

### Daily Backup

Create automated backups:

```bash theme={null}
#!/bin/bash
# Daily backup script

backup_dir="backups/$(date +%Y-%m-%d)"
sudocode export --output "$backup_dir"

echo "Backup created: $backup_dir"

# Keep only last 30 days
find backups/ -type d -mtime +30 -exec rm -rf {} \;
```

### Pre-Migration Export

Before major changes:

<Steps>
  <Step title="Export current state">
    ```bash theme={null}
    sudocode export --output backups/pre-migration-$(date +%Y-%m-%d)
    ```
  </Step>

  <Step title="Verify export">
    ```bash theme={null}
    ls -lh backups/pre-migration-*/
    ```

    Check that files exist and have reasonable sizes
  </Step>

  <Step title="Perform migration">
    Make your changes
  </Step>

  <Step title="Keep backup">
    Don't delete until migration is verified
  </Step>
</Steps>

### Share Project State

Export for team member or external tool:

<Steps>
  <Step title="Export to clean directory">
    ```bash theme={null}
    sudocode export --output shared-export/
    ```
  </Step>

  <Step title="Package">
    ```bash theme={null}
    tar czf sudocode-export.tar.gz shared-export/
    ```
  </Step>

  <Step title="Share">
    Send `sudocode-export.tar.gz` to collaborator
  </Step>

  <Step title="Recipient imports">
    ```bash theme={null}
    tar xzf sudocode-export.tar.gz
    sudocode import --input shared-export/
    ```
  </Step>
</Steps>

### Data Analysis

Export for external analysis:

```bash theme={null}
# Export to temp directory
sudocode export --output /tmp/analysis

# Analyze with jq
jq '.priority' /tmp/analysis/issues.jsonl | \
  sort | uniq -c

# Output: Count of issues by priority
#   15 0
#    8 1
#    3 2
```

## Scripting Examples

### Incremental Backup

Keep incremental backups:

```bash theme={null}
#!/bin/bash
# Incremental backup - only if changes detected

current_hash=$(sha256sum .sudocode/specs.jsonl .sudocode/issues.jsonl | sha256sum | cut -d' ' -f1)
last_hash=$(cat backups/last-hash.txt 2>/dev/null || echo "")

if [ "$current_hash" != "$last_hash" ]; then
  backup_dir="backups/$(date +%Y-%m-%d-%H%M%S)"
  sudocode export --output "$backup_dir"
  echo "$current_hash" > backups/last-hash.txt
  echo "Backup created: $backup_dir"
else
  echo "No changes detected, skipping backup"
fi
```

### Export Statistics

Generate report from export:

```bash theme={null}
#!/bin/bash
# Export and generate statistics report

export_dir="/tmp/sudocode-export"
sudocode export --output "$export_dir"

echo "sudocode Export Report"
echo "======================"
echo ""
echo "Specs: $(wc -l < "$export_dir/specs.jsonl")"
echo "Issues: $(wc -l < "$export_dir/issues.jsonl")"
echo ""
echo "Issue Status Breakdown:"
jq -r '.status' "$export_dir/issues.jsonl" | sort | uniq -c
```

### Export to CSV

Convert JSONL to CSV for spreadsheet:

```bash theme={null}
# Export
sudocode export --output /tmp/export

# Convert issues to CSV
echo "id,title,status,priority,assignee" > issues.csv
jq -r '[.id, .title, .status, .priority, .assignee] | @csv' \
  /tmp/export/issues.jsonl >> issues.csv

echo "Created issues.csv"
```

## Understanding Export

### What Gets Exported

**Specs:**

* All spec fields (id, uuid, title, content, priority, etc.)
* Archived specs included
* Parent relationships included

**Issues:**

* All issue fields (id, uuid, title, content, status, priority, etc.)
* Archived issues included
* Parent relationships included

**Not Exported:**

* Relationships (separate file if needed)
* Tags (embedded in entity data)
* Feedback (embedded in entity data)
* Database-only computed views

### Export is Source of Truth

JSONL files are the canonical representation:

* Git-friendly (line-by-line diffs)
* Human-readable (one object per line)
* Easy to process (standard JSON)
* Complete (all entity data)

The database is derived from JSONL via import.

## Comparison with Sync

<CardGroup cols={2}>
  <Card title="export" icon="file-export">
    **Database → JSONL only**

    * One direction
    * Overwrites JSONL files
    * No markdown involved
    * Raw data export

    ```bash theme={null}
    sudocode export --output dir/
    ```
  </Card>

  <Card title="sync" icon="arrows-rotate">
    **Bidirectional full sync**

    * Auto-detects direction
    * Handles markdown too
    * Complete workflow
    * Normal operations

    ```bash theme={null}
    sudocode sync
    ```
  </Card>
</CardGroup>

**Use export when:**

* Creating backups
* Manual data extraction
* Preparing for import elsewhere

**Use sync when:**

* Normal development workflow
* After git pull
* After manual edits

## Common Questions

<AccordionGroup>
  <Accordion title="Do I need to export manually?">
    Usually no. Most commands automatically export after making changes. Manual export is useful for:

    * Creating backups
    * Snapshots before major changes
    * Exporting to external tools
  </Accordion>

  <Accordion title="What's the difference between export and sync?">
    * **export**: Database → JSONL only, one direction
    * **sync**: Bidirectional, handles markdown too, auto-detects direction

    Use `sync` for normal operations, `export` for manual data extraction.
  </Accordion>

  <Accordion title="Can I export specific entities?">
    No, export always exports everything. For selective extraction, query JSONL directly:

    ```bash theme={null}
    jq 'select(.id == "SPEC-001")' .sudocode/specs.jsonl
    ```
  </Accordion>

  <Accordion title="Are relationships exported?">
    Relationships are embedded in spec/issue data under the `relationships` field. A separate relationships.jsonl is not currently created by default.
  </Accordion>

  <Accordion title="Can export overwrite existing files?">
    Yes, export overwrites existing JSONL files in the output directory. Always backup before overwriting important data.
  </Accordion>

  <Accordion title="What format is the timestamp?">
    ISO 8601 format: `2025-10-29T10:00:00Z`
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Export fails with permission error">
    **Cause:** Cannot write to output directory

    **Solution:**

    1. Check directory permissions
    2. Create directory manually:
       ```bash theme={null}
       mkdir -p backups/export
       sudocode export --output backups/export
       ```
  </Accordion>

  <Accordion title="Exported files are empty">
    **Cause:** No data in database

    **Solution:**
    Verify database has data:

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

    If empty, import or create entities first.
  </Accordion>

  <Accordion title="Export creates files but they're corrupted">
    **Cause:** Disk space or write issues

    **Solution:**

    1. Check disk space: `df -h`
    2. Verify file integrity:
       ```bash theme={null}
       jq '.' backups/export/specs.jsonl > /dev/null
       ```
    3. Re-export if needed
  </Accordion>

  <Accordion title="Export doesn't include recent changes">
    **Cause:** Changes not yet in database

    **Solution:**
    Sync first:

    ```bash theme={null}
    sudocode sync
    sudocode export --output backups/
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="import" icon="file-import" href="/cli/import">
    Import from JSONL
  </Card>

  <Card title="sync" icon="arrows-rotate" href="/cli/sync">
    Full bidirectional sync
  </Card>

  <Card title="status" icon="chart-simple" href="/cli/status">
    Check project status
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Export current state">
    ```bash theme={null}
    sudocode export --output backups/current
    ```
  </Step>

  <Step title="Verify export">
    ```bash theme={null}
    ls -lh backups/current/
    jq '.' backups/current/specs.jsonl | head
    ```
  </Step>

  <Step title="Store safely">
    Commit to git or copy to backup location
  </Step>

  <Step title="Automate">
    Set up daily backup script
  </Step>
</Steps>

<Card title="Storage Model" icon="book" href="/concepts/storage">
  Learn more about sudocode's storage architecture and JSONL format
</Card>