CLI

The hessian CLI talks to a Hessian API. Most users only ever target a single environment, but the CLI is built around contexts (also called profiles) so you can switch between, for example, a hosted production deployment, a shared dev environment, and a local stack — without re-typing API URLs or copying tokens between shells.

For the auto-generated per-command pages see the CLI Reference.

Contexts at a glance

A context (or profile) is a named bundle of:

• HESSIAN_API_HOST — the API URL the CLI should call
• HESSIAN_API_KEY — long-lived API key (optional)
• HESSIAN_TOKEN — OAuth bearer token written by hessian login (optional)
• Per-profile request headers (e.g. Cloudflare Access service tokens)

Contexts are stored in ~/.hessian/credentials (INI format, mode 0600). The currently-active context is recorded in ~/.hessian/config.yaml under current_context.

# ~/.hessian/credentials
[default]
HESSIAN_API_HOST=https://api.hessian.sh
HESSIAN_TOKEN=eyJ...

[nonprod]
HESSIAN_API_HOST=https://api.dev-hessian.sh
HESSIAN_API_KEY=wtp_...
HESSIAN_HEADER=CF-Access-Client-Id: 1234.access
HESSIAN_HEADER=CF-Access-Client-Secret: hunter2

# ~/.hessian/config.yaml
current_context: nonprod

Resolution order

For each request, the CLI picks the active profile in this order — the first match wins:

1. --profile <name> flag
2. HESSIAN_PROFILE environment variable
3. current_context in ~/.hessian/config.yaml
4. default

Within the chosen profile, individual values still defer to explicit overrides: a --api_url flag or a HESSIAN_API_URL env var beats the profile’s HESSIAN_API_HOST. --header flags merge with (and can override) per-profile headers for a single invocation.

Configuring contexts

Add a context

hessian config add-context nonprod 
  --api_url https://api.dev-hessian.sh

--api_url is required. --api_key is optional — leave it off if you’d rather use OAuth, then run hessian login --profile nonprod to populate HESSIAN_TOKEN instead.

Pass --force to overwrite an existing profile.

Switch the active context

hessian config context              # list, with * marking the active one
hessian config context nonprod      # switch

The named profile must already exist. The switch is persisted to config.yaml, so the next shell you open keeps the same active context.

One-shot override

If you just want to run a single command against a different environment, skip the switch and pass --profile:

hessian --profile prod worker list

This works for any subcommand, including hessian login --profile <name>, which lets you log into a fresh profile in one shot — the profile is created on first write.

Delete a context

hessian config delete-context nonprod

Removes the section from credentials and deletes the per-profile ~/.hessian/nonprod/ directory (which holds e.g. worker_config.yaml). If the deleted profile was the active one, current_context is cleared.

Tab completion

Profile names tab-complete on the --profile flag and on the context, delete-context, and header --profile commands. Set up shell completion with hessian completion <bash|zsh|fish|powershell>.

Per-profile headers

Some environments sit behind transport-layer auth — most commonly Cloudflare Zero Trust, which expects CF-Access-Client-Id and CF-Access-Client-Secret on every request. Rather than typing -H flags repeatedly, attach the headers to the profile:

hessian config header add "CF-Access-Client-Id: 1234.access"     --profile nonprod
hessian config header add "CF-Access-Client-Secret: hunter2"     --profile nonprod

hessian config header list   --profile nonprod
hessian config header remove CF-Access-Client-Secret --profile nonprod

--profile defaults to the active context. Header names are validated as HTTP tokens (RFC 7230) and values may not contain control characters such as CR/LF. Adding a header with the same name (case-insensitive) replaces the existing entry.

At request time, profile headers are sent first, then merged with any -H/--header flags — a flag entry with the same name overrides the profile entry for that one invocation.

Subprocess inheritance

When the CLI spawns a child process (notably the worker runner), the resolved values are also exported into the environment as HESSIAN_API_HOST, HESSIAN_API_URL, HESSIAN_API_KEY, and HESSIAN_TOKEN. So a --profile prod flag at the top-level reaches every subprocess without you having to forward env vars manually.

File layout summary

~/.hessian/
├── config.yaml           # current_context
├── credentials           # all profiles (mode 0600)
└── <profile>/            # per-profile state
    └── worker_config.yaml