pChronicle CLI¶

This page is the English reference for the canonical pchronicle command line. New commands and scripts should use the syntax documented here.

Find the command you need¶

Start with the shortest path to a useful answer:

Try the product: pchronicle onboard query uses temporary example data and needs no Dataset path.
Check a Dataset: use list/ls and stats overview before writing SQL.
Locate a run or phrase: use find --run-id, --session-id, or --match; inspect the returned identity before querying more data.
Ask a repeatable question: use query --sql or query --file and set output and resource limits for automation.
Expose history: use serve only after the read-only query works; the serve guide explains the lifecycle and shutdown path.

For a first interaction, copy this sequence:

pchronicle onboard query
pchronicle list ./trajectory-data
pchronicle query ./trajectory-data --sql 'SELECT COUNT(*) FROM dataset.runs'

The second and third commands require a Dataset you already have. If you do not have one, stop after onboard query and continue with the Dataset walkthrough.

Dataset¶

A Dataset is a path. pChronicle opens that path as the trajectory store. It may be:

a local directory or file, such as ./local/path;
an object-store URI prefix, such as s3://bucket/prefix;
a dataset pin that resolves to either location, such as @prod.

Global syntax¶

pchronicle [-c FILE] [--log-level error|warn|info|debug] <COMMAND> ...

-c, --config selects the user configuration file. --log-level controls stderr diagnostics without changing stdout results or exit status. For pchronicle serve, the same flag also filters Warehouse request tracing (pchronicle.serve).

Commands¶

Onboard¶

pchronicle onboard [SECTION] [DATASET] [--no-pause]

pchronicle onboard
pchronicle onboard query @prod

The default onboard (or onboard basics) teaches listing, a summary, and one SQL question. Use onboard all for the complete curriculum. Topic commands pause in an interactive terminal (Enter to continue, q to quit); --no-pause or redirected output disables prompts.

The complete walkthrough covers Dataset discovery, health and built-in analysis, normalized SQL, unified FTS/JSONB find expressions, cross-format queries, Storyline Lance import/export, and the read-only Web/API boundary. Use pchronicle onboard find DATASET to inspect the search grammar directly.

Dataset pins¶

pchronicle dataset pin|unpin|list|show|set|rename …

pchronicle dataset pin default ./trajectory-data
pchronicle dataset show default
pchronicle dataset pin prod s3://bucket/evals
pchronicle dataset pin secure s3://bucket/evals --ak "$AWS_ACCESS_KEY_ID" --sk "$AWS_SECRET_ACCESS_KEY"
pchronicle dataset pin minio s3://bucket/evals --endpoint http://127.0.0.1:9000 --region us-west-2 --ak 123 --sk 123
pchronicle dataset pin regional s3://bucket/evals --region us-west-2
pchronicle dataset pin team catalog://127.0.0.1:8081 --ak USER_AK --sk USER_SK
pchronicle dataset set prod s3://new-bucket/evals
pchronicle dataset list
pchronicle stats @prod

default is a reserved pin used when a command omits DATASET_URI. It must be a local directory. Other pins only update user configuration; they do not move or delete Dataset data. Pins are stored under [pins.<name>] in the user config file (-c / PCHRONICLE_CONFIG). Example:

[pins.default]
uri = "/abs/path/to/warehouse"

[pins.prod]
uri = "s3://bucket/evals"
endpoint = "http://127.0.0.1:9000"
region = "us-west-2"
access_key = "..."
secret_key = "..."

Legacy keys such as default_warehouse or aliases are rejected. S3 credentials supplied with --ak and --sk are stored on the same pin table and applied through the standard AWS environment variables when the pin is used. They are not printed by dataset list or dataset show. dataset list also includes the built-in @codex, @claude, and @claude-code pins for the corresponding local Agent session roots. For S3-compatible services such as MinIO, pass the endpoint with --endpoint. Keep the Dataset URI in the form s3://bucket/prefix. A catalog://127.0.0.1:PORT pin is a Directory locator. @team/prod fetches a ticket and opens the ticket uri; @team by itself lists authorized Datasets. Directory pins require --ak and --sk and reject --endpoint and --region. See RFC-0013. For http:// endpoints, pChronicle also enables AWS_ALLOW_HTTP automatically. The optional --region is stored per pin. When an s3:// pin omits it, pChronicle applies us-west-2 as AWS_REGION / AWS_DEFAULT_REGION before opening the store. Endpoint, region, and credentials are applied before the Tokio runtime starts so OpenDAL sees them reliably.

Inspect and find¶

pchronicle list|ls [DATASET] [--sources] [OPTIONS]
pchronicle stats [DATASET] [OPTIONS]
pchronicle stats <overview|agents|models|tools> [DATASET] [OPTIONS]
pchronicle find [DATASET]
 (--run-id ID|--document-id ID|--session-id ID|--match EXPRESSION) [OPTIONS]

pchronicle list @prod --format json
pchronicle stats @prod --format json
pchronicle stats overview @prod
pchronicle find @prod --session-id session-42
pchronicle find ./dataset --match "timeout" --match "retry" --format json
pchronicle find ./dataset --match '$.tags=important' --match '$.priority=2' --format json

list (ls) lists one directory level, like a shell ls. Dataset children show type and trajectory count from chronicle.manifest when present. --sources opens the path and prints Snapshot members (the virtual dataset query will union). Bare stats reports Dataset health and counts after the path is opened as a Snapshot. stats overview|agents|models|tools runs the built-in statistical reports. --match is the unified search expression. Plain terms search Storyline Step content with the indexed FTS/Jieba path; scoped forms such as #system(prompt) select a field, and AND/OR/NOT combine predicates. JSONB predicates use $.path=value (or #json("$.path")=value) and perform exact JSONPath value matching. Repeat --match to require all expressions. A JSON-only expression currently searches run-level JSONB columns; a mixed text/JSON expression searches step-level JSONB columns. An explicit #json.metrics(...) selector also targets step-level JSONB without a text term. CLI and Web share this expression, the reported search.scope, and snapshot_id. The Web UI may highlight and clip returned fields without changing the match set. Each match includes a bounded preview field to make candidate selection possible before a follow-up query. JSON output also reports search.mode (fts, json, fts+json, or identity), search.scope (steps or runs), and FTS availability/tokenizer metadata. The current grammar is documented in the query model. RFC-0012 records the accepted decision; where they disagree, the installed CLI wins.

Query¶

pchronicle query [DATASET|--mount NAME=DATASET ...] (--sql SQL|--file FILE_OR_STDIN) [OPTIONS]

pchronicle query ./dataset --sql 'SELECT COUNT(*) FROM dataset.runs'
pchronicle query \
 --mount live=./live --mount archive=@archive \
 --file report.sql

Each invocation accepts one read-only statement with explicit resource limits. --file - reads SQL from stdin. Use --format, --output, --max-output-rows, --max-output-bytes, and --timeout to make pipeline behavior explicit.

Import¶

pchronicle import -f|--from SOURCE -t|--to NEW_DATASET
 [-i|--input-format auto|atif|actf|openai-messages|storyline|codex|claude-code|compact-jsonl]
 [-o|--output-format preserve|storyline|compact-jsonl]
 [|--replace] [--append] [--on-duplicate suffix|skip] [--yes]
 [--resume] [--wal-dir DIR] [--reset]
 [--column NAME=JSON_PATH]... [OPTIONS]

pchronicle import -f input.json -t ./imported -i atif
cat input.json | pchronicle import -f - -t ./imported -i openai-messages
pchronicle import -f more.json -t ./normalized --append --on-duplicate skip
pchronicle import -f rebuilt.json -t ./normalized --replace --yes
pchronicle import -f s3://bucket/corpus -t s3://bucket/out -o storyline --resume
pchronicle import -f ./jsonl-root -t ./records.lance \
 -o compact-jsonl \
 --column id=$.event.id --column timestamp=$.event.time \
 --column model=$.payload.model

- means stdin. Create is the default and requires a new destination. --append requires an existing Storyline Dataset and either suffixes colliding document_id values with #N (the default) or skips them. --replace moves the old local Dataset aside, publishes the fully imported Dataset with a rename transaction, and only then removes the old data. It requires interactive confirmation or --yes; an existing object-store Dataset cannot currently be replaced in place.

Long Storyline imports write a local checkpoint WAL under ./.pchronicle-import-wal/<job_id>/ (job.json, done.jsonl, failed.jsonl). Use --resume with the same --from/--to fingerprint to skip sources already recorded as done or failed; --wal-dir overrides the WAL root; --reset deletes that job's WAL before starting. Decode and skippable commit failures are recorded in the WAL and import.log so the job can continue.

Compact JSONL is a record store, not a trajectory conversion. Either --input-format compact-jsonl or --output-format compact-jsonl selects it. It recursively reads local .json, .jsonl, and .ndjson files. JSON objects and arrays are accepted; each JSON document becomes one record, with arrays kept intact. Missing or invalid id and timestamp values receive stable source_filename#line_number values. The default paths are $.id and $.timestamp. --column id=PATH and --column timestamp=PATH override those paths, while any other --column NAME=PATH adds a nullable JSONB projection. Compact import supports local create and confirmed replace, but not stdin, object-store targets, or append.

Sync¶

pchronicle sync --from DIRECTORY
 [--mirror DIRECTORY] [--to DIRECTORY]
 [--input-format FORMAT] [--suggested-format FORMAT]
 [--column NAME=JSON_PATH]...
 [--interval DURATION] [--once]

sync is a resident polling worker for .json, .jsonl, and .ndjson files. It coalesces changes into a pending set and, on each interval, rebuilds full snapshots for the destinations you enable. Provide --mirror, --to, or both:

--mirror writes a Compact JSONL Lance Dataset (record-level ingest; optional --column mapping). Each successful batch atomically replaces that target.
--to converts trajectories into a Storyline Lance Dataset (--input-format / --suggested-format).

Pending changes clear only after every enabled destination succeeds; failures retain the set and retry with bounded exponential backoff. Use --once for one initial batch and exit. Local destinations must sit outside the source tree.

With --input-format compact-jsonl, only --mirror is allowed (not --to). Each successful batch rescans the tree and atomically replaces the compact Lance snapshot at --mirror.

Drop¶

pchronicle drop DATASET [--yes]

Drop permanently removes a local Dataset directory or object-store prefix. It requires interactive confirmation unless --yes is supplied and refuses filesystem roots or whole object-store buckets.

Export¶

pchronicle export -f|--from DATASET -t|--to TARGET
 -o|--output-format atif|actf|openai-messages|storyline|compact-jsonl [OPTIONS]

pchronicle export -f ./imported -t restored.json -o atif
pchronicle export -f @prod -t - -o actf --session-id session-42

--to - writes stdout. File and object-store destinations are create-only unless --overwrite is explicit.

Agent analysis¶

pchronicle agent <codex|claude> [DATASET]
 [--ask QUESTION|--ask-file FILE_OR_STDIN] [--no-overview] [--dry-run]

pchronicle agent codex ./dataset
pchronicle agent claude @prod --ask 'Compare model latency'

Serve¶

pchronicle serve ./trajectory-data
pchronicle serve --listen 127.0.0.1:8080 train=./train eval=./eval
pchronicle serve --catalog-config catalog.toml --listen 127.0.0.1:8081

The listener is loopback-only. Named mounts provide stable SQL aliases. --open opens the Web UI; --home-link TEXT=PATH adds same-origin navigation links. --catalog-config enables authenticated Directory and data operations and cannot be combined with positional Dataset mounts. Configure datasets and user grants with pchronicle serve catalog; storage credentials remain scoped to each backend and worker. The server emits a readiness JSON record containing warehouse_endpoint.

Refresh builds a replacement Snapshot before switching readers. Failed refresh keeps the previous view readable. Dataset writes remain CLI import operations. Logs go to stderr; --log-level controls verbosity. Failed API requests include code, message, and request_id; internal details remain in the server log.

Output and exit status¶

stdout contains command results, exported content, or readiness JSON. stderr contains diagnostics. Stable boundary exit codes are: 0 success, 2 invalid input, 3 not found, 4 conflict, 5 resource limit, and 6 timeout or a temporarily unavailable dependency. Unclassified internal errors use 1.

Use Discover and query for the locate-then-SQL workflow, Import and export for interchange, and Serve Datasets locally for the read-only server. Snapshot construction is explained in Snapshot design.

Catalog management¶

The Directory ACL file contains users, datasets (libraries), and grants. Management commands create the file when it does not exist.

pchronicle serve catalog issue --catalog-config FILE NAME
pchronicle serve catalog grant --catalog-config FILE NAME DATASET...
pchronicle serve catalog revoke --catalog-config FILE NAME DATASET...
pchronicle serve catalog dataset add --catalog-config FILE NAME --uri URI
 [--endpoint URL] [--region REGION] [--access-key KEY] [--secret-key KEY]
pchronicle serve catalog dataset remove --catalog-config FILE NAME...
pchronicle serve catalog dataset list --catalog-config FILE

issue generates a user AK/SK and prints the secret once. dataset add registers the URI and optional backend storage credentials without creating or deleting object-store data. grant / revoke add or remove library names on that user (v1 grants are library membership, not fine-grained permission flags).

Request execution diagnostics¶

The Requests tab shows the current browser tab session's recent API requests, their request IDs, HTTP outcomes, execution phases and elapsed time. The indicator above Local / profile opens the same tab. Select a request or enter its ID to inspect it while it is running. Worker admission, worker startup and worker execution are separate stages; directory browsing and scoped Runs queries report their own stages. pending stages have not started; skipped stages were not used. Stages describe application operations, not individual DNS, TCP or S3 requests. A successful partial directory response can still report a background refresh in its note.

GET /api/requests/{request_id} (also under /api/v1) returns the live snapshot: request_id, method, path, state, elapsed_ms, status, error, note, phases (name, state, elapsed_ms) and an optional nested worker snapshot. This endpoint runs in the front server, independently of busy query workers.

Tracking is opt-in: send a cryptographically random 32-character hexadecimal x-pchronicle-observer token with the original request and the diagnostic lookup. Set x-request-id on the original request to look it up before it completes. The UI supplies both headers automatically. The observer token is a private capability, not a replacement for catalog credentials; a different token cannot read the record. The server retains at most 512 records for up to 10 minutes, in memory only; restarting the server clears them. Unknown, expired or inaccessible IDs return 404. The UI keeps 40 recent entries and polls unfinished requests once per second. Diagnostic connection failures are shown separately and can be retried. Query strings, bodies and credentials are not included in the diagnostic record. Internal error details remain in server logs, correlated by request ID.