sudocode import - sudocode

Syntax

sudocode import --input <directory>

Description

The import command reads JSONL (JSON Lines) files and loads them into the SQLite database. This is the inverse operation of export. Imported files:

specs.jsonl - Specifications
issues.jsonl - Issues
relationships.jsonl - Relationships (if present)

Use import to:

Restore from backups
Initialize new database from JSONL
Migrate data between systems
Recover from database corruption
Load shared project data

JSONL files are the source of truth in sudocode. Import rebuilds the database from these files, which is how sync works internally.

Arguments

string

required

Input directory containing JSONL filesExample: --input backups/2025-10-29Directory must contain specs.jsonl and/or issues.jsonl files.

Examples

Basic Import

Import from a directory:

sudocode import --input .sudocode/

Expected output

✓ Imported from JSONL
  Input: .sudocode/

This reads .sudocode/specs.jsonl and .sudocode/issues.jsonl and loads them into the database.

Restore from Backup

Restore database from backup:

sudocode import --input backups/2025-10-29/

Expected output

✓ Imported from JSONL
  Input: backups/2025-10-29/

Initialize New Database

Set up fresh database from JSONL:

Ensure clean state

rm -f .sudocode/sudocode.db  # Remove old database

Import from JSONL

sudocode import --input .sudocode/

Verify

sudocode status

Import Shared Data

Load data shared by team member:

# Unpack shared export
tar xzf team-export.tar.gz

# Import into your database
sudocode import --input team-export/

# Sync to markdown
sudocode sync --to-markdown

Expected output

✓ Imported from JSONL
  Input: team-export/

✓ Synced 59 entities to markdown

JSON Output

Get machine-readable output:

sudocode --json import --input backups/2025-10-29/

JSON output

{
  "success": true,
  "inputDir": "backups/2025-10-29/"
}

How Import Works

Import processes JSONL files line by line:

Read JSONL files

Parse specs.jsonl and issues.jsonl from input directoryEach line is one JSON object representing an entity

Validate data

Check for required fields and valid structureSkip or error on invalid entries

Insert/update database

For each entity:

Check if ID exists in database
Insert if new, update if exists
Preserve UUIDs and timestamps

Import relationships

If relationships.jsonl exists, import relationship dataTags and other metadata embedded in entity records

Common Workflows

Disaster Recovery

Recover from database corruption:

Backup corrupted database

mv .sudocode/sudocode.db .sudocode/sudocode.db.corrupted

Import from JSONL (source of truth)

sudocode import --input .sudocode/

Sync to markdown

sudocode sync --to-markdown

Verify

sudocode status
sudocode spec list
sudocode issue list

Migration from Old Version

Migrate data from older sudocode version:

Export from old version

In old project:

sudocode-old export --output migration-data/

Copy JSONL files

cp migration-data/*.jsonl new-project/.sudocode/

Import in new version

In new project:

sudocode import --input .sudocode/
sudocode sync --to-markdown

Verify migration

sudocode stats

Compare counts with old project

Team Collaboration

Share and merge project data:

Team member A exports

sudocode export --output shared/alice-work/

Team member B receives and imports

# Backup current state
sudocode export --output backups/pre-merge/

# Import Alice's work
sudocode import --input shared/alice-work/

# Sync to markdown
sudocode sync --to-markdown

Handle conflicts

Review imported changes and resolve any conflicts manually

Periodic Restore Test

Verify backups are valid:

#!/bin/bash
# Test restore from backup

backup_dir="backups/2025-10-29"
test_dir="/tmp/sudocode-restore-test"

# Create test environment
mkdir -p "$test_dir/.sudocode"
cd "$test_dir"

# Initialize
sudocode init

# Import backup
sudocode import --input "$backup_dir"

# Verify
count=$(sudocode --json status | jq '.issues.total')
echo "Restored $count issues from backup"

# Cleanup
cd -
rm -rf "$test_dir"

Import Behavior

Conflict Resolution

When importing data that conflicts with existing database: Default behavior: Upsert (insert or update)

If entity ID exists: Update with imported data
If entity ID doesn’t exist: Insert new entity
Timestamps from JSONL are preserved
No manual conflict resolution

Import will overwrite existing data for matching IDs. Always backup before importing if you have unsaved local changes.

Data Preservation

What’s preserved during import:

Entity IDs (SPEC-001, ISSUE-001, etc.)
UUIDs
Timestamps (created_at, updated_at, closed_at)
All entity fields (title, content, priority, status, etc.)
Parent relationships
Tags
Archived status

Missing Files

If files are missing:

Only specs.jsonl → Imports specs only
Only issues.jsonl → Imports issues only
Both missing → Error (nothing to import)
Extra files → Ignored

Scripting Examples

Automated Backup Restore

Test backup integrity automatically:

#!/bin/bash
# Verify latest backup can be imported

latest_backup=$(ls -t backups/ | head -1)

echo "Testing backup: $latest_backup"

# Create test database
test_db=$(mktemp -d)
cd "$test_db"
sudocode init

# Import backup
if sudocode import --input "$HOME/project/backups/$latest_backup"; then
  echo "✓ Backup is valid"

  # Verify counts
  sudocode stats
else
  echo "✗ Backup is corrupted!"
  exit 1
fi

# Cleanup
cd -
rm -rf "$test_db"

Merge Multiple Exports

Combine data from multiple sources:

#!/bin/bash
# Merge multiple JSONL exports

output_dir="merged-export"
mkdir -p "$output_dir"

# Combine specs
cat source1/specs.jsonl source2/specs.jsonl | \
  jq -s 'unique_by(.id) | .[]' > "$output_dir/specs.jsonl"

# Combine issues
cat source1/issues.jsonl source2/issues.jsonl | \
  jq -s 'unique_by(.id) | .[]' > "$output_dir/issues.jsonl"

# Import merged data
sudocode import --input "$output_dir"

Selective Import

Import only specific entities:

#!/bin/bash
# Import only high-priority issues

input_dir="backups/2025-10-29"
temp_dir=$(mktemp -d)

# Filter to P0/P1 issues only
jq 'select(.priority <= 1)' "$input_dir/issues.jsonl" > "$temp_dir/issues.jsonl"

# Copy specs as-is
cp "$input_dir/specs.jsonl" "$temp_dir/specs.jsonl"

# Import filtered data
sudocode import --input "$temp_dir"

# Cleanup
rm -rf "$temp_dir"

Comparison with Sync and Export

import

JSONL → Database

One direction
Overwrites database
No markdown involved
Restoration/migration

sudocode import --input dir/

export

Database → JSONL

One direction
Overwrites JSONL
No markdown involved
Backup/extraction

sudocode export --output dir/

sync

Bidirectional full sync

Auto-detects direction
Handles all layers
Complete workflow
Normal operations

sudocode sync

Typical workflow:

Normal operations: Use sync
Create backup: Use export
Restore backup: Use import then sync --to-markdown

Common Questions

Does import delete existing data?

No, import is an upsert operation:

Matching IDs: Updated with imported data
New IDs: Inserted as new entities
Existing IDs not in import: Remain unchanged

To fully replace database, delete it first:

rm .sudocode/sudocode.db
sudocode import --input backups/2025-10-29/

What happens to markdown files after import?

Import only updates the database. To update markdown:

sudocode import --input backups/2025-10-29/
sudocode sync --to-markdown

Can I import from multiple sources?

Yes, but sequential imports will overwrite conflicts. For merging:

Merge JSONL files manually using jq
Import the merged result

Are relationships imported?

Yes, if relationship data is embedded in entity records or if relationships.jsonl exists in the input directory.

What if JSONL format is invalid?

Import will skip or error on invalid lines. Check logs for specific errors. Validate with:

jq '.' input/specs.jsonl > /dev/null

Can I import into an existing project?

Yes, import merges with existing data. Matching IDs are updated, new IDs are added. Always backup first:

sudocode export --output backups/pre-import/
sudocode import --input new-data/

Troubleshooting

Error: Input directory doesn't exist

Cause: Path is incorrect or directory not foundSolution: Verify path:

ls -la backups/2025-10-29/

Use absolute path if needed:

sudocode import --input /full/path/to/backups/2025-10-29/

Error: No JSONL files found

Cause: Directory doesn’t contain specs.jsonl or issues.jsonlSolution: Check contents:

ls backups/2025-10-29/

Ensure at least one JSONL file exists.

Import succeeds but data is missing

Cause: May have imported to wrong database or database not synced to markdownSolution:

Check database:
sudocode status
Sync to markdown:
sudocode sync --to-markdown

Import fails with parse error

Cause: Invalid JSON in JSONL fileSolution: Validate JSONL:

jq '.' backups/2025-10-29/specs.jsonl > /dev/null

Fix or regenerate JSONL files from a clean source.

Database locked during import

Cause: Another process is using the databaseSolution:

Close other sudocode processes
Wait and retry
Check for zombie processes:
ps aux | grep sudocode

export

Export to JSONL

sync

Full bidirectional sync

status

Check import results

Next Steps

Backup current state

sudocode export --output backups/pre-import/

Import data

sudocode import --input new-data/

Sync to markdown

sudocode sync --to-markdown

Verify import

sudocode status
sudocode spec list
sudocode issue list

Commit changes

git add .sudocode/
git commit -m "Import data from backup"

Storage Model

Learn more about sudocode’s storage architecture and data flow

​Syntax

​Description

​Arguments

​Examples

​Basic Import

​Restore from Backup

​Initialize New Database

​Import Shared Data

​JSON Output

​How Import Works

​Common Workflows

​Disaster Recovery

​Migration from Old Version

​Team Collaboration

​Periodic Restore Test

​Import Behavior

​Conflict Resolution

​Data Preservation

​Missing Files

​Scripting Examples

​Automated Backup Restore

​Merge Multiple Exports

​Selective Import

​Comparison with Sync and Export

import

export

sync

​Common Questions

​Troubleshooting

​Related Commands

export

sync

status

​Next Steps

Storage Model

Syntax

Description

Arguments

Examples

Basic Import

Restore from Backup

Initialize New Database

Import Shared Data

JSON Output

How Import Works

Common Workflows

Disaster Recovery

Migration from Old Version

Team Collaboration

Periodic Restore Test

Import Behavior

Conflict Resolution

Data Preservation

Missing Files

Scripting Examples

Automated Backup Restore

Merge Multiple Exports

Selective Import

Comparison with Sync and Export

Common Questions

Troubleshooting

Related Commands

Next Steps