ephemeris-cli 0.0.0-stage → 0.4.0

package/docs/cli-reference.md

@@ -0,0 +1,594 @@
+# Ephemeris CLI reference
+
+Generated from command help. Do not edit manually.
+
+```text
+Ephemeris 0.4.0 — 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 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 environment only.
+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 environment only.
+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 environment only.
+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.
+
+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 environment only.
+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. 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 environment only.
+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. 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 environment only.
+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 environment only.
+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 environment only.
+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 environment only.
+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.
+
+Set EPHEMERIS_API_KEY from your environment/secret manager. No credential arguments or stored credential files. Create a key 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 environment only.
+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 environment only.
+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.
+```