# Ephemeris CLI 0.5.1 — agent operating guide and complete command reference

Install: npm install --global ephemeris-cli@0.5.1 (Node.js 22+). This package version is independent of the hosted MCP version.

# Operating Ephemeris from an unfamiliar agent

The executable is the authoritative operating guide. No skill pack or repository access is required. Start with `ephemeris --help`, then `<command> --help`. Help, version and schemas work offline. `docs/cli-reference.md` is generated from the same command definitions and ships with the npm package.

## Discover before acting

```sh
ephemeris --help
ephemeris version --json
ephemeris forecast --help
ephemeris forecast run --help
ephemeris schema forecast
```

Record the installed version when reporting a problem. A null build commit means unknown; the CLI cannot infer the hosted MCP or bridge version. Use live `models list` to discover model names, limits, health and prices rather than relying on memorized names.

## Obtain access without handling user passwords

`ephemeris auth status` checks local configuration without networking; it does not validate a saved key. `ephemeris auth status --verify` contacts the account service without forecasting. An explicitly set `EPHEMERIS_API_KEY` takes precedence over the credentials file.

For an authorized interactive login, use `ephemeris auth login --no-browser` and relay its approval URL and code to the person. Keep the command waiting while they approve. Do not request passwords, authenticator codes or raw API keys in chat. Login has network access and saves a credential but submits no forecast. If no person is available to approve, explain that authentication remains incomplete. `auth logout` removes the local saved credential, not an environment variable or the server-side key; use the dashboard for revocation.

## Ask for context that cannot be determined from numbers

Obtain the intended target, unit, sampling frequency, horizon and meaning of each measurement where possible. Distinguish period totals, period averages and point-in-time measurements. Observed sales need not equal demand. A 24-step horizon only means 24 hours if the sampling interval is hourly. Preserve unknowns rather than inventing units, a timezone, future events or a business definition.

Numeric past covariates must align with history; future covariates must align with the horizon and have matching past channels. Distinguish known future inputs from scenario assumptions. Local narrative context does not affect model inference. Not supplied does not mean zero, unchanged or no events.

## Prepare, validate, submit and preserve

For files, use `data inspect --help` and explicitly select columns. Check `series[].report.ready_for_forecast`; exit 0 means inspection completed, not that data is suitable. Missing periods, duplicates and missing values require user-directed correction of the source. Do not silently repair, reorder or resample.

```sh
# sales.csv must contain real user-supplied date and sales columns.
ephemeris data inspect --input sales.csv --time-column date --value-column sales \
  --frequency D --unit units --measurement period_total --timezone UTC \
  --target-description 'Observed daily sales' --output inspected.json

# Offline validation: does not submit or charge.
ephemeris forecast run --input inspected.json --horizon 7 \
  --quantiles 0.1,0.5,0.9 --dry-run --output prepared.json

# Run only after a forecast submission is authorized. This can spend credits.
ephemeris forecast run --input prepared.json --output forecast.json

# Reuse the saved result without inference.
ephemeris forecast describe --input forecast.json --output description.json
ephemeris forecast plot --input forecast.json --output forecast.png
```

Use only caller-supplied units and semantics; these example labels are not defaults for arbitrary data. `forecast run --help` contains a complete synthetic input example when no real file is available. Avoid overwriting existing paths. Select series and variates explicitly when multiple outputs exist; indices are zero-based.

Artifacts and submission receipts contain full input history and local context. Save them privately. API keys are excluded. Description and plotting are separate, deterministic local operations, so a plotting failure does not require another paid forecast.

## Recover without paying twice

Before the paid POST, the CLI saves a private submission receipt containing the original request and idempotency key. After a timeout, the request may already have completed. Keep the receipt and use:

```sh
ephemeris forecast run --resume forecast.json.submission.json --output recovered.json
```

Use the actual receipt path from the failed operation. Do not construct a fresh request or key, edit the receipt, or promise indefinite replay: the server's retention period still applies. If the output file already exists, inspect it or choose a new path. A paid-response write failure attempts recovery on stdout and exits 8; preserve stdout. CLI errors are JSON Lines on stderr. Use the exit-code and recovery guidance in each command's help.

401/403: resolve credentials. 402: ask the user to fund the account; do not loop. 409/429: inspect the error and any retry delay. Network interruption: treat completion as unknown and preserve the receipt. Do not make a diagnostic paid forecast merely to check access.

## Interpret only supported quantities

Read deterministic `scope`, `result`, `basis`, `limitations`, `references` and `followups` before composing prose. References point into the saved artifact. Billing `_mc` values are millicredits: 100 mc is 0.1 credit, not 100 credits. Saved balances are not current account balances.

A q0.1–q0.9 band is a nominal central 80% marginal interval, not demonstrated calibrated coverage or accuracy. Do not sum marginal quantiles to produce a cumulative interval. Marginals do not determine path-dependent probabilities or the distribution of the actual peak. The highest median is only the highest marginal median. A sum of marginal medians for period totals is not the median of the cumulative total. Do not invent causes or trading/inventory instructions.

If only labels are missing, copy the artifact, edit caller-supplied local context metadata in the copy, preserve request/response, and rerun description/plotting offline. Unknown timezone or assumptions remain unknown. There is no dedicated metadata-edit command; no new forecast is needed for label changes.

## Evidence and limits

See `docs/usability-audit.md` for the release evaluation and its exact scope. Scripted CI scenarios are not model evaluations. Agent trials use a local fixture: they test discovery, correct tool use, data preservation and interpretation, not production forecast quality. Passing a finite suite does not establish universal reliability. New use cases need additional review, particularly unsupported calendars, model-specific constraints and decisions with real consequences.

The public API and CLI expose marginal quantiles only, with no supported sample-path request. Do not offer another paid run, model mode, or extra quantiles as a way to obtain cumulative intervals or peak/path probabilities. Those require a separately verified method and appropriate dependence information. The plotted boundary lies halfway between the last observed point (step 0) and first future point (step 1).


# Ephemeris CLI reference

Generated from command help. Do not edit manually.

```text
Ephemeris 0.5.1 — inspect, forecast, describe, plot

Usage: ephemeris <command> [options]

  version              Inspect the installed CLI version, build identity and supported local record schemas.
  data inspect         Inspect selected observed columns and freeze a reusable local data snapshot.
  forecast run         Submit a forecast and save a versioned artifact; this operation spends credits.
  forecast describe    Calculate deterministic interpretation of a saved forecast artifact, offline.
  forecast plot        Render PNG or SVG from saved history, median, and quantile bands, offline.
  models list          Discover live model capabilities, context/horizon limits, and prices.
  balance              Read available credits and active holds without running a forecast.
  usage list           Read one page of forecast request history and charges.
  auth login           Sign in from the terminal: approve a code in the browser and save an API key.
  auth logout          Delete the saved credentials file. Does not revoke the key.
  auth status          Check local credential configuration; optionally verify it with the API.
  schema forecast      Print the bundled public forecast request JSON Schema, offline.

Discover each operation with <command> --help. Start with data inspect --help.
Workflow: inspect -> forecast run -> forecast describe -> forecast plot.
Each operation is explicit; only forecast run submits paid inference.
Options can precede or follow commands. --version prints the version.
Compatibility: forecast --input ... aliases forecast run; results are now artifacts.

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## version

```text
Usage: ephemeris version [options]

Inspect the installed CLI version, build identity and supported local record schemas.

Runs offline without credentials, inference, charges or service checks. No required inputs. JSON is the default; --json is accepted explicitly. --output writes a new file and never overwrites; stdout is the default. ephemeris --version remains the short package version only.

Fields: component identifies this installed CLI; version comes from its package metadata; build_commit is the full source Git SHA stamped when a clean checkout was packed, or null when unavailable. artifact_schema_versions lists supported versions by record kind. A null commit is unknown, not evidence of an outdated install. Package, hosted MCP, bridge and artifact schema versions are independent. This command does not determine the deployed service version, latest npm version, model availability, account balance or forecast quality. Use MCP get_version for the hosted version and models list for live capabilities.

Examples below need no files or API key. Exit 0 means metadata was read; invalid options exit 2; output errors exit 8. A failure causes no network operation or paid forecast; correct the option or choose a new writable output path and rerun.

Options:
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
ephemeris version
ephemeris version --json
ephemeris version --output cli-version.json
ephemeris --version

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## data inspect

```text
Usage: ephemeris data inspect [options]

Inspect selected observed columns and freeze a reusable local data snapshot.

Supported: CSV/TSV with headers, JSON arrays of row objects, JSONL row objects. Select --value-column explicitly; add --time-column for time coverage and grid checks. Optional --series-column groups independent series without guessing a target. Decimal text is parsed in CSV/TSV; JSON values must be numbers. No Excel, Parquet, gzip, implicit grouping, repairs, sorting, deduplication, resampling, or interpolation.

Output ephemeris.data v1 includes selected numeric history, original timestamp strings, source SHA-256, metadata, per-series readiness and reports. Missing/non-numeric cells are represented as null with separate counts and one-based source data-row numbers. Reports include observed range, frequency evidence, missing periods, duplicates, missing values, invalid cells, and zeros. Exit 0 means inspection completed, NOT ready to forecast. Check series[].report.ready_for_forecast. Counts refer to the selected observed window; no data outside it is inferred.

Supported time grids: whole-second subdaily (H, 15min, 30s), D, W, and month-start MS. ISO dates or ISO datetimes only; offsets must be explicit for aware timestamps. Supply an IANA --timezone when known. Named-zone naive subdaily timestamps are ambiguous and not ready. Frequency inferred from a regular window is only a candidate; --frequency declares the intended grid. Without timestamps, missing periods/coverage remain unknown and forecasting requires declared frequency. Unsupported calendars remain unverified. A horizon counts grid steps, not calendar days.

Preserve units and target meaning explicitly: period_total, period_average, or point_in_time. Observed sales are not necessarily underlying demand; zeros do not prove stockouts or lost demand. The snapshot freezes selected history; source edits do not change it. Fix bad source data explicitly and inspect again. Runs locally. No credentials, provider calls, credits, or network access. Does not change the input. Output is JSON unless this command specifies an image; --output writes a new file only.

Options:
  --input, -i <value>
      Required file, or - for stdin. UTF-8; maximum 8 MiB.
  --format <value>
      csv|tsv|json|jsonl. Inferred from filename extension; required for stdin.
  --value-column <value>
      Required observed numeric target column; literal name.
  --time-column <value>
      Optional ISO timestamp column; omitted means unknown coverage.
  --series-column <value>
      Optional grouping column. Missing IDs reject; source order is preserved within each group.
  --frequency <value>
      Declared intended sampling grid, e.g. H, 15min, D, W, MS. Default: evidence-based candidate, if unambiguous.
  --unit <value>
      Caller-declared unit, e.g. AUD, units, kWh; default unknown. No conversion.
  --timezone <value>
      Caller-declared IANA zone, e.g. Australia/Brisbane; default unknown. Does not silently localize ambiguous instants.
  --target-description <value>
      Caller-supplied target meaning, e.g. observed daily sales; default unknown.
  --measurement <value>
      period_total|period_average|point_in_time; default unknown.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
printf 'date,sales\n2026-01-01,10\n2026-01-02,12\n' > example-sales.csv
ephemeris data inspect --input example-sales.csv --time-column date --value-column sales --frequency D --unit units --measurement period_total --target-description "Synthetic observed sales" --output inspected.json
ephemeris forecast run --input inspected.json --horizon 7 --quantiles 0.1,0.5,0.9 --dry-run
# For real work, use actual supplied observations, units, and target meaning.

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## forecast run

```text
Usage: ephemeris forecast run [options]

Submit a forecast and save a versioned artifact; this operation spends credits.

Input: an ephemeris.data v1 snapshot, an ephemeris.request v1 prepared request, or a public API request such as:
{"mode":"route","series":[{"values":[10,12,11],"freq":"D"}],"horizon":2,"quantiles":[0.1,0.5,0.9]}
This differs from raw Paracast. For raw CSV/TSV/JSON rows, first use data inspect. For multi-series snapshots choose --series ID. Snapshot data must be complete and regular; no silent repair.

Modes: route selects automatically; ensemble blends compatible models; explicit requires model from models list. Raw/prepared JSON requires mode; snapshots default route. Explicit flags override input fields; model does not implicitly change mode. API defaults horizon=64 and context_len=256; use explicit values when required. Limits: 64 series, 256 variates, horizon 1–4096, context_len 1–16384. Each history is oldest first. Frequency belongs to each series; horizon counts sampling steps. Quantiles [0.1,0.5,0.9] give marginal median and a central nominal 80% interval, NOT proven calibrated coverage. Total variates × horizon × quantile count must not exceed 120000; omitted quantiles count as 21 for this limit. Model-specific limits may be smaller. This CLI/public API exposes marginal quantiles, not joint trajectories or sample paths. No supported flag or mode requests them; do not offer a paid rerun as a way to obtain cumulative intervals or peak/path probabilities.

Optional local --context JSON is separate from the API request:
{"series":[{"unit":"units","measurement":"period_total","timezone":"UTC","target_description":"Synthetic observed sales","timestamps":["2026-01-01","2026-01-02","2026-01-03"]}]}
context.series aligns with request.series. Allowed per-series fields: series_id, unit, measurement, timezone, target_description, timestamps, future_timestamps, future_covariate_roles, source_available_at, recorded_as_of. Missing context stays null. Timestamps must match history length and a supported regular grid. Explicit future_timestamps must continue it for horizon steps. Named-zone calendar projection may fall back to steps unless explicit future timestamps are provided. Metadata applies to all variates in its series. Future roles map channel names to known_future|scenario_assumption|unspecified. Context and assertions are retained locally, never sent as model inputs. Narrative scenario assumptions do not affect inference. No future inputs or an empty assumptions list means not supplied; it does NOT mean the model assumes zero events, no promotions, no constraints, or unchanged conditions.

API series[].covariates.past numeric channels align with full history; future channels match horizon and need matching past names. Multivariate values are equal-length variate arrays. Only submitted numeric inputs affect the forecast; known future inputs and scenario assumptions must not be conflated. Use schema forecast for the wire contract. Raw requests reject unknown fields; put local context in --context.

--dry-run is fully offline, needs no key, costs nothing, and outputs a reusable ephemeris.request envelope (request plus local context). Submission returns an ephemeris.forecast v1 artifact, preserving request, full submitted history, response, context, timestamps, IDs, retry key, and billing. Billing is at response.meta.billing: settled_mc is charged millicredits; balance_mc is the remaining balance at that response. All _mc fields are exact integer strings: 1000 millicredits = 1 credit, so settled_mc="100" means 100 millicredits (0.1 credits), NOT 100 credits. Preserve these units and strings; missing billing is unknown. IDs are at response.meta.gateway_request_id, response.meta.request_id, and transport.request_id when supplied. transport.credentials_redacted=false means no credential-like response content needed redaction, not that credentials were included. Credentials are excluded. No describe or plot side effects occur. API results may include null quantiles; they remain missing. Service/model context caps can shorten the history actually used.

Idempotency-Key is printed BEFORE submission. A private, versioned ephemeris.submission v1 receipt is also synced to disk BEFORE the request. With --output forecast.json it defaults to forecast.json.submission.json; with stdout it uses .ephemeris/submissions/<uuid>.json in the current directory. --receipt selects another NEW path. Receipts contain the full prepared request/history/context, service origin, key, and request hash, never credentials. They remain after success or failure and do not prove completion. Existing receipts are never overwritten; a receipt write failure prevents submission. Archive or delete them explicitly when no longer needed.

Recover with forecast run --resume RECEIPT --output NEW_FILE. Resume reuses the exact stored request, key, context, and origin, ignoring EPHEMERIS_BASE_URL. It rejects input/model/horizon/quantile/context/key/base-url/receipt overrides; --timeout, --output, and --dry-run are allowed. --resume --dry-run validates offline and prints the prepared envelope. Only resume receipts you trust; their hashes are integrity checks, not signatures. Server retention rules apply: an expired key may result in a new charge; do not assume replay is retained indefinitely. Reuse it with the identical effective request after a timeout/interruption; a fresh key represents a new paid forecast. There are no automatic retries. Reserve the output path before submission. If writing a paid artifact fails, the CLI attempts recovery to stdout and exits 8. Save that JSON or retry with the same key (server retention rules apply). Later description/plot failures never rerun inference.

Options:
  --input, -i <value>
      Required file, or - for stdin. UTF-8; maximum 8 MiB.
  --base-url <value>
      HTTPS service origin; default EPHEMERIS_BASE_URL or https://ephemeris.cascade.industries. HTTP allowed on loopback only.
  --timeout <value>
      HTTP deadline in seconds, 1–3600; default 300. No automatic retries.
  --resume <value>
      Recover from a saved submission receipt. Reuses origin, request, and key; mutually exclusive with --input and request overrides.
  --receipt <value>
      New private submission receipt path; default OUTPUT.submission.json or .ephemeris/submissions/<uuid>.json. No receipt is written by --dry-run.
  --context <value>
      Optional local context JSON file or -. Not accepted with frozen snapshots/prepared requests. Only one input may be stdin.
  --series <value>
      Exact series ID from a multi-series inspected snapshot.
  --mode <value>
      route|ensemble|explicit; overrides input mode.
  --model <value>
      Live model name for explicit mode; discover with models list.
  --horizon <value>
      Future sampling steps, integer 1–4096; overrides input. API default 64.
  --quantiles <value>
      Comma-separated unique levels in (0,1), maximum 21, e.g. 0.1,0.5,0.9. Overrides input; omit to retain API/input defaults.
  --context-len <value>
      Most recent points per variate, 1–16384. Overrides input; API default 256.
  --dry-run
      Validate offline and print prepared request/context. No network or charge.
  --idempotency-key <value>
      8–128 letters/digits/dot/underscore/colon/hyphen. Default new UUID; retain it for identical retries.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
# Complete synthetic input; replace with actual supplied observations for real work.
cat > example-request.json <<'JSON'
{"mode":"route","series":[{"values":[10,12,11],"freq":"D"}],"horizon":2,"quantiles":[0.1,0.5,0.9]}
JSON
cat > example-context.json <<'JSON'
{"series":[{"unit":"units","measurement":"period_total","timezone":"UTC","target_description":"Synthetic observed sales","timestamps":["2026-01-01","2026-01-02","2026-01-03"]}]}
JSON
# Offline validation; no credentials or charge:
ephemeris forecast run --input example-request.json --context example-context.json --dry-run --output prepared.json
# Paid submission: requires EPHEMERIS_API_KEY. Receipt is saved before network access.
ephemeris forecast run --input prepared.json --output forecast.json
# Only after an uncertain result, recover to a NEW file (do not start a fresh request):
# ephemeris forecast run --resume forecast.json.submission.json --output recovered.json
# Other modes: add --mode ensemble, or --mode explicit --model NAME from models list.
# Stdin: cat example-request.json | ephemeris forecast run --input - --dry-run

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## forecast describe

```text
Usage: ephemeris forecast describe [options]

Calculate deterministic interpretation of a saved forecast artifact, offline.

Requires an ephemeris.forecast v1 artifact saved by forecast run. Select series/variate explicitly when there are multiple. Missing or corrected labels never require paid inference: copy the artifact to a NEW file, edit only its local context.series metadata using caller-supplied facts, leave request/response unchanged, then rerun describe/plot offline. Timestamps must pass the existing grid checks. No dedicated metadata-edit command exists. Returns a Gnomon-aligned overview: scope, result, basis, limitations, references, followups. JSON pointers refer to the INPUT artifact. This is not a Gnomon import or ledger record.

Shows observed count/mean/median/min/max/latest; final forecast median; change against the LAST OBSERVED value; arithmetic mean of per-step medians; and maximum marginal median with tied sampling steps. Percentage change uses 100*(final median-last)/abs(last); zero baseline gives null. A sum of medians is calculated only for caller-declared period_total and is NOT a median or interval of the cumulative total. Missing medians remain missing; no interpolation. Incomplete horizon-wide statistics and non-finite arithmetic return null. Missing units, timezone, and measurement remain unknown. result.billing labels saved millicredit amounts and exact decimal credit conversions; missing values remain null. This is not a current balance check.

Marginal quantiles do not establish calibrated coverage, path probabilities, cumulative intervals, actual peak distributions, causal explanations, trading actions, or inventory actions. Joint trajectories or a justified dependence model would be needed for cumulative/peak/path uncertainty. This CLI/public API has no supported way to request sample paths: do not promise that another paid forecast, another mode, or additional quantiles supplies them. Record the unsupported calculation and discuss a separately verified method before proposing any inference. Future-channel labels are caller assertions. Absent future inputs mean not supplied, not assumed zero or no events. A forecast jump or narrow/constant band does not by itself establish poor fit or quality; observed outcomes and evaluation are needed. This command makes no inference/LLM call, does not score outcomes, and does not schedule reviews. Runs locally. No credentials, provider calls, credits, or network access. Does not change the input. Output is JSON unless this command specifies an image; --output writes a new file only.

Options:
  --input, -i <value>
      Required file, or - for stdin. UTF-8; maximum 8 MiB.
  --series-index <value>
      Zero-based artifact series index. Required for multiple series; otherwise 0.
  --variate-index <value>
      Zero-based variate index. Required for multiple variates; otherwise 0. Series metadata applies to the selected variate.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
# Synthetic saved result for this offline example; not live predictions.
cat > example-forecast.json <<'JSON'
{"kind":"ephemeris.forecast","schema_version":"1","artifact_id":"00000000-0000-4000-8000-000000000001","created_at":"2026-01-04T00:00:00Z","request":{"mode":"route","series":[{"values":[10,12,11],"freq":"D"}],"horizon":2,"quantiles":[0.1,0.5,0.9]},"request_sha256":"8737423c8f6d653c73037497414069f2c4bf07bcf2d6ffcb7c98dfe6190ca1df","response":{"forecasts":[{"quantiles":{"0.1":[9,10],"0.5":[12,13],"0.9":[15,16]}}]},"context":{"series":[{"unit":"units","timezone":"UTC","target_description":"Synthetic observed sales","measurement":"period_total","series_id":null,"timestamps":["2026-01-01","2026-01-02","2026-01-03"],"future_axis":{"kind":"timestamps","values":["2026-01-04","2026-01-05"],"reason":"Projected from the recorded regular grid; future observations have not occurred."},"frequency_evidence":{"supplied_frequency":"D","candidate_frequency":"D","effective_frequency":"D","basis":"caller_declared_grid","invalid_timestamps":0,"duplicate_timestamps":0,"out_of_order_pairs":0,"missing_periods":0,"off_grid_intervals":0,"coverage":{"start":"2026-01-01","end":"2026-01-03"},"regular":true,"reason":null},"source_available_at":null,"recorded_as_of":null,"future_covariate_roles":{}}],"scenario_assumptions":[],"snapshot_id":null,"source":null},"transport":{},"disclosure":{"input_history_included":true,"context_sent_to_api":false,"credentials_included":false,"provider_input_note":"All submitted history is saved. The service may truncate it using context_len and model context limits."},"interoperability":{"gnomon_import":"not_implemented","recorded_in_ledger":false,"identity_basis":"local artifact UUID and request SHA-256; hashes are not authenticity signatures"}}
JSON
ephemeris forecast describe --input example-forecast.json --output description.json
# For a real saved artifact: ephemeris forecast describe --input forecast.json
# Multiple results: add --series-index 0 --variate-index 0 (zero-based).

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## forecast plot

```text
Usage: ephemeris forecast plot [options]

Render PNG or SVG from saved history, median, and quantile bands, offline.

Requires an ephemeris.forecast v1 artifact with a returned 0.5 quantile. Select series/variate explicitly for multiple results. Choose --output forecast.png for a shareable image, or forecast.svg for scalable output. --format png|svg explicitly selects format; otherwise the filename extension selects it, with SVG as the default for stdout or extensionless files. Conflicting/unsupported extensions reject. PNG stdout is binary and must be piped; it is not written to an interactive terminal. PNG uses a packaged renderer and bundled font, offline. Missing/corrected labels do NOT require a new paid forecast: copy the artifact to a NEW file, edit only its local context.series metadata with caller-supplied facts, keep request/response unchanged, and rerun plot offline. Timestamps must pass the grid checks. No dedicated metadata-edit command exists. No plotting application, browser, or Python installation is required.

Grey is observed history. The default view shows the most recent max(24, 2*horizon) observations, capped by available history; --history N changes that count, --history all shows everything. The chart labels the shown/total counts; the full history is always retained in the artifact. View changes do not change inference or resample observations. Blue is the marginal median; the dashed line marks the forecast boundary halfway between the last observed point (step 0) and first future point (step 1); it is not an observation or a forecast value. Default bands pair available complementary levels, e.g. q0.1–q0.9, and label nominal mass, not calibrated coverage. Use --lower and --upper together to select one existing band. Missing values break lines; missing/crossed interval points are omitted and counted. Median is never inferred from other quantiles. Available reliable timestamps are used; otherwise the axis uses sampling steps relative to the last observation (0). Named-zone calendar projection across DST can require explicit future_timestamps; no dates are fabricated.

Plots do not show cumulative uncertainty, path probabilities, peak distributions, or business recommendations. Unit/measurement/timezone are shown as supplied or unknown. Plot failure leaves the saved forecast intact; fix arguments or choose a new output path and rerun locally. Runs locally. No credentials, provider calls, credits, or network access. Does not change the input. Output is JSON unless this command specifies an image; --output writes a new file only.

Options:
  --input, -i <value>
      Required file, or - for stdin. UTF-8; maximum 8 MiB.
  --series-index <value>
      Zero-based artifact series index. Required for multiple series; otherwise 0.
  --variate-index <value>
      Zero-based variate index. Required for multiple variates; otherwise 0. Series metadata applies to the selected variate.
  --format <value>
      png|svg. Default from --output extension, otherwise svg. PNG stdout is binary; filename must match format.
  --history <value>
      Number of recent observations to display, 1–100000, or all. Default min(available, max(24, 2*horizon)); full history stays saved.
  --lower <value>
      Lower quantile already in saved result, e.g. 0.1. Requires --upper.
  --upper <value>
      Upper quantile already in saved result, e.g. 0.9. Requires --lower.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
# Synthetic saved result for this offline example; not live predictions.
cat > example-forecast.json <<'JSON'
{"kind":"ephemeris.forecast","schema_version":"1","artifact_id":"00000000-0000-4000-8000-000000000001","created_at":"2026-01-04T00:00:00Z","request":{"mode":"route","series":[{"values":[10,12,11],"freq":"D"}],"horizon":2,"quantiles":[0.1,0.5,0.9]},"request_sha256":"8737423c8f6d653c73037497414069f2c4bf07bcf2d6ffcb7c98dfe6190ca1df","response":{"forecasts":[{"quantiles":{"0.1":[9,10],"0.5":[12,13],"0.9":[15,16]}}]},"context":{"series":[{"unit":"units","timezone":"UTC","target_description":"Synthetic observed sales","measurement":"period_total","series_id":null,"timestamps":["2026-01-01","2026-01-02","2026-01-03"],"future_axis":{"kind":"timestamps","values":["2026-01-04","2026-01-05"],"reason":"Projected from the recorded regular grid; future observations have not occurred."},"frequency_evidence":{"supplied_frequency":"D","candidate_frequency":"D","effective_frequency":"D","basis":"caller_declared_grid","invalid_timestamps":0,"duplicate_timestamps":0,"out_of_order_pairs":0,"missing_periods":0,"off_grid_intervals":0,"coverage":{"start":"2026-01-01","end":"2026-01-03"},"regular":true,"reason":null},"source_available_at":null,"recorded_as_of":null,"future_covariate_roles":{}}],"scenario_assumptions":[],"snapshot_id":null,"source":null},"transport":{},"disclosure":{"input_history_included":true,"context_sent_to_api":false,"credentials_included":false,"provider_input_note":"All submitted history is saved. The service may truncate it using context_len and model context limits."},"interoperability":{"gnomon_import":"not_implemented","recorded_in_ledger":false,"identity_basis":"local artifact UUID and request SHA-256; hashes are not authenticity signatures"}}
JSON
ephemeris forecast plot --input example-forecast.json --output forecast.png
ephemeris forecast plot --input example-forecast.json --output forecast.svg --history all
# For a real saved artifact: ephemeris forecast plot --input forecast.json --history 48 --lower 0.1 --upper 0.9 --output interval.png

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## models list

```text
Usage: ephemeris models list [options]

Discover live model capabilities, context/horizon limits, and prices.

Authenticated GET /api/v1/models. No forecast or forecast charge. Use before explicit model selection; names/capabilities are not hard-coded. Returns the unmodified catalog JSON, except credential-like fields are redacted. Catalog price_per_kslot_mc means millicredits per 1000 series-slots; billing_context_cap is the maximum billable context. 1000 millicredits = 1 credit. Treat absent capability/price fields as unknown. This does not establish model quality.

Options:
  --base-url <value>
      HTTPS service origin; default EPHEMERIS_BASE_URL or https://ephemeris.cascade.industries. HTTP allowed on loopback only.
  --timeout <value>
      HTTP deadline in seconds, 1–3600; default 300. No automatic retries.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
ephemeris models list --json

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## balance

```text
Usage: ephemeris balance [options]

Read available credits and active holds without running a forecast.

Authenticated GET /api/v1/balance. No forecast or forecast charge. Fields ending in _mc are millicredit strings; 1000 millicredits = 1 credit ("100" mc is 0.1 credits, not 100 credits). Preserve them to avoid integer precision loss. No billing state is changed.

Options:
  --base-url <value>
      HTTPS service origin; default EPHEMERIS_BASE_URL or https://ephemeris.cascade.industries. HTTP allowed on loopback only.
  --timeout <value>
      HTTP deadline in seconds, 1–3600; default 300. No automatic retries.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
ephemeris balance --json

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## usage list

```text
Usage: ephemeris usage list [options]

Read one page of forecast request history and charges.

Authenticated GET /api/v1/usage. No forecast or forecast charge. Use pagination.next_offset for the next page. Rows are in data[]. requestId identifies the gateway request; paracastRequestId identifies the provider request when supplied. estimatedMc and settledMc are exact millicredit strings, not credits; status is the recorded HTTP status when supplied. Preserve IDs and strings; 1000 millicredits = 1 credit. This does not ingest actuals or score forecasts.

Options:
  --base-url <value>
      HTTPS service origin; default EPHEMERIS_BASE_URL or https://ephemeris.cascade.industries. HTTP allowed on loopback only.
  --timeout <value>
      HTTP deadline in seconds, 1–3600; default 300. No automatic retries.
  --limit <value>
      Rows per page, integer 1–200; default 50.
  --offset <value>
      Rows to skip, integer >=0; default 0.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
ephemeris usage list --limit 20 --offset 0 --json

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## auth login

```text
Usage: ephemeris auth login [options]

Sign in from the terminal: approve a code in the browser and save an API key.

Starts a sign-in (POST /api/v1/device/code; OAuth 2.0 device flow, RFC 8628), opens the approval page in your browser and waits. On the page, sign in or sign up, check it shows the same code, and approve. The new key is saved to the credentials file, readable by you only: ~/.config/ephemeris/credentials ($XDG_CONFIG_HOME, %APPDATA% on Windows; EPHEMERIS_CREDENTIALS_FILE overrides). Other Ephemeris tools on this machine (ephemeris-mcp, savetokens) read the same file. EPHEMERIS_API_KEY, when set, still wins over the file. The key is never printed: stdout reports where it was saved; stderr carries one JSON line with the code and link (event device_login) for an agent to show the person. --no-browser prints the link without opening it (SSH, CI). Codes expire after 10 minutes. The key appears on the dashboard API keys page, where it can be revoked. No forecast or charge.

Options:
  --base-url <value>
      HTTPS service origin; default EPHEMERIS_BASE_URL or https://ephemeris.cascade.industries. HTTP allowed on loopback only.
  --timeout <value>
      HTTP deadline in seconds, 1–3600; default 300. No automatic retries.
  --no-browser
      Do not open a browser; use the link on stderr.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
ephemeris auth login
ephemeris auth login --no-browser
ephemeris auth status --verify

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## auth logout

```text
Usage: ephemeris auth logout [options]

Delete the saved credentials file. Does not revoke the key.

Removes the credentials file written by auth login. EPHEMERIS_API_KEY in the environment is not affected. The key stays valid until you revoke it on the dashboard API keys page. Offline.

Options:
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
ephemeris auth logout

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## auth status

```text
Usage: ephemeris auth status [options]

Check local credential configuration; optionally verify it with the API.

Reports where the key comes from: EPHEMERIS_API_KEY (environment, which wins) or credentials_file (written by ephemeris auth login), or null when there is none. No credential arguments. Create a key with ephemeris auth login, or in the dashboard at https://ephemeris.cascade.industries/dashboard/api-keys. Default reports configured, not verified. --verify performs GET /api/v1/balance; no forecast charge. Keys are never printed. On 401/403 replace/check the key and permissions.

Options:
  --base-url <value>
      HTTPS service origin; default EPHEMERIS_BASE_URL or https://ephemeris.cascade.industries. HTTP allowed on loopback only.
  --timeout <value>
      HTTP deadline in seconds, 1–3600; default 300. No automatic retries.
  --verify
      Verify key with balance endpoint; default local configuration check only.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
ephemeris auth status --verify

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```

## schema forecast

```text
Usage: ephemeris schema forecast [options]

Print the bundled public forecast request JSON Schema, offline.

Default --kind request prints the public API request contract. --kind artifact, prepared, data, or submission prints the corresponding local version 1 schema. Each output is standalone JSON Schema with local $defs references. API validation remains authoritative. Local semantic checks additionally enforce shape, covariate alignment, and explicit-mode model selection. Artifacts preserve request/response/context, IDs and billing; prepared records separate the wire request from local context; data records freeze selected observations and diagnostics; submission receipts preserve the exact request and retry key before network access. See forecast run --help for usage. Runs locally. No credentials, provider calls, credits, or network access. Does not change the input. Output is JSON unless this command specifies an image; --output writes a new file only.

Options:
  --kind <value>
      request|artifact|prepared|data|submission. Default request (public wire format); other kinds are local version 1 contracts.
  --json
      JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.
  --output, -o <value>
      Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.
  --help, -h
      Complete offline help for this command.

Examples:
ephemeris schema forecast --output forecast-schema.json
ephemeris schema forecast --kind artifact
ephemeris schema forecast --kind data

Authentication for remote operations: EPHEMERIS_API_KEY, else the file saved by ephemeris auth login.
Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
7 API/protocol error; 8 file I/O; 130 interrupted.
401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
Offline commands need no credentials and do not contact the service.
Missing units, target/business definitions, or future assumptions: ask the user;
preserve unknowns rather than filling them with plausible guesses. No operation
establishes forecast accuracy, calibrated coverage, or permission for business actions.
Missing future inputs mean not supplied, not assumed zero/no events.
A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
Missing labels alone never require new paid inference. Copy a saved artifact to a
NEW file, correct only caller-supplied local context metadata, keep request/response
unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.
```