sudocode sync

Syntax

sudocode sync [options]

Description

The sync command manages data flow between sudocode’s 3-layer storage system: Markdown Files ↔ JSONL Files ↔ SQLite Database Use sync to:

Synchronize after git pull (update local database)
Sync after manual markdown edits
Force a specific sync direction
Watch for changes and auto-sync
Troubleshoot sync issues

Most commands automatically sync when needed. Use manual sync after external changes (git pull, manual file edits) or when troubleshooting.

Storage Architecture

sudocode uses a 3-layer storage system:

Layer 1: Markdown Files

Human-readable spec and issue files in .sudocode/specs/ and .sudocode/issues/Purpose: Version control, human editing, readability

Layer 2: JSONL Files

Line-delimited JSON in .sudocode/specs.jsonl and .sudocode/issues.jsonlPurpose: Git-friendly structured data, source of truth

Layer 3: SQLite Database

Local database .sudocode/sudocode.dbPurpose: Fast queries, relationships, views

Data flow:

User edits markdown → Sync to JSONL → Import to database
CLI updates database → Export to JSONL → Sync to markdown

Options

--watch

boolean

Watch for file changes and auto-syncExample: --watchStarts a file watcher that automatically syncs when files change. Press Ctrl+C to stop.Debounce: 2000ms (2 seconds) delay to batch rapid changes

--from-markdown

boolean

Force sync FROM markdown TO databaseExample: --from-markdownAlways syncs in this direction, regardless of file modification times.Use after: Manual markdown edits, git pull with markdown changes

--to-markdown

boolean

Force sync FROM database TO markdownExample: --to-markdownAlways syncs in this direction, regardless of file modification times.Use after: CLI operations that updated database only

Examples

Automatic Direction Detection

Let sudocode determine sync direction:

sudocode sync

Expected output (markdown is newer)

Detecting sync direction...
  Spec markdown files are newer (2025-10-29 14:30:00 > 2025-10-29 14:00:00)

→ Syncing FROM markdown TO database (markdown is newer)

Syncing from markdown to database...
  Found 12 spec files
  ✓ updated spec SPEC-001
  ✓ updated spec SPEC-002
  ...
  Found 47 issue files
  ✓ updated issue ISSUE-001
  ✓ updated issue ISSUE-002
  ...

✓ Synced 59 files to database

Expected output (already in sync)

Detecting sync direction...
  Specs are in sync; Issues are in sync

✓ Everything is in sync
  Use --from-markdown or --to-markdown to force a specific direction

After Git Pull

Sync database with pulled changes:

git pull
sudocode sync

Expected output

Detecting sync direction...
  Issues JSONL is newer (2025-10-29 15:00:00 > 2025-10-29 14:30:00)

→ Syncing FROM database TO markdown (database is newer)

Syncing from database to markdown...
  Found 47 issues in database
  ✓ updated issue ISSUE-001
  ✓ created issue ISSUE-050
  ...

✓ Synced 48 entities to markdown

Force Sync from Markdown

After manually editing markdown files:

vim .sudocode/specs/authentication-system.md
sudocode sync --from-markdown

Expected output

Syncing from markdown to database...
  Found 12 spec files
  ✓ updated spec SPEC-001
  Found 47 issue files

✓ Synced 12 files to database

Force Sync to Markdown

Regenerate markdown from database:

sudocode sync --to-markdown

Expected output

Syncing from database to markdown...
  Found 12 specs in database
  ✓ updated spec SPEC-001 → authentication-system.md
  ✓ updated spec SPEC-002 → api-design.md
  ...
  Found 47 issues in database
  ✓ updated issue ISSUE-001
  ✓ updated issue ISSUE-002
  ...

✓ Synced 59 entities to markdown

Watch Mode

Auto-sync on file changes:

sudocode sync --watch

Expected output

Starting file watcher...
  Watching: /Users/alice/project/.sudocode
  Press Ctrl+C to stop

  [watch] Detected change in specs/authentication-system.md
  [watch] Syncing...
  [watch] ✓ Synced 1 file to database
  [watch] Exported to JSONL

  [watch] Detected change in issues/ISSUE-001.md
  [watch] Syncing...
  [watch] ✓ Synced 1 file to database
  [watch] Exported to JSONL

Press Ctrl+C to stop the watcher.

JSON Output

Get machine-readable output:

sudocode --json sync

JSON output

{
  "success": true,
  "direction": "from-markdown",
  "syncedCount": 59,
  "errorCount": 0
}

How Sync Direction is Determined

When you run sync without flags, it automatically detects the correct direction:

Compare file modification times

For both specs and issues:

Get most recent markdown file modification time
Get JSONL file modification time

Determine direction for each type

If markdown is newer → sync FROM markdown
If JSONL is newer → sync TO markdown
If timestamps match → no sync needed

Handle conflicts

If specs and issues want different directions:

Prefer FROM markdown (preserves user edits)
Reason: User edits in markdown take precedence

Decision Matrix

Markdown State	JSONL State	Direction	Reason
Newer	Older	`from-markdown`	User edited markdown
Older	Newer	`to-markdown`	Database updated (git pull)
Same	Same	`no-sync`	Already in sync
Missing	Exists	`to-markdown`	Regenerate markdown
Exists	Missing	`from-markdown`	Import to JSONL
Mixed	Mixed	`from-markdown`	Prefer user edits

Common Workflows

Daily Development

Start work

Pull latest changes:

git pull
sudocode sync

Make changes

Edit specs or issues via CLI or markdown:

sudocode issue update ISSUE-001 --status in_progress
# or
vim .sudocode/specs/auth-spec.md

Sync before commit

sudocode sync
git add .sudocode/
git commit -m "Update authentication spec"

After Manual Markdown Edits

Edit markdown

vim .sudocode/specs/authentication-system.md

Sync to database

sudocode sync --from-markdown

Verify changes

sudocode spec show SPEC-001

Troubleshoot Sync Issues

Force resync from JSONL

# Regenerate everything from JSONL (source of truth)
sudocode sync --to-markdown

Check for errors

Look for sync errors in output

Manually inspect

# Compare markdown and JSONL
cat .sudocode/specs/auth-spec.md
cat .sudocode/specs.jsonl | grep SPEC-001

Development with Watch Mode

For active development:

# Terminal 1: Watch and auto-sync
sudocode sync --watch

# Terminal 2: Edit files
vim .sudocode/specs/authentication-system.md

# Terminal 1: See auto-sync messages
# [watch] Detected change...
# [watch] Synced...

Understanding Sync Behavior

Auto-Sync in Commands

Most commands auto-sync as needed:

Creating entities: Database → JSONL → Markdown
Updating entities: Database → JSONL → Markdown
After operations: JSONL export triggered automatically

When manual sync is needed:

After git pull (external changes)
After manual markdown edits
Troubleshooting inconsistencies

Sync Operations

From Markdown:

Read markdown files

Parse frontmatter and content from .sudocode/specs/ and .sudocode/issues/

Update database

Insert or update records in SQLite database

Export to JSONL

Write updated data to specs.jsonl and issues.jsonl

To Markdown:

Read from database

Query all specs and issues from SQLite

Generate markdown

Create markdown files with frontmatter and content

Write files

Save to .sudocode/specs/ and .sudocode/issues/

Watch Mode Details

Watch mode monitors file changes and auto-syncs: Configuration:

Debounce delay: 2000ms (2 seconds)
- Waits 2 seconds after last change before syncing
- Prevents excessive syncs during rapid edits
Watched directories:
- .sudocode/specs/
- .sudocode/issues/
- .sudocode/*.jsonl

Events detected:

File creation
File modification
File deletion

Graceful shutdown:

Press Ctrl+C to stop
Ensures clean exit

Common Questions

When do I need to run sync manually?

Manual sync is needed when:

After git pull (pulled JSONL changes)
After editing markdown files directly
Troubleshooting sync inconsistencies
Regenerating markdown from database

Most CLI operations auto-sync automatically.

What's the difference between sync, export, and import?

sync: Bidirectional, auto-detects direction, handles markdown ↔ database
export: Database → JSONL only
import: JSONL → Database only

Use sync for normal operations, export/import for manual data migration.

Can sync cause data loss?

Generally no, but:

Syncing FROM markdown overwrites database changes
Syncing TO markdown overwrites markdown edits
Always commit to git before major sync operations
JSONL files are the source of truth - never deleted

Why does sync prefer from-markdown in conflicts?

User edits in markdown are considered intentional and take precedence over database state. This protects manual work.

How do I recover from bad sync?

Use git:

git checkout .sudocode/  # Restore from git
sudocode sync             # Resync

Or restore from JSONL:

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

Can I sync individual files?

Not directly. Sync operates on all files. For selective updates, use specific commands:

sudocode spec update SPEC-001 --title "New Title"

Troubleshooting

Sync says 'everything in sync' but files differ

Cause: Modification times are equal despite content differencesSolution: Force specific direction:

sudocode sync --from-markdown
# or
sudocode sync --to-markdown

Sync errors on specific files

Cause: Invalid markdown format or corrupted dataSolution:

Check file format:

head -20 .sudocode/specs/problematic-file.md

Fix frontmatter issues
Resync:
```
sudocode sync --from-markdown
```

Watch mode not detecting changes

Cause: File system watcher issues or editor behaviorSolution:

Restart watch mode
Use manual sync instead
Check editor settings (some use atomic writes that may not trigger watchers)

Sync takes very long

Cause: Large number of filesSolution: Normal for large projects. Consider:

Archiving old entities
Splitting into multiple projects
Using watch mode instead of manual sync

Database out of sync after git merge conflict

Cause: Merge conflict in JSONL filesSolution:

Resolve JSONL conflicts in git

Force import from JSONL:

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

export

Export to JSONL

import

Import from JSONL

status

Check sync status

Next Steps

Pull latest changes

git pull

Sync database

sudocode sync

Verify sync

sudocode status

Start work

Use CLI commands normally - auto-sync handles the rest

Storage Model

Learn more about sudocode’s 3-layer storage architecture

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

Syntax

Description

Storage Architecture

Options

Examples

Automatic Direction Detection

After Git Pull

Force Sync from Markdown

Force Sync to Markdown

Watch Mode

JSON Output

How Sync Direction is Determined

Decision Matrix

Common Workflows

Daily Development

After Manual Markdown Edits

Troubleshoot Sync Issues

Development with Watch Mode

Understanding Sync Behavior

Auto-Sync in Commands

Sync Operations

Watch Mode Details

Common Questions

Troubleshooting

export

import

status

Next Steps

Storage Model

CLI Reference

Spec Commands

Issue Commands

Relationship Commands

Feedback Commands

Query & Sync Commands

​Syntax

​Description

​Storage Architecture

​Options

​Examples

​Automatic Direction Detection

​After Git Pull

​Force Sync from Markdown

​Force Sync to Markdown

​Watch Mode

​JSON Output

​How Sync Direction is Determined

​Decision Matrix

​Common Workflows

​Daily Development

​After Manual Markdown Edits

​Troubleshoot Sync Issues

​Development with Watch Mode

​Understanding Sync Behavior

​Auto-Sync in Commands

​Sync Operations

​Watch Mode Details

​Common Questions

​Troubleshooting

​Related Commands

export

import

status

​Next Steps

Storage Model

Syntax

Description

Storage Architecture

Options

Examples

Automatic Direction Detection

After Git Pull

Force Sync from Markdown

Force Sync to Markdown

Watch Mode

JSON Output

How Sync Direction is Determined

Decision Matrix

Common Workflows

Daily Development

After Manual Markdown Edits

Troubleshoot Sync Issues

Development with Watch Mode

Understanding Sync Behavior

Auto-Sync in Commands

Sync Operations

Watch Mode Details

Common Questions

Troubleshooting

Related Commands

Next Steps