Skip to main content

​
Usage

codaph repair cloud [options]
Repairs missing or incomplete cloud sync by replaying events from the local .codaph mirror to Mubit, then republishing shared session and diff artifacts.

​
Use Cases

​
When to Use Repair

  • Interrupted sync - Network failure during initial push
  • Missing events - Cloud out of sync with local mirror
  • Artifact corruption - Session summaries or diffs not published
  • Migration - Moving to new Mubit project ID

​
When NOT to Use Repair

Do not use repair if:
  • Cloud and local are already in sync (check with codaph status)
  • You haven’t run codaph push yet (run push first)
  • Mubit API key is not configured

​
Options

​
--cwd
string
Working directory path. Defaults to current directory.
​
--session
string
Repair specific session ID only instead of all sessions.
​
--json
boolean
default:"false"
Output results in JSON format.
​
--mubit-api-key
string
Mubit API key. Can also be set via MUBIT_API_KEY environment variable.
​
--mubit-project-id
string
Mubit project ID to sync to. Auto-detected if not specified.
​
--dry-run
boolean
default:"false"
Preview what would be repaired without making changes.

​
Repair Process

The repair command:
  1. Reads local mirror - Loads all events from .codaph/
  2. Replays to Mubit - Sends events to cloud with deduplication
  3. Publishes artifacts - Regenerates session summaries and diff artifacts
  4. Verifies sync - Confirms cloud state matches local

​
Examples

​
Repair all sessions

codaph repair cloud

​
Repair specific session

codaph repair cloud --session ses_abc123

​
Preview repair (dry run)

codaph repair cloud --dry-run

​
Repair with JSON output

codaph repair cloud --json

​
Repair for specific project

codaph repair cloud --cwd /path/to/project

​
Output Format

Repair provides progress updates: 
Repairing cloud sync from local mirror...
Found 3 sessions with 456 events
Replaying events to Mubit: [##########] 456/456
Publishing session summaries: 3/3
Publishing diff artifacts: 3/3
✓ Cloud repair complete
  Replayed: 456 events
  Sessions: 3
  Deduped: 12 events (already in cloud)
  Published: 6 artifacts

​
JSON Output Example

{
  "repoId": "owner/repo",
  "sessionCount": 3,
  "totalEvents": 456,
  "replayedEvents": 444,
  "deduplicatedEvents": 12,
  "publishedArtifacts": 6,
  "sessions": [
    {
      "sessionId": "ses_abc123",
      "events": 156,
      "replayed": 156,
      "deduped": 0
    }
  ],
  "duration": "15.2s"
}

​
Safety Features

​
Deduplication

Repair uses event IDs to deduplicate:
  • Skips events already in Mubit
  • Prevents duplicate writes
  • Idempotent operation (safe to run multiple times)

​
Validation

Before replay:
  • Verifies local mirror integrity
  • Checks Mubit API connectivity
  • Validates event schemas

​
Rollback

Repair does not modify local mirror:
  • Local data remains unchanged
  • Only cloud state is updated
  • Can be safely retried

​
Performance

  • Batch writes - Events sent in batches of 24
  • Concurrency - Up to 2 concurrent writes
  • Timeout - 15 second timeout per batch
Typical performance:
  • 100 events: ~5 seconds
  • 1000 events: ~30 seconds
  • 10000 events: ~5 minutes

​
Troubleshooting

​
Repair fails with “Mubit disabled”

Problem: Mubit API key not configured Solution: 
export MUBIT_API_KEY=your_key_here
codaph repair cloud

​
Repair hangs

Problem: Network timeout or large dataset Solution: Check network and increase timeout: 
codaph repair cloud --mubit-write-timeout-ms 30000

​
Some events not replayed

Problem: Events already in cloud Explanation: This is expected - repair deduplicates by event ID

​
Artifacts not publishing

Problem: Artifact generation failure Solution: Check logs and retry: 
codaph repair cloud --session ses_abc123

​
Recovery Scenarios

​
Scenario 1: Interrupted Initial Push

# Initial push failed halfway
codaph push  # Failed at 50%

# Repair completes the push
codaph repair cloud

​
Scenario 2: Missing Artifacts

# Events synced but artifacts missing
codaph status  # Shows events synced, artifacts missing

# Repair regenerates artifacts
codaph repair cloud

​
Scenario 3: Project Migration

# Moving to new Mubit project
export MUBIT_PROJECT_ID=new-owner/new-repo

# Repair syncs all data to new project
codaph repair cloud

Build docs developers (and LLMs) love

Get started for freeTalk to us