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

> Import sudocode data from JSONL files into the SQLite database

## Syntax

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

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

## Arguments

<ParamField path="--input" type="string" required>
  Input directory containing JSONL files

  **Example:** `--input backups/2025-10-29`

  Directory must contain `specs.jsonl` and/or `issues.jsonl` files.
</ParamField>

## Examples

### Basic Import

Import from a directory:

```bash theme={null}
sudocode import --input .sudocode/
```

<Accordion title="Expected output">
  ```
  ✓ Imported from JSONL
    Input: .sudocode/
  ```
</Accordion>

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

### Restore from Backup

Restore database from backup:

```bash theme={null}
sudocode import --input backups/2025-10-29/
```

<Accordion title="Expected output">
  ```
  ✓ Imported from JSONL
    Input: backups/2025-10-29/
  ```
</Accordion>

### Initialize New Database

Set up fresh database from JSONL:

<Steps>
  <Step title="Ensure clean state">
    ```bash theme={null}
    rm -f .sudocode/sudocode.db  # Remove old database
    ```
  </Step>

  <Step title="Import from JSONL">
    ```bash theme={null}
    sudocode import --input .sudocode/
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    sudocode status
    ```
  </Step>
</Steps>

### Import Shared Data

Load data shared by team member:

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

<Accordion title="Expected output">
  ```
  ✓ Imported from JSONL
    Input: team-export/

  ✓ Synced 59 entities to markdown
  ```
</Accordion>

### JSON Output

Get machine-readable output:

```bash theme={null}
sudocode --json import --input backups/2025-10-29/
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "success": true,
    "inputDir": "backups/2025-10-29/"
  }
  ```
</Accordion>

## How Import Works

Import processes JSONL files line by line:

<Steps>
  <Step title="Read JSONL files">
    Parse `specs.jsonl` and `issues.jsonl` from input directory

    Each line is one JSON object representing an entity
  </Step>

  <Step title="Validate data">
    Check for required fields and valid structure

    Skip or error on invalid entries
  </Step>

  <Step title="Insert/update database">
    For each entity:

    * Check if ID exists in database
    * Insert if new, update if exists
    * Preserve UUIDs and timestamps
  </Step>

  <Step title="Import relationships">
    If `relationships.jsonl` exists, import relationship data

    Tags and other metadata embedded in entity records
  </Step>
</Steps>

## Common Workflows

### Disaster Recovery

Recover from database corruption:

<Steps>
  <Step title="Backup corrupted database">
    ```bash theme={null}
    mv .sudocode/sudocode.db .sudocode/sudocode.db.corrupted
    ```
  </Step>

  <Step title="Import from JSONL (source of truth)">
    ```bash theme={null}
    sudocode import --input .sudocode/
    ```
  </Step>

  <Step title="Sync to markdown">
    ```bash theme={null}
    sudocode sync --to-markdown
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    sudocode status
    sudocode spec list
    sudocode issue list
    ```
  </Step>
</Steps>

### Migration from Old Version

Migrate data from older sudocode version:

<Steps>
  <Step title="Export from old version">
    In old project:

    ```bash theme={null}
    sudocode-old export --output migration-data/
    ```
  </Step>

  <Step title="Copy JSONL files">
    ```bash theme={null}
    cp migration-data/*.jsonl new-project/.sudocode/
    ```
  </Step>

  <Step title="Import in new version">
    In new project:

    ```bash theme={null}
    sudocode import --input .sudocode/
    sudocode sync --to-markdown
    ```
  </Step>

  <Step title="Verify migration">
    ```bash theme={null}
    sudocode stats
    ```

    Compare counts with old project
  </Step>
</Steps>

### Team Collaboration

Share and merge project data:

<Steps>
  <Step title="Team member A exports">
    ```bash theme={null}
    sudocode export --output shared/alice-work/
    ```
  </Step>

  <Step title="Team member B receives and imports">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Handle conflicts">
    Review imported changes and resolve any conflicts manually
  </Step>
</Steps>

### Periodic Restore Test

Verify backups are valid:

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

<Warning>
  Import will **overwrite** existing data for matching IDs. Always backup before importing if you have unsaved local changes.
</Warning>

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

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

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

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

<CardGroup cols={3}>
  <Card title="import" icon="file-import">
    **JSONL → Database**

    * One direction
    * Overwrites database
    * No markdown involved
    * Restoration/migration

    ```bash theme={null}
    sudocode import --input dir/
    ```
  </Card>

  <Card title="export" icon="file-export">
    **Database → JSONL**

    * One direction
    * Overwrites JSONL
    * No markdown involved
    * Backup/extraction

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

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

    * Auto-detects direction
    * Handles all layers
    * Complete workflow
    * Normal operations

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

**Typical workflow:**

1. **Normal operations**: Use `sync`
2. **Create backup**: Use `export`
3. **Restore backup**: Use `import` then `sync --to-markdown`

## Common Questions

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    rm .sudocode/sudocode.db
    sudocode import --input backups/2025-10-29/
    ```
  </Accordion>

  <Accordion title="What happens to markdown files after import?">
    Import only updates the database. To update markdown:

    ```bash theme={null}
    sudocode import --input backups/2025-10-29/
    sudocode sync --to-markdown
    ```
  </Accordion>

  <Accordion title="Can I import from multiple sources?">
    Yes, but sequential imports will overwrite conflicts. For merging:

    1. Merge JSONL files manually using `jq`
    2. Import the merged result
  </Accordion>

  <Accordion title="Are relationships imported?">
    Yes, if relationship data is embedded in entity records or if `relationships.jsonl` exists in the input directory.
  </Accordion>

  <Accordion title="What if JSONL format is invalid?">
    Import will skip or error on invalid lines. Check logs for specific errors. Validate with:

    ```bash theme={null}
    jq '.' input/specs.jsonl > /dev/null
    ```
  </Accordion>

  <Accordion title="Can I import into an existing project?">
    Yes, import merges with existing data. Matching IDs are updated, new IDs are added. Always backup first:

    ```bash theme={null}
    sudocode export --output backups/pre-import/
    sudocode import --input new-data/
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Input directory doesn't exist">
    **Cause:** Path is incorrect or directory not found

    **Solution:**
    Verify path:

    ```bash theme={null}
    ls -la backups/2025-10-29/
    ```

    Use absolute path if needed:

    ```bash theme={null}
    sudocode import --input /full/path/to/backups/2025-10-29/
    ```
  </Accordion>

  <Accordion title="Error: No JSONL files found">
    **Cause:** Directory doesn't contain `specs.jsonl` or `issues.jsonl`

    **Solution:**
    Check contents:

    ```bash theme={null}
    ls backups/2025-10-29/
    ```

    Ensure at least one JSONL file exists.
  </Accordion>

  <Accordion title="Import succeeds but data is missing">
    **Cause:** May have imported to wrong database or database not synced to markdown

    **Solution:**

    1. Check database:
       ```bash theme={null}
       sudocode status
       ```
    2. Sync to markdown:
       ```bash theme={null}
       sudocode sync --to-markdown
       ```
  </Accordion>

  <Accordion title="Import fails with parse error">
    **Cause:** Invalid JSON in JSONL file

    **Solution:**
    Validate JSONL:

    ```bash theme={null}
    jq '.' backups/2025-10-29/specs.jsonl > /dev/null
    ```

    Fix or regenerate JSONL files from a clean source.
  </Accordion>

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

    **Solution:**

    1. Close other sudocode processes
    2. Wait and retry
    3. Check for zombie processes:
       ```bash theme={null}
       ps aux | grep sudocode
       ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="export" icon="file-export" href="/cli/export">
    Export to 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 import results
  </Card>
</CardGroup>

## Next Steps

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

  <Step title="Import data">
    ```bash theme={null}
    sudocode import --input new-data/
    ```
  </Step>

  <Step title="Sync to markdown">
    ```bash theme={null}
    sudocode sync --to-markdown
    ```
  </Step>

  <Step title="Verify import">
    ```bash theme={null}
    sudocode status
    sudocode spec list
    sudocode issue list
    ```
  </Step>

  <Step title="Commit changes">
    ```bash theme={null}
    git add .sudocode/
    git commit -m "Import data from backup"
    ```
  </Step>
</Steps>

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