Local Query, Upload, Download, and Debug Bundles
Query local AXP runs, upload completed runs, download platform data, and send debug bundles to the platform app.
AXP keeps raw run files under .axp/runs/<run-id>/ as the durable execution and debug format. axp local run also writes .axp/derived/<run-id>/artifacts.parquet, the source artifact axp upload sends to the platform. Local queries use DuckDB over derived Parquet. (These local artifacts come from axp local run; platform runs from axp run store their results in your org — pull them down with axp download.)
Query local runs
Use axp local query to query a raw local run or downloaded platform Parquet. For raw runs, the CLI derives analytical Parquet under .axp/derived/<run-id>/query/ on demand. For downloaded runs, it reads .axp/downloads/<run-id>/ directly.
axp local query <RUN_ID> <SQL>Examples:
axp local query my-experiment-01HX... "SHOW TABLES" --table
axp local query my-experiment-01HX... "SELECT * FROM runs LIMIT 10" --tableLocal query exposes runs, agent_events, tool_calls, messages, harness_spans, tests, artifacts, and experiment_runs.
Derived files
axp local run writes the lossless source artifact table automatically:
.axp/derived/<run-id>/artifacts.parquetartifacts.parquet stores every raw file under the run directory byte-for-byte. The platform derives analytical tables from it after upload. axp local query creates additional query-only Parquet files under:
.axp/derived/<run-id>/query/Do not treat derived files as the execution record; .axp/runs/<run-id>/ remains the durable format.
Upload a run
Use axp upload to upload one completed AXP run to the platform app.
axp upload [OPTIONS] [RUN_ID]When RUN_ID is omitted, AXP chooses the most recent completed run under ./.axp/runs/.
axp upload
axp upload my-experiment-01HX...axp upload reuses .axp/derived/<run-id>/artifacts.parquet when it exists. For older raw-only runs, it generates that derived artifact from .axp/runs/<run-id>/ before uploading. The platform derives the analytical ClickHouse tables from the raw artifacts after upload. The upload requires saved credentials from axp auth login and uses the active CLI organization by default.
If this is your first upload, sign up or sign in to AXP, open Account settings, and create an API key from the API Keys tab. Paste that key when axp auth login prompts for it. After the CLI saves the key, check the active identity and upload the run:
axp auth login
axp auth whoami
axp upload my-experiment-01HX...If you already have saved CLI credentials, you can skip axp auth login and run axp upload directly.
Use axp auth orgs to list available organizations and axp auth orgs --switch org_... to change the active CLI org. To upload to a different org once without changing the saved active org, pass --org:
axp upload my-experiment-01HX... --org org_...If the same run was already uploaded in the target org, the server rejects the duplicate. Pass --force to overwrite an existing upload of the same run.
axp upload my-experiment-01HX... --forceIf the AXP team gives you a different platform URL, override the upload target with AXP_PLATFORM_URL:
AXP_PLATFORM_URL=https://platform.example.com axp upload my-experiment-01HX...On success, the CLI prints that artifacts were uploaded and that the platform is deriving analytical tables, then points you to the Experiments area. After derivation completes, open the uploaded experiment to inspect aggregate metrics, runs, variant results, test output, timeline spans, and agent events. Platform pages require a signed-in user and active organization.
Send a debug bundle
Use axp send-debug when the AXP team asks for a self-contained bundle to reproduce or debug a run.
axp send-debug [OPTIONS] [RUN_ID]When RUN_ID is omitted, AXP chooses the most recent completed run under ./.axp/runs/.
axp send-debug
axp send-debug my-experiment-01HX...The command builds a .tar.gz bundle containing the run, the source experiment YAML captured at run time, and host metadata such as the AXP CLI version and OS/architecture. It requires saved credentials from axp auth login and uses the active CLI organization by default.
Debug bundles include agent and test logs verbatim. If a setup script, test, or agent output printed a secret, that secret will be present in the bundle. The CLI warns and prompts before uploading; pass --yes only when you have already checked that the bundle is safe to send.
To include context for the recipient, add a note:
axp send-debug my-experiment-01HX... --note "failure reproduces on main"To inspect the bundle locally without uploading it, use --dry-run with --out:
axp send-debug my-experiment-01HX... --dry-run --out debug-bundle.tar.gzWorkspaces can be large. To shrink the bundle, exclude the per-variant workspace copy or filesystem diff:
axp send-debug my-experiment-01HX... --no-workspace --no-fs-diffTo send to a different org once without changing the saved active org, pass --org:
axp send-debug my-experiment-01HX... --org org_...Inspect uploaded runs
After artifacts.parquet finishes uploading, the platform derives analytical tables from those raw artifacts. The experiment page lists uploaded runs and variant results. Run pages summarize cost, token usage, wall-clock time, tool calls, and tests. Variant pages show the resolved variant details, tests, timeline spans, and agent trace for that variant.
Agents that analyze local results can use:
axp prompt analyze <run-id>The generated analysis prompt uses axp local query against .axp/runs/<run-id>/ or .axp/downloads/<run-id>/.
Derivation is best-effort relative to the table upload response. If artifacts commit successfully but bookkeeping or derivation start fails, the upload can still report success while the platform logs the follow-up failure.
Passing --force replaces the uploaded artifacts for that run and marks any previous upload and derivation records as stale. During the replacement upload, the platform shows the run as uploading. After artifacts.parquet finishes uploading, the run returns to complete and the platform pages read from the refreshed analytical tables as derivation updates them.
Download a run
Use axp download to download a run's Parquet files from the platform app.
axp download [OPTIONS] [RUN_ID]When RUN_ID is omitted, AXP chooses the most recent completed local run under ./.axp/runs/. When you pass an explicit ID, the platform is the source of truth; the run does not need to exist locally.
axp download
axp download my-experiment-01HX...Downloads require saved credentials from axp auth login, use the active CLI organization by default, and write files under:
.axp/downloads/<run-id>/If that destination already exists, pass --force to replace it.
axp download my-experiment-01HX... --forceTo download from a different org once without changing the saved active org, pass --org:
axp download my-experiment-01HX... --org org_...If a run exists in a different org that your API key can access, the platform error suggests either --org <org-id> or axp auth orgs --switch <org-id>. If the run is not in an accessible org, the error stays generic.
Upload behavior
The CLI uploads artifacts.parquet in 1 MiB chunks. The request includes the active organization or --org override, the run ID, the table name, chunk index, total chunk count, an idempotency key, force, and upload schema version 6.
Transient upload errors are retried with backoff. Authentication errors ask you to run axp auth login; duplicate uploads ask you to pass --force. If chunks from an earlier upload attempt arrive after a replacement upload has started, the platform rejects that stale attempt instead of reviving it.
The server records upload completion in Supabase. Once artifacts.parquet is complete, it marks the uploaded run complete, attempts to start platform derivation, and then starts the analysis workflow described above.
axp download streams each table back from the platform app, verifies the streamed byte count and SHA-256 trailer for every file, and retries transient transport errors with backoff.
axp send-debug uploads the tar.gz bundle in 1 MiB chunks. Transient upload errors are retried with backoff. On completion, the platform stores the bundle in a private debug-bundles bucket and records an index row in the supabase.debug_bundles table.