chronicle [OPTIONS] <MOUNT_POINT>
Arguments
| Argument | Required | Description |
|---|
MOUNT_POINT | Yes | Directory to mount the filesystem on |
Options
Identity
| Flag | Short | Default | Description |
|---|
--agent-id | -a | hostname-PID | Agent identifier for namespacing |
Storage
| Flag | Short | Default | Description |
|---|
--database | -d | ~/.chronicle/{agent_id}/chronicle.db | SQLite database path |
--cas-dir | -c | ~/.chronicle/{agent_id}/cas | CAS storage directory |
--pooled-cas | | false | Share CAS across agents (~/.chronicle/shared_cas/) |
S3 Tiered Storage
| Flag | Default | Description |
|---|
--s3-bucket | None | S3 bucket for CAS backing |
--s3-prefix | "" | S3 key prefix |
--s3-async-upload | true | Non-blocking S3 uploads |
Replication (Agent Mode)
| Flag | Short | Default | Description |
|---|
--replication | -r | false | Enable replication server |
--socket | -s | ~/.chronicle/{agent_id}/chronicle.sock | Unix socket path |
--ws-listen | | None | WebSocket listen address (e.g., 0.0.0.0:3002) |
Replication (Sandbox Mode)
| Flag | Short | Description |
|---|
--connect | -c | Connect to agent Unix socket path |
--ws-connect | | Connect to agent WebSocket URL |
--replication, --connect, and --ws-connect are mutually exclusive.
Filtering
| Flag | Description |
|---|
--exclude | Gitignore pattern to exclude from sync |
--include | Gitignore pattern to include (overrides excludes) |
FSKit (macOS)
| Flag | Default | Description |
|---|
--fskit | auto | FSKit mode: auto, force, disable |
Examples
Standalone (development)
chronicle /tmp/workspace --agent-id dev-agent
With S3 backing
chronicle /tmp/workspace \
--agent-id prod-agent \
--s3-bucket my-chronicle-cas \
--pooled-cas
Agent mode (accepting sandbox connections)
chronicle /instances/agent123/mount \
--agent-id agent123 \
--replication \
--ws-listen 0.0.0.0:3002 \
--s3-bucket chronicle-cas
Sandbox mode (connecting to agent)
chronicle /sandbox/workspace \
--agent-id sandbox-1 \
--connect /instances/agent123/chronicle.sock
Sandbox mode over WebSocket (E2B)
chronicle /sandbox/workspace \
--agent-id sandbox-1 \
--ws-connect ws://agent-host:3002
