CLI reference

The heimdall binary is @heimdallm/cli's command line client for the same public API these docs cover: catalogue reads, account and key management, provider operations and one-shot inference calls. Commands that support --json are marked below. Their stdout contains a JSON result instead of a table; errors have a nonzero exit status. Login uses an interactive authorization flow and does not support --json. Media commands can report waiting progress on stderr.

The staging distribution is @staging-heimdall/cli, installed with npm install -g @staging-heimdall/cli. Use heimdall-staging for the commands below and HEIMDALL_STAGING_ in place of the HEIMDALL_ environment prefix. Its credentials, settings and history are independent of heimdall.

Updates are explicit: heimdall-staging version check reports the newest eligible version, how many eligible releases the installation is behind, and the exact install command. Staging recommendations wait 24 hours after publication. Automatic notices appear at most once daily in an interactive terminal and stay silent in JSON output, scripts and CI. Set HEIMDALL_STAGING_NO_UPDATE_NOTIFIER=1 to disable automatic checks. The delay applies to recommendations, not manual installation or dependency ages.

A command that changes state on the server asks for confirmation on a terminal, and with no terminal attached refuses to run unless --yes is passed. Inference requests such as chat or image are billed per use and run without a prompt.

Most commands share three flags: --base-url (or HEIMDALL_BASE_URL) is the public API base URL including /api/v1; --api-key (or HEIMDALL_API_KEY) is the bearer key for an account route; --host (or HEIMDALL_HOST) selects a stored credential profile instead of a literal key, from heimdall login. Each is listed again per command below because its requiredness differs: a public catalogue read takes only --base-url, an account command needs a key from one of the three, and login/logout/auth switch take a host with no API base URL at all.

The installed heimdall-staging binary defaults to the staging API and web origins, so no URL exports are needed. Pass --api (an alias of --base-url) for another API; --web-url overrides the browser login origin. The source heimdall binary still requires an API URL.

Commands are grouped by topic below the index: auth, deposits, generations, keys, meshes, models, providers, version, videos each hold more than one subcommand, and every other command stands alone.

Commands#

heimdall activity#

The account's usage for one UTC day, over GET /activity, in the row shape OpenRouter's /activity publishes. Without --date, the day the account's daily spend window is currently in. --group-by (default model) sets what a row is: model aggregates across every endpoint and key that served it, endpoint splits a model's rows by which endpoint served them, and key splits by which API key spent them and adds api_key_hash to every row. Grouping only ever splits a day into more rows: the sum of any field over a grouped day's rows equals the same model's row at the default grouping. Money fields (usage, spend, byok_usage_inference) are decimal strings, printed exactly as the wire sends them.

Supports --json for machine-readable output.

Aliased as usage.

heimdall auth status#

The credential backend and the host a command uses by default. Never prints a key, not even a prefix of one.

Supports --json for machine-readable output.

heimdall auth switch#

Make a host with a stored API key the active profile.

heimdall chat#

A chat completion over POST /chat/completions, streamed as it arrives. Runs one-shot when a PROMPT argument is given or stdin is piped, and opens an interactive turn loop only when neither is present. Tokens print to stdout as they stream; under --json, stdout carries nothing until the stream ends, then one response document with usage and the generation id, in the same shape as a non-streamed chat completion. Ctrl-C during a stream aborts the request, leaves whatever text already printed in place, and exits 130; the call log still records the generation id when one arrived before the interrupt.

Supports --json for machine-readable output.

heimdall complete#

The legacy text-completions shape over POST /completions: a prompt in, text out, no conversation structure. Give a PROMPT, pipe standard input, or pass a complete --request file.

Supports --json for machine-readable output.

heimdall completion#

Print a shell completion script for bash, zsh or fish, generated from the loaded command tree so it cannot drift from the commands and flags the CLI accepts. Topic names, the commands within a topic, flags and the fixed values of a flag complete in a fresh shell. Load the script from the shell startup file: source <(heimdall completion bash) for bash, source <(heimdall completion zsh) for zsh after compinit, or heimdall completion fish > ~/.config/fish/completions/heimdall.fish for fish. A zsh script saved as a function file named after the command, on the function path, loads without sourcing.

heimdall credits#

Credited and debited totals for the account the presented key belongs to, over GET /credits. The balance is the difference between the two; both figures are exact.

Supports --json for machine-readable output.

heimdall decisions#

Answer a typed question about a state. A plain question asks yes/no (noul); --choice ranks named options and --level scores ordered levels. Use --request for multiple questions or structured state.

Supports --json for machine-readable output.

heimdall deposits create#

Settle a signed-authorization (x402) deposit, over POST /deposits/x402. Without --payment-signature the answer is the 402 PaymentRequired terms the protocol itself defines, not a settled deposit: sign the printed offer with the paying wallet and resubmit the same --amount and --network carrying that signature in --payment-signature to settle it. The credit posts at the chain's confirmation depth, not with this command's own response.

Supports --json for machine-readable output.

heimdall deposits stripe#

The card deposit rail terms, over GET /deposits/stripe. No key is required. Nothing here takes money: the Checkout Session that does is created on the browser session plane.

Supports --json for machine-readable output.

heimdall deposits x402#

The signed-authorization (x402) deposit rail terms, over GET /deposits/x402. No key is required. { "enabled": false } alone means the rail is not configured.

Supports --json for machine-readable output.

heimdall embed#

Text embeddings over POST /embeddings. Give an INPUT, pipe standard input, or pass a complete --request file for batches and provider settings. Vectors never print to a table; use --json to read them.

Supports --json for machine-readable output.

heimdall generations show#

A recorded generation or a funded request awaiting a final record, over GET /generation, scoped to the presented key's own account. record_state is recorded or unrecorded: an unrecorded request leaves final tokens, timings and cost null. Absent measurements print null, never a measured zero. Consults the local call log first: a row logged under this id by chat, complete, embed, image or transcribe prints from there with no request sent, and the gateway is asked only when the log holds no such row or --remote is given.

Supports --json for machine-readable output.

heimdall image#

An image generation over POST /images. Give a PROMPT or a complete --request file. The reply is asked for whole: rendered images are base64-decoded and written to --out (with numbered names for additional images), or the sole image to stdout when --out is -. Under --json, the printed response document replaces each image's base64 payload with its decoded byte count.

Supports --json for machine-readable output.

heimdall key#

What the presented key is, what it has spent and what its ceiling leaves, over GET /key. A key with no ceiling reports null for every ceiling field rather than a zero.

Supports --json for machine-readable output.

heimdall keys create#

A new key in the presented management key's own workspace, over POST /keys. The plaintext prints exactly once, in this command’s own response, and is never written to the local call log or anywhere else this process keeps state — read it now or lose it, the same as the API itself never stores it.

Supports --json for machine-readable output.

heimdall keys list#

Every key in the presented management key's own workspace, newest first, over GET /keys. Served only to a management key; a spending key gets the same refusal every other management route answers it with. Never carries key material — only the plaintext a create or rotate just minted does, and only in that one response.

Supports --json for machine-readable output.

heimdall keys revoke#

Disables a key in the presented management key’s own workspace, over DELETE /keys/:hash. The key’s next authenticated request fails from that point on. Idempotent — revoking an already-disabled key succeeds without changing anything. Prompts for confirmation on a terminal; pass --yes to run it without one.

Supports --json for machine-readable output.

heimdall keys rotate#

Replaces a key’s material while keeping its name and limit. No single gateway route rotates a key, so this composes three calls under one confirmation: GET /keys/:hash to read the existing name, limit and limit_reset, POST /keys with the same three to mint a replacement, then DELETE /keys/:hash on the original. The new plaintext prints exactly once, the same as keys create. If the DELETE step fails after the POST succeeds, both keys are left live and the command says so — it never guesses which one to keep. Prompts for confirmation on a terminal; pass --yes to run it without one.

Supports --json for machine-readable output.

heimdall log#

The local call log that chat, complete and embed each append a row to, newest first. Stored under $XDG_DATA_HOME/heimdall (default ~/.local/share/heimdall). Holds no prompt or completion text unless the call that produced a row was run with --log-text.

Supports --json for machine-readable output.

heimdall login#

Store an API key for a host. The default flow opens the browser on the marketplace's authorization page. Paste its one-time code here, or finish in the browser on the same computer. It uses --web-url (or HEIMDALL_WEB_URL) for its web origin. Staging has a built-in default. --with-token reads the key from stdin instead, for CI and containers. Use --manual when the browser runs on another computer.

heimdall logout#

Remove a host's stored API key and clear it as the active profile.

heimdall mcp#

Serve the Heimdallm Model Context Protocol server on stdin and stdout, for an agent to launch: model discovery, chat and media generation, files, batches, account usage, key administration and provider operations as tools, each an ordinary request to the API billed as one. The key is --api-key, then the stored profile for the host; without one the catalogue tools still answer and the account tools answer 401. Paths the tools read and write resolve against the working directory. Stdout carries nothing but the protocol.

heimdall meshes cancel-repair#

Stop optional mesh repair, preserving generation and the last validated repair. Poll meshes show until repair is terminal.

Supports --json for machine-readable output.

heimdall meshes create#

Generate a mesh from a prompt. Use --input for a full JSON request with views, texture and repair options. Use --out to wait and save the GLB, or --wait to return the completed job.

Supports --json for machine-readable output.

heimdall meshes download#

Download a mesh GLB to a new file, resuming an interrupted transfer. Index 0 is the original; index 1 is the validated repair when available. The destination must not exist.

Supports --json for machine-readable output.

heimdall meshes models#

List mesh generation models, or available vision repair models and machine pricing.

Supports --json for machine-readable output.

heimdall meshes show#

Read a mesh job, geometry, repair progress and exact repair charges. Use --wait to wait for completion or --out to wait and save the selected GLB to a new file.

Supports --json for machine-readable output.

heimdall models endpoints#

A model and every live endpoint serving it, over GET /models/{author}/{slug}/endpoints. A measured figure whose window holds fewer samples than its own gate is null, printed as a dash in the table and as null in --json — never as a measured zero. Each price is what a request is charged; pricing.discount is the fraction already taken off it, and is 0 on an endpoint charging its published price.

Supports --json for machine-readable output.

heimdall models list#

List every served model. --family, --limit and --offset are the query parameters the public /models route serves; every other flag filters the returned page locally, after it is fetched. --provider and --zdr read a live endpoint, which the list route does not carry, so each fetches one candidate's endpoints route after the other filters have narrowed the page.

Supports --json for machine-readable output.

heimdall models show#

Show one served model, the same object GET /models lists.

Supports --json for machine-readable output.

heimdall providers earnings#

The presented key's provider's earnings for one month: totals, a breakdown by model, and a breakdown by the statement that claims each part, over GET /providers/earnings. Without --month, the current month. Every amount is an exact decimal USD string, printed exactly as the wire sends it, never converted to a float.

Supports --json for machine-readable output.

heimdall providers list#

List approved providers, over GET /providers.

Supports --json for machine-readable output.

heimdall providers probe-now#

Makes one of the presented key's provider's endpoints due for a health probe immediately rather than waiting out the failure backoff, and reports the schedule the request left on it. Over POST /providers/probe-now. --endpoint-id names which endpoint, as providers status publishes it; a withdrawn endpoint and one belonging to somebody else both answer 404. The answer is the schedule rather than a verdict: the marketplace runs the probe on its next tick, and the request has been served once providers status reports a last_probe_at newer than the requested_at printed here. Refused, at the interval the schedule itself keeps to, when the endpoint was probed or asked for too recently. The provider must be approved.

Supports --json for machine-readable output.

heimdall providers pull-now#

Re-reads one of the presented key's provider's source documents immediately rather than waiting for its schedule, and reports the resulting pull run. Over POST /providers/pull-now. --source-id names which source; it is required only where the provider holds more than one active source. Refused, at the interval the schedule itself keeps to, when the named source (or the provider’s whole set of sources when none is named) was pulled too recently. The provider must be approved.

Supports --json for machine-readable output.

heimdall providers statements#

Every statement issued to the presented key's provider, newest period first, over GET /providers/statements. earliest_earned_month is the earliest month of an earning the statement claims, which reads earlier than period_start when the statement picked up an earning that settled after its own month was already paid. Every amount is an exact decimal USD string, printed exactly as the wire sends it.

Supports --json for machine-readable output.

heimdall providers status#

The presented key's provider: every live, pending-health, provider-not-ready or disabled endpoint it serves, with the same health, measured figures and pricing a customer choosing one would read off the catalogue, beside the outcome of the provider's most recent pull of any of its source documents. Over GET /providers/status. last_pull is null before the first pull. Withdrawn endpoints are not listed and are not counted. Each endpoint carries when it was last probed and how that probe ended, and one line under the table names when its newest failed probe ran and what it was answered with: the path the provider's own server was asked for and the status it gave, beside the status the marketplace recorded.

Supports --json for machine-readable output.

heimdall providers validate#

Validate a models document against the marketplace’s own v2.4 parser, offline, before it is published. Reports the same errors a pull of the document records, so a mistake is caught here rather than in a reconcile warning hours later. Runs no tips, since every tip reads measured or filled marketplace state (health, capability checks, Hub-filled facts) this command never fetches.

Supports --json for machine-readable output.

heimdall rerank#

Rank text documents against a query. Give the query first and documents after it, or repeat --document. Use --request for the full JSON request including image documents and provider preferences.

Supports --json for machine-readable output.

heimdall speech#

Speak text and save the audio. Use --request for the full JSON request, including a voice sample or provider preferences. --json reports metadata, never encoded audio.

Supports --json for machine-readable output.

heimdall stats#

Marketplace usage aggregates over the last 30 days, over GET /stats/public.

Supports --json for machine-readable output.

heimdall status#

The status board: every approved provider's live endpoints with measured health, over GET /status.

Supports --json for machine-readable output.

heimdall transcribe#

A transcription over POST /audio/transcriptions: upload a FILE as multipart/form-data, or pass a JSON --request containing base64 input_audio. Prints the transcript text; under --json, the full response document (usage.seconds, usage.cost, and duration/language/segments/words when the endpoint reports them).

Supports --json for machine-readable output.

heimdall version check#

Check npm for eligible updates without installing anything. Staging recommendations wait 24 hours; production recommendations wait 72 hours.

Supports --json for machine-readable output.

Aliased as upgrade.

heimdall videos create#

Generate a video from a prompt. Use --input for a full JSON request with references and provider options. Use --out to wait and save the MP4, or --wait to return the completed job.

Supports --json for machine-readable output.

heimdall videos models#

List video generation models and their declared capabilities.

Supports --json for machine-readable output.

heimdall videos show#

Read a video job and its generation progress. Use --wait to wait for completion or --out to wait and save the MP4 to a new file.

Supports --json for machine-readable output.