> ## 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.

# Agent workflows

> Primary operating guide for AI agents and scripts that use HEVN CLI safely.

HEVN CLI is designed primarily for AI agents and automation, with human terminal output as a convenience layer. Agents should prefer explicit flags, structured output, non-interactive execution, and confirmation-free commands only when the user's intent is clear.

<Note>
  Using an MCP coding agent like Claude Code, Codex, or Cursor? Run [`hevn mcp install`](/connect-agents) to expose every command as an MCP tool — the guidance below is delivered to the agent automatically.
</Note>

## Discover the CLI contract

Before planning or executing a HEVN workflow, load the packaged agent guide:

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

This command prints the current `CLAUDE.md` operating guide shipped with the CLI. Agents must read it first because it contains workflow-specific instructions that are more detailed than the command manifest.

Then load the machine-readable manifest:

```bash theme={null}
hevn --schema
```

The schema includes commands, global options, auth methods, output envelopes, danger levels, idempotency support, and stable error codes.

## Use structured output

Prefer YAML or JSON for reads and automation. In structured mode, successful output is wrapped in `ok`, `data`, `meta`, and `warnings`; errors include `errorCode`, `errorType`, `error`, and `exitCode`.

```bash theme={null}
hevn --yaml whoami
hevn profile get --yaml
hevn contacts list --yaml
hevn contracts preview --id <contract-id> --yaml
```

Use `--non-interactive` or `--no-input` when prompts must be forbidden:

```bash theme={null}
hevn --non-interactive --yaml contacts list
```

## Read before writing

For money movement and contract operations, load the relevant resource first:

```bash theme={null}
hevn profile get --yaml
hevn contacts list --yaml
hevn invoice get <invoice-id> --yaml
hevn contracts preview --id <contract-id> --yaml
```

Then perform the write with explicit ids and amounts.

## Contract role selection

When creating a contract from a document, determine which party is the current HEVN user:

```bash theme={null}
hevn profile get --yaml
```

Then compare the current user against the parties in the document.

* If the current user is the client, pass the counterparty as `--contractor-email`.
* If the current user is the contractor, pass the counterparty as `--client-email`.

The email flag always identifies the counterparty's role, not the current user's role.

<Warning>
  Do not assume the current HEVN user is always the client. Many contract workflows have the current user acting as the contractor.
</Warning>

## Avoid invented data

If a document does not contain the counterparty's email, ask the user. Do not invent emails, addresses, tax ids, bank details, invoice dates, or amounts.

## Use idempotency for transfers

For payment automation, pass your own idempotency key:

```bash theme={null}
hevn transfer contact \
  --contact-id <contact-id> \
  --amount 25 \
  --idempotency-key <stable-operation-id> \
  --yaml
```

Use `--dry-run` for mutating commands when you need to inspect the would-be request before sending it:

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

## Confirmation flags

Use `--yes` only when the user or upstream workflow has already approved the action:

```bash theme={null}
hevn transfer contact --contact-id <contact-id> --amount 25 --yes
hevn invoice decline --invoice-id <invoice-id> --yes
hevn contracts delete --id <contract-id> --yes
```

## Debug safely

`--debug` can include curl commands and authentication details. Use it for local troubleshooting, but redact before storing or sharing logs.