> ## Documentation Index
> Fetch the complete documentation index at: https://hevninc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

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

## Config file

By default, HEVN CLI stores local configuration at:

```text theme={null}
~/.config/hevn-cli/config.json
```

Override the config path with:

```bash theme={null}
export HEVN_CLI_CONFIG="/path/to/config.json"
```

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

## Environments

Select an environment globally:

```bash theme={null}
export HEVN_ENV="prod"
```

Or per command:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
hevn login
```

This saves:

* `api_key`
* `api_key_header`
* `base_url`, when returned by the login callback

For automation, either save a key directly:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
hevn --json contacts list
hevn --yaml invoice list
export HEVN_OUTPUT_FORMAT=yaml
```

or per command:

```bash theme={null}
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:

```bash theme={null}
hevn --non-interactive --yaml contacts new --type email
```

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

```bash theme={null}
hevn --dry-run transfer --invoice-id <invoice-id> --memo "Invoice payment"
```

Inspect the full CLI contract for agents and scripts:

```bash theme={null}
hevn --schema
hevn --schema --yaml
hevn agent-skill
```

## Debugging

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

```bash theme={null}
hevn --debug invoice get <invoice-id>
```

Or set:

```bash theme={null}
export HEVN_DEBUG=1
```

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