sudocode export

Syntax

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

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

Arguments

--output

string

required

Output directory for JSONL filesExample: --output /backup/sudocode-exportDirectory will be created if it doesn’t exist. Existing files will be overwritten.

Examples

Basic Export

Export to default location (.sudocode/):

sudocode export --output .sudocode/

Expected output

✓ Exported to JSONL
  Output: .sudocode/

This creates:

.sudocode/specs.jsonl
.sudocode/issues.jsonl

Export to Backup Directory

Create a dated backup:

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

Expected output

✓ Exported to JSONL
  Output: backups/sudocode-2025-10-29

Creates timestamped backup directory with all JSONL files.

Export for External Processing

Export to temporary directory for analysis:

sudocode export --output /tmp/sudocode-export

Expected output

✓ Exported to JSONL
  Output: /tmp/sudocode-export

JSON Output

Get machine-readable output:

sudocode --json export --output backups/export

JSON output

{
  "success": true,
  "outputDir": "backups/export"
}

JSONL Format

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

specs.jsonl

{"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

{"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:

#!/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:

Export current state

sudocode export --output backups/pre-migration-$(date +%Y-%m-%d)

Verify export

ls -lh backups/pre-migration-*/

Check that files exist and have reasonable sizes

Perform migration

Make your changes

Keep backup

Don’t delete until migration is verified

Export for team member or external tool:

Export to clean directory

sudocode export --output shared-export/

Package

tar czf sudocode-export.tar.gz shared-export/

Send sudocode-export.tar.gz to collaborator

Recipient imports

tar xzf sudocode-export.tar.gz
sudocode import --input shared-export/

Data Analysis

Export for external analysis:

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

#!/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:

#!/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:

# 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

export

Database → JSONL only

One direction
Overwrites JSONL files
No markdown involved
Raw data export

sudocode export --output dir/

sync

Bidirectional full sync

Auto-detects direction
Handles markdown too
Complete workflow
Normal operations

sudocode sync

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

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

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.

Can I export specific entities?

No, export always exports everything. For selective extraction, query JSONL directly:

jq 'select(.id == "SPEC-001")' .sudocode/specs.jsonl

Are relationships exported?

Relationships are embedded in spec/issue data under the relationships field. A separate relationships.jsonl is not currently created by default.

Can export overwrite existing files?

Yes, export overwrites existing JSONL files in the output directory. Always backup before overwriting important data.

What format is the timestamp?

ISO 8601 format: 2025-10-29T10:00:00Z

Troubleshooting

Export fails with permission error

Cause: Cannot write to output directorySolution:

Check directory permissions

Create directory manually:

mkdir -p backups/export
sudocode export --output backups/export

Exported files are empty

Cause: No data in databaseSolution: Verify database has data:

sudocode status

If empty, import or create entities first.

Export creates files but they're corrupted

Cause: Disk space or write issuesSolution:

Check disk space: df -h

Verify file integrity:

jq '.' backups/export/specs.jsonl > /dev/null

Re-export if needed

Export doesn't include recent changes

Cause: Changes not yet in databaseSolution: Sync first:

sudocode sync
sudocode export --output backups/

import

Import from JSONL

sync

Full bidirectional sync

status

Check project status

Next Steps

Export current state

sudocode export --output backups/current

Verify export

ls -lh backups/current/
jq '.' backups/current/specs.jsonl | head

Store safely

Commit to git or copy to backup location

Automate

Set up daily backup script

Storage Model

Learn more about sudocode’s storage architecture and JSONL format

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

Syntax

Description

Arguments

Examples

Basic Export

Export to Backup Directory

Export for External Processing

JSON Output

JSONL Format

specs.jsonl

issues.jsonl

Common Workflows

Daily Backup

Pre-Migration Export

Data Analysis

Scripting Examples

Incremental Backup

Export Statistics

Export to CSV

Understanding Export

What Gets Exported

Export is Source of Truth

Comparison with Sync

export

sync

Common Questions

Troubleshooting

import

sync

status

Next Steps

Storage Model

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

​Syntax

​Description

​Arguments

​Examples

​Basic Export

​Export to Backup Directory

​Export for External Processing

​JSON Output

​JSONL Format

​specs.jsonl

​issues.jsonl

​Common Workflows

​Daily Backup

​Pre-Migration Export

​Share Project State

​Data Analysis

​Scripting Examples

​Incremental Backup

​Export Statistics

​Export to CSV

​Understanding Export

​What Gets Exported

​Export is Source of Truth

​Comparison with Sync

export

sync

​Common Questions

​Troubleshooting

​Related Commands

import

sync

status

​Next Steps

Storage Model

Syntax

Description

Arguments

Examples

Basic Export

Export to Backup Directory

Export for External Processing

JSON Output

JSONL Format

specs.jsonl

issues.jsonl

Common Workflows

Daily Backup

Pre-Migration Export

Share Project State

Data Analysis

Scripting Examples

Incremental Backup

Export Statistics

Export to CSV

Understanding Export

What Gets Exported

Export is Source of Truth

Comparison with Sync

Common Questions

Troubleshooting

Related Commands

Next Steps