Configuration

Configure HEVN environments, API credentials, output formats, and debug behavior.

Config file

By default, HEVN CLI stores local configuration at:

~/.config/hevn-cli/config.json

Override the config path with:

export HEVN_CLI_CONFIG="/path/to/config.json"

The config file is written with restrictive file permissions when possible.

Environments

Select an environment globally:

export HEVN_ENV="prod"

Or per command:

hevn --env dev account get
hevn --env local login

Built-in environments:

Environment	Site URL	API URL
prod	https://app.gethevn.com	https://api.hevn.finance/api/v1
dev	https://app-beta.hevn.finance	https://dev-api.hevn.finance/api/v1
local	http://localhost:8081	Local or configured development API

You can also override URLs directly:

export HEVN_BASE_URL="https://api.hevn.finance/api/v1"
export HEVN_SITE_URL="https://app.gethevn.com"

API keys

The preferred interactive auth path is:

hevn login

This saves:

• api_key
• api_key_header
• base_url, when returned by the login callback

For automation, either save a key directly:

hevn login --api-key hvn_...
hevn login --api-key hvn_... --api-key-header X-Api-Key
hevn login --api-key hvn_... --api-base-url https://api.example.com/api/v1

or set credentials through environment variables:

export HEVN_API_KEY="hvn_..."
# Optional. Defaults to Authorization.
export HEVN_API_KEY_HEADER="Authorization"

Authorization mode adds a Bearer prefix automatically when the key does not already start with one. Use X-Api-Key only when your backend deployment requires that header:

export HEVN_API_KEY_HEADER="X-Api-Key"

The CLI no longer uses HEVN_APP_ID; transfer endpoints derive the owning app from the API key.

Output formats

Human output is optimized for terminal use with Rich tables and panels. For scripts and agents, prefer JSON or YAML. You can set output globally:

hevn --json contacts list
hevn --yaml invoice list
export HEVN_OUTPUT_FORMAT=yaml

or per command:

hevn contacts list --json
hevn invoice list --yaml
hevn contracts preview --id <contract-id> --yaml

Structured success output is wrapped as ok, data, meta, and warnings. Structured error output is wrapped as ok, errorCode, errorType, error, and exitCode.

Automation controls

Use non-interactive mode to refuse prompts and return structured INTERACTIVE_REQUIRED errors when a required flag is missing:

hevn --non-interactive --yaml contacts new --type email

Use dry-run mode to preflight mutating HTTP calls without sending the request:

hevn --dry-run transfer --invoice-id <invoice-id> --memo "Invoice payment"

Inspect the full CLI contract for agents and scripts:

hevn --schema
hevn --schema --yaml
hevn agent-skill

Debugging

Use --debug to include invocation and curl details in error output:

hevn --debug invoice get <invoice-id>

Or set:

export HEVN_DEBUG=1

Debug output can include sensitive headers and request payloads. Avoid sharing raw debug logs without redaction.