CLI reference¶

This page lists every benchdb command with its flags, defaults, and environment variables. Use it when you write CI jobs, scripts, or operations tasks that call the CLI. Run benchdb <command> --help to see the same flags from the installed binary:

benchdb --help
benchdb results submit --help
benchdb ci report --help

Common behavior¶

Every command that talks to a server needs --server, except benchdb health. Pass the server's base URL, including any path prefix such as https://example.com/tools/bench.

Exit codes follow one rule across commands:

benchdb ci report uses its own exit codes, listed in its section below.

Credentials¶

These commands send a bearer token when one is available: results submit, history export, ci report, auth token list, and auth token revoke. They resolve the token in this order:

1. --token
2. BENCHDB_TOKEN
3. the credentials file written by benchdb auth login

In CI and shared scripts, set BENCHDB_TOKEN and leave out --token. That keeps the token out of the process argument list.

The credentials file is benchdb/credentials.json in the user config directory. On Linux that is ~/.config/benchdb/credentials.json, or $XDG_CONFIG_HOME/benchdb/credentials.json when XDG_CONFIG_HOME is set. On macOS it is ~/Library/Application Support/benchdb/credentials.json. It maps each --server value to a token, so the server URL must match the one used at login. The CLI writes the file with mode 0600.

results get, compare, and series list do not send a token.

Database access¶

benchdb migrate and benchdb serve read the database URL from BENCHDB_DB_URL or BENCHDB_DB_URL_FILE, and fall back to DATABASE_URL when neither is set. The benchdb admin commands accept only BENCHDB_DB_URL or BENCHDB_DB_URL_FILE. Setting both BENCHDB_DB_URL and BENCHDB_DB_URL_FILE is an error. See Operations for the full rules on _FILE secrets.

Results¶

benchdb results submit¶

Submit one or more benchmark result JSON files:

benchdb results submit <file-or-glob>... --server URL

Quote globs so the CLI expands them instead of the shell:

benchdb results submit "bench-results/*.json" --server "$BENCHDB_SERVER_URL" --jobs 16

A glob that matches no files is a usage error. Each file can hold one result object or an array of result objects. The CLI rejects payloads with unknown fields.

With exactly one result, the command prints one line on success:

{"id":"...","history_fingerprint":"..."}

With more than one result, it prints one JSON line per result with file, index for array entries, ok, and either id and history_fingerprint or error. If any submission fails, the command exits 1 after printing every line. See Submitting results for the payload shape.

benchdb results get¶

Fetch one result as JSON:

benchdb results get <id> --server URL

Reading and comparing¶

benchdb compare¶

Compare two results and print the comparison as JSON:

benchdb compare <baseline-id> <contender-id> --server URL

benchdb series list¶

List benchmark series as JSON:

benchdb series list --server URL

benchdb history export¶

Export the history of one result's series as CSV:

benchdb history export <result-id> --server URL --output history.csv

See Browsing and comparing for the dashboard views these commands mirror.

CI¶

benchdb ci report¶

Render a benchmark report for a commit or a set of runs:

benchdb ci report --server URL --repository REPO --commit SHA
benchdb ci report --server URL --repository REPO --commit SHA --run-ids RUN_IDS
benchdb ci report --server URL --run-ids CONTENDER_IDS --baseline-run-ids BASELINE_IDS

You must pass --repository and --commit, --run-ids, or both. --github-check and --github-pr-comment also need --repository and --commit.

For GitHub publishing, the CLI reads credentials from flags first, then the environment:

The CLI reads the token variables only when no token, App ID, or App private key came from a flag or the App variables.

A typical publishing call from a CI runner:

benchdb ci report \
  --server URL \
  --repository REPO \
  --commit SHA \
  --github-check \
  --github-pr-comment \
  --github-pr-number PR_NUMBER \
  --build-url BUILD_URL

Use --format markdown --output benchdb-report.md to produce a CI step summary. Exit codes:

See CI reporting for the metadata contract, a GitHub Actions example, baseline modes, and how the report status is chosen.

Authentication¶

benchdb auth login¶

Sign in through the browser and store a user-owned API token:

benchdb auth login --server URL

The command listens on 127.0.0.1 on a free port, opens the browser, and waits up to 3 minutes for the login to finish. It saves the token to the credentials file and prints only the server and the token prefix.

benchdb auth token list and benchdb auth token revoke¶

List or revoke your API tokens. Each command prints one line of JSON:

benchdb auth token list --server URL
benchdb auth token revoke <token-id> --server URL

These commands need a user-owned token or session. The static operator token gets 403. See Authentication and tokens.

Operations¶

The benchdb admin commands connect to PostgreSQL directly. Run them where BENCHDB_DB_URL or BENCHDB_DB_URL_FILE is set. Alert evaluation also needs the server's archive volume and matching DuckDB extensions. See Evaluation for scheduling requirements.

benchdb admin tokens create¶

Mint a reporter token without a browser login:

benchdb admin tokens create --email ci@example.com --token-name buildkite

The command creates the user if needed and prints one JSON line with user_id, token_id, email, user_name, token_name, token, prefix, and created_at. The plaintext token appears only in this output.

benchdb admin repair-commits¶

Repair stored commit rows that were saved as unknown, once GitHub metadata is available:

benchdb admin repair-commits --format json

This command needs GitHub credentials. Set either GITHUB_API_TOKEN with at least one usable token, or all of BENCHDB_COMMIT_GITHUB_APP_ID, BENCHDB_COMMIT_GITHUB_APP_INSTALLATION_ID, and BENCHDB_COMMIT_GITHUB_APP_PRIVATE_KEY_FILE. Setting both is an error.

benchdb admin alerts evaluate¶

Evaluate every enabled alert rule:

benchdb admin alerts evaluate --format json

The command reads BENCHDB_INTENDED_BASE_URL, when set, to build absolute report links.

benchdb admin alerts deliver¶

Send stored alert events to one channel:

benchdb admin alerts deliver --channel webhook --format json
benchdb admin alerts deliver --channel slack --format json
benchdb admin alerts deliver --channel github-check --format json
benchdb admin alerts deliver --channel github-comment --format json
benchdb admin alerts deliver --channel email --format json

Webhook, Slack, and GitHub API URLs must be http or https. See Alerting for rule evaluation, the delivery outbox, and each channel's message format.

Server and schema¶

benchdb serve¶

Run the API server and the embedded dashboard:

benchdb serve

serve has no flags. It reads its configuration from environment variables listed in Operations.

benchdb migrate¶

Apply database schema migrations and print database schema is current:

benchdb migrate

migrate has no flags. It uses the database URL rules in Database access.

benchdb openapi¶

Print the OpenAPI document to stdout:

benchdb openapi
benchdb openapi --downgrade

See API and SDK for the generated clients.

benchdb health¶

Check that a server process is up. The command needs no database configuration and sends no credentials:

benchdb health --server http://127.0.0.1:8080 --timeout 5s

The command requests /api/ping and prints ok on success. It exits nonzero on an HTTP error, a redirect, a timeout, or a response that is not {"status":"ok"} within 4 KiB. It does not query PostgreSQL.