Heimdall Staging CLI

Use heimdall-staging to browse models, run inference, manage your account and generate meshes and videos on the Heimdall staging service. Requires Node.js 22.12 or later.

Install

npm install -g @staging-heimdall/cli
heimdall-staging --version
heimdall-staging --help

Connect to staging

The staging CLI uses https://api-staging.impossiblecarrot.cc/api/v1 for API requests and https://staging.impossiblecarrot.cc for browser login by default. No URL setup is needed. Use --api (also accepted as --base-url) to send a command to another API, and --web-url to change the browser login origin. HEIMDALL_STAGING_BASE_URL and HEIMDALL_STAGING_WEB_URL provide the same overrides for a shell session.

Browse the public catalogue without signing in:

heimdall-staging models list
heimdall-staging providers list
heimdall-staging status

Sign in

heimdall-staging login
heimdall-staging auth status

login opens the approval page and waits for its one-time code. Paste that code into the waiting terminal. The browser can run on another computer. For SSH or a headless host, use heimdall-staging login --manual: open the printed URL on any computer, approve, then paste the code back into the original terminal. Keep the terminal open; codes expire after ten minutes and work once. Code input is hidden. If an older approval page redirects to an unreachable localhost address, paste that complete address into the waiting terminal instead.

If you already have an API key in a file, use heimdall-staging login --with-token < key.txt instead. For automation, supply the key through HEIMDALL_STAGING_API_KEY.

Credentials use the OS keychain when available, with a restricted-permission file as the fallback: $XDG_CONFIG_HOME/heimdall-staging/hosts.json (normally ~/.config/heimdall-staging/hosts.json). HEIMDALL_STAGING_CREDENTIAL_BACKEND=file selects that fallback explicitly.

Choose a Spending key for inference. To use keys list, keys create, keys rotate or keys revoke, create a Management key on the staging account's API keys tab and supply it with login --with-token or HEIMDALL_STAGING_API_KEY. Only the account owner or an organization admin can create management keys. A management key manages keys in its own workspace and cannot pay for inference. Revoking it does not revoke the keys it created; revoke those separately.

Staging has its own credentials, configuration, history and cache. It does not read the HEIMDALL_* variables or saved credentials used by the separate heimdall command.

heimdall-staging credits
heimdall-staging activity
heimdall-staging logout

Use a model

An inference command without --model selects the newest live model that accepts its input and produces the requested output. It prints the selected ID on stderr. Pass --model when the model or price matters to you.

heimdall-staging chat "What is the capital of France?"
heimdall-staging embed "The quick brown fox"
heimdall-staging rerank "Which team handles refunds?" "Billing" "Engineering"
heimdall-staging decisions "We were billed twice" "Which team?" --choice billing=refunds --choice engineering=bugs
heimdall-staging image "A lighthouse in fog" --out lighthouse.png
heimdall-staging speech "Welcome aboard" --out welcome.mp3
heimdall-staging transcribe clip.mp3

complete covers the legacy text completions route. decisions --request request.json sends multiple typed questions or a structured state; rerank --request request.json accepts image documents. Each command's --help lists its options. Inference and generation can incur staging charges.

Wait for a mesh or video

Give a text prompt directly, or use --input request.json for references and engine settings:

heimdall-staging meshes create "A clay vase" --out result.glb
heimdall-staging videos create "A lighthouse in fog" --duration 4 --out result.mp4

--out submits once, waits for completion and saves the result. Use --wait to wait without downloading. Progress on stderr includes elapsed waiting time, job status and optional mesh repair state; --json keeps stdout as one JSON result.

Temporary status failures retry within --timeout (7200 seconds by default), respecting the server's Retry-After delay. The CLI never automatically repeats a submission or download. Timeout or interruption leaves the job running. Resume the same job with its printed ID:

heimdall-staging meshes show JOB_ID --out result.glb
heimdall-staging videos show JOB_ID --out result.mp4

Existing output files are refused. An empty destination is removed after a failed download; partially written files are retained. Downloads are single-use and a failed transfer can consume the asset, so inspect the job before trying again.

Explore the commands

| Task | Command | | ------------------------------- | ----------------------------------------------- | | Browse image models | heimdall-staging models list --modality image | | Check your API key | heimdall-staging key | | List mesh generation models | heimdall-staging meshes models | | Learn how to submit a mesh job | heimdall-staging meshes create --help | | List video generation models | heimdall-staging videos models | | Learn how to submit a video job | heimdall-staging videos create --help | | Check your provider | heimdall-staging providers status | | View local call history | heimdall-staging log | | Configure shell completion | heimdall-staging autocomplete --help |

Use --json on commands that support it for machine-readable output. heimdall-staging --help lists the available commands; heimdall-staging COMMAND --help explains an individual command.

Check for updates

heimdall-staging version check
heimdall-staging version check --json

Updates are manual. When an eligible update exists, the check prints an installation command with the exact recommended version. Staging releases become eligible after 24 hours; deprecated releases are excluded.

Interactive commands display an update notice at most once a day, including the number of eligible versions behind and the recommended release's age. Automatic checks stay silent in CI, with redirected or JSON output, and when npm is unavailable. Set HEIMDALL_STAGING_NO_UPDATE_NOTIFIER=1 to disable those notices.

You can install a fresh release before it becomes eligible for a recommendation. The delay applies to the CLI release, not to the age of its dependencies.

License

See LICENSE.md.