From a data file to a saved forecast.

Use a terminal with Node.js 22 or newer and npm. This installs the published release; run the installation command again to update an existing CLI to this version.

node --version
# Requires Node.js 22 or newer
npm install --global ephemeris-cli@0.5.1
ephemeris version --json
ephemeris --help

If global installation is unavailable, use npx --yes --package ephemeris-cli@0.5.1 ephemeris --help. Replace the final command with the operation you need. If your shell cannot find ephemeris, check that npm’s global bin directory is on your PATH, or use npx.

version --json reports this installed CLI, its build identity and local schema versions. The hosted MCP and npm bridge have independent versions. Signing in does not upgrade any of them.

Run the sign-in command, then approve the displayed code on the Ephemeris page in your browser. Over SSH, use --no-browser and open the printed link yourself. Keep the terminal running while you approve.

ephemeris auth login
# For SSH or an agent: auth login --no-browser
ephemeris auth status --verify
ephemeris models list
ephemeris balance

The CLI saves a private credentials file. EPHEMERIS_API_KEY, when set, takes precedence over that file. Never paste passwords or keys into an agent conversation. auth status alone checks local configuration; --verify contacts the service. These checks do not submit forecasts.

auth logout removes the saved file; it does not revoke the key or clear an environment variable. Revoke keys on the dashboard’s API keys page. For CI, supply EPHEMERIS_API_KEY through your secret manager.

Create this small example in a new directory, or replace it with your real CSV. Select the time and value columns explicitly. CSV, TSV, JSON rows and JSONL are supported; Excel and Parquet are not.

# Synthetic example only. For real work, supply your own observations.
cat > sales.csv <<'CSV'
date,sales
2026-10-01,100
2026-10-02,102
2026-10-03,97
2026-10-04,106
2026-10-05,108
2026-10-06,109
2026-10-07,112
2026-10-08,107
CSV
ephemeris data inspect --input sales.csv \
  --time-column date --value-column sales --frequency D \
  --unit units --measurement period_total --timezone UTC \
  --target-description "Synthetic observed daily sales" \
  --output inspected.json

Read series[].report.ready_for_forecast in inspected.json. Exit code 0 means inspection finished, not that the data is ready. The report identifies duplicates, missing values, zeros, time coverage and frequency evidence. Nothing is silently sorted, filled or repaired.

The labels above describe this example only. For real data, establish the unit, target, timezone and whether values are period totals, period averages or point-in-time readings. Leave unknown information unknown. Recorded sales are not automatically underlying demand, and a blank cell is not zero.

ephemeris forecast run --input inspected.json \
  --horizon 3 --quantiles 0.1,0.5,0.9 \
  --dry-run --output prepared.json

This writes prepared.json, containing a validated request and separate local context. It needs no credentials and makes no network call. A horizon of 3 means three sampling steps: three days here because the declared grid is daily. Hourly data would mean three hours.

The default mode for an inspected snapshot is route, which lets the service select a model. To change it, add --mode ensemble, or --mode explicit --model NAME using a name from models list. Model-specific limits can be smaller than the API limits.

Quantiles 0.1,0.5,0.9 request a median and a nominal central 80% marginal interval. They do not establish calibrated coverage. Dry-run success validates the local request; it does not prove account balance, model availability or forecasting quality.

Check your balance and authorize the cost before running this step. The CLI saves a durable submission receipt before contacting the service.

# Paid operation: run only when you want to spend forecast credits.
ephemeris forecast run --input prepared.json --output forecast.json

forecast.json is an ephemeris.forecast v1 artifact with the submitted request, response, IDs, billing and local context. It includes the full submitted input history. The service may use a shorter context window. Credentials are excluded.

forecast.json.submission.json also contains input history and the retry key. Keep it for recovery, and store both files appropriately for your data. Output files are never overwritten: choose a new filename for another operation.

Billing fields ending in _mc are exact millicredit strings. 1,000 millicredits equals one credit; a recorded charge of "100" is 0.1 credits. A saved balance is the balance at that response, not a live account check.

ephemeris forecast describe --input forecast.json --output description.json
ephemeris forecast plot --input forecast.json --output forecast.png
ephemeris forecast plot --input forecast.json --history all --output forecast.svg

These commands read the artifact without another forecast or charge. PNG is convenient for sharing; SVG scales without losing detail. Plots show observed history, the median, a boundary between history and forecast, and labeled quantile bands. Without reliable dates, the axis uses sampling steps.

The description calculates statistics deterministically and identifies its baseline and sources. The sum of marginal medians is not the median of a total. Summing marginal quantiles does not produce a cumulative interval, and the highest median is not the distribution of the actual peak. This API does not expose sample paths; another paid run cannot supply that missing capability.

For multiple series or variates, select them explicitly using --series-index and --variate-index (zero-based). To correct labels, copy the artifact to a new file, update only caller-confirmed local context, preserve its request and response, then describe or plot again. Missing labels alone never require another forecast.

A timeout does not prove that inference failed. If the response is lost, use the receipt to recover the exact request and idempotency key. Do not create a new key just to retry.

# Only after an uncertain submission; retain the original receipt.
ephemeris forecast run --resume forecast.json.submission.json --dry-run
ephemeris forecast run --resume forecast.json.submission.json --output recovered.json

Resume uses the receipt’s saved service origin. Only use receipts you trust. Server retention limits apply: an expired key may cause a new execution and charge, so replay is not guaranteed indefinitely. A plotting or description error leaves the paid forecast intact; fix the local output problem and rerun only that command.

ephemeris --help
ephemeris forecast --help
ephemeris forecast run --help
ephemeris schema forecast
ephemeris forecast describe --help
ephemeris forecast plot --help

Help, schemas and version diagnostics work offline. Each command explains inputs, defaults, side effects, output meanings and recovery. Use live models list for account/deployment capabilities instead of guessing model names or limits.

Tell the agent to ask for missing units and business definitions, validate offline first, and obtain your authorization before paid inference. For browser sign-in, it should relay the approval link and code while the command waits; it should never request passwords or raw keys in chat.

Read the full machine-readable operating guide and generated reference. Release metadata identifies the guide’s version and content hashes.

• data inspect --help: supported files, explicit columns and time grids.
• forecast run --help: raw JSON/stdin, modes, covariates, receipts and limits.
• forecast describe --help and forecast plot --help: offline examples and interpretation.
• usage list --help: account usage history; it contacts the service.
• schema forecast --kind artifact: the offline saved-record schema.

Explore model capabilities · Understand forecast pricing · Integrate with the API or MCP