Skip to main content
Sync Mubit cloud activity to your local .codaph/ mirror. This is the primary daily workflow command.

​
Usage

codaph pull [options]

​
Description

The pull command:
  1. Fetches recent timeline events from Mubit (project/session scope)
  2. Imports new events to local .codaph/ mirror
  3. Deduplicates events already present locally
  4. Updates remote sync state
This is a fast, incremental sync that doesn’t replay local agent history. For backfilling historical sessions, use codaph push.

​
Flags

​
--cwd
string
Working directory (defaults to current directory)
​
--json
boolean
default:"false"
Output JSON instead of human-readable summary
​
--refresh
boolean
default:"true"
Refresh timeline from Mubit (disable with --no-refresh for cached data)
​
--timeline-limit
number
default:"1200"
Maximum timeline events to fetch from MubitAlternative flag: --limit

​
Mubit Configuration

​
--mubit-api-key
string
Override Mubit API key (or use MUBIT_API_KEY env var)
​
--mubit-project-id
string
Override Mubit project ID
​
--mubit-actor-id
string
Override actor ID

​
Examples

​
Basic Pull

codaph pull
Output: 
Querying Mubit run scope: codaph:owner/my-project
Pull (cloud->local): snapshot received=150/1200, imported=12, dedup=138, skipped=0
Remote sync run: codaph:owner/my-project

​
Pull with Custom Limit

codaph pull --timeline-limit 500

​
Pull in Specific Directory

codaph pull --cwd ~/my-project

​
JSON Output

codaph pull --json

{
  "runId": "codaph:owner/my-project",
  "timelineEvents": 150,
  "requestedTimelineLimit": 1200,
  "imported": 12,
  "deduplicated": 138,
  "skipped": 0,
  "suspectedServerCap": false,
  "noRemoteChangesDetected": false,
  "promptTimelineEvents": 5,
  "sessionSummaryTimelineEvents": 3,
  "diffTimelineEvents": 2
}

​
Output Details

​
Standard Output

Pull (cloud->local): snapshot received=150/1200, imported=12, dedup=138, skipped=0, prompt-stream=5, session-stream=3, diff-stream=2
  • received - Events fetched from Mubit
  • requested - Timeline limit (max to fetch)
  • imported - New events added to local mirror
  • dedup - Events already present (deduplicated)
  • skipped - Events skipped (invalid or filtered)
  • prompt-stream - Prompt timeline events
  • session-stream - Session summary events
  • diff-stream - Diff timeline events

​
Cooldown Behavior

If automation is enabled and cooldown is active: 
Pull (cloud->local): skipped (Cooldown active (300s).)
Default cooldown: 300 seconds (5 minutes) Override in project settings: 
{
  "syncAutomation": {
    "remotePullCooldownSec": 600
  }
}

​
Workflow Integration

​
Daily Workflow

# Morning: sync overnight activity
codaph pull

# Browse sessions
codaph tui

# Afternoon: sync again after team commits
codaph pull

​
Automated Pull

If sync automation is enabled during codaph init, pull runs automatically:
  • After git push (if autoPullOnSync enabled)
  • On TUI startup (if autoWarmTuiOnOpen enabled)
  • After agent completion (respects cooldown)
Manual pull: 
codaph pull

​
Mubit Run Scope

Pull fetches events based on Mubit run scope:

​
Project Scope (default)

RunId: codaph:owner/my-project
Shared run across all contributors to the project.

​
Session Scope

RunId: codaph:owner/my-project:session-abc123
Separate runs per session (if mubitRunScope: "session" configured).

​
Troubleshooting

​
No Mubit API Key

Error: Mubit is disabled. Set MUBIT_API_KEY (or MUBIT_APIKEY) and use --mubit.
Fix: 
codaph setup --mubit-api-key mb_live_...
# OR
export MUBIT_API_KEY=mb_live_...

​
Skipped (Cooldown)

Pull (cloud->local): skipped (Cooldown active (300s).)
Fix: Wait for cooldown or run manually: 
codaph pull  # Manual pull ignores automation cooldown

​
Server Cap Warning

Pull (cloud->local): snapshot received=1200/1200, capped?
Mubit returned the exact limit requested. Actual timeline may be longer. Fix: Increase limit: 
codaph pull --timeline-limit 2400

Build docs developers (and LLMs) love

Get started for freeTalk to us