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.

Using an MCP coding agent like Claude Code, Codex, or Cursor? Run hevn mcp install to expose every command as an MCP tool — the guidance below is delivered to the agent automatically.

Discover the CLI contract

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

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:

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.

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:

hevn --non-interactive --yaml contacts list

Read before writing

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

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:

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.

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

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:

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:

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:

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.