hevn-cli 0.1.0

Command-line client for the HEVN backend API and MCP transfers.

HEVN CLI

Standalone command-line wrapper for the HEVN backend API and MCP transfers.

Requires an active HEVN account. Sign up at app.gethevn.com before installing.

Install

For end users:

pipx install hevn-cli
hevn login
hevn --help

Before the package is published to PyPI, install from GitHub so pipx upgrade can fetch newer commits:

pipx install "git+https://github.com/hevn/hevn-cli.git"
pipx upgrade hevn-cli

For local development:

poetry install
poetry run hevn --help

For local wheel smoke testing only:

poetry build
pipx install dist/hevn_cli-0.1.0-py3-none-any.whl

Local wheel installs are not a good long-term pipx install source because pipx upgrade hevn-cli can only reinstall from that same local artifact.

Publish

PyPI publishing is handled by the Publish to PyPI GitHub Actions workflow. Run it manually from the main branch. The workflow runs lint, tests, and hevn --help on Ubuntu, macOS, and Windows, then builds and publishes the package once from Ubuntu.

The workflow uses PyPI trusted publishing. In the PyPI project hevn-cli, configure a trusted publisher with GitHub owner hevn, repository hevn-cli, workflow .github/workflows/publish-pypi.yml, and environment pypi.

Environment

export HEVN_ENV="prod" # prod (default), dev, or local
export HEVN_API_KEY="<app bearer token or app api key>"
export HEVN_MCP_KEY="mcp_..."

Optional:

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

Authorization is the default app header and is sent as Bearer <HEVN_API_KEY>. Use HEVN_API_KEY_HEADER=X-API-Key if a deployment exposes app endpoints by API key. Use HEVN_* environment variables for CLI configuration.

Built-in environments:

Env	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	http://localhost:8000/api/v1

You can also select the environment per command:

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

Clear saved CLI credentials:

hevn logout

Examples

hevn contacts list
hevn contacts list --yaml
hevn login
hevn account list --yaml
hevn banks list --all
hevn contacts new
hevn contacts new --type email --name "Vendor" --email [e-mail]
hevn transfer contact <contact-id> 25 --memo "Thanks"
hevn transfer contact --contact-id <contact-id> --amount 25 --memo "Thanks"
hevn transfer contact --contact-id <contact-id> --amount 25 --yes --memo "Bank payout"
hevn transfer contact --contact-id <contact-id> --amount 25 --bank-account-id <bank-account-id> --yes --memo "Bank payout"
hevn transfer contact --contact-id <contact-id> --quote-id <quote-id> --memo "Bank payout"
hevn invoice list
hevn bills --yaml
hevn invoice get <invoice-id>
hevn invoice decline --invoice-id <invoice-id> --yes --yaml
hevn invoice new
hevn invoice new --contractor-email [e-mail] --contractor-name Vendor --item "Consulting:1:100" --due-date 2026-06-01
hevn invoice upload-incoming --path ./invoice.pdf --contractor-email [e-mail] --items '[{"name":"Consulting","quantity":1,"price":"100"}]'
hevn invoice batch --contract '{"contractId":"<contract-id>","period":0,"memo":"May payroll","items":[{"name":"Monthly services","quantity":1,"price":"5000"}]}' --yaml
hevn contracts list --yaml
hevn contractors list --yaml
hevn contracts preview --id <contract-id> --yaml
hevn contracts new --contractor-email [e-mail] --type default_contractor --amount 1000 --currency USD --period monthly --activation-at 2026-05-01 --yaml
hevn contracts new --contractor-email [e-mail] --type custom --document-id <document-id> --item '{"name":"Design","quantity":2,"price":"100"}' --yaml
hevn contracts payment-methods --id <contract-id> --payment-method '{"accountType":"email","email":"[e-mail]"}' --yaml
hevn contracts --id <contract-id> approve --yaml
hevn hire --contractor-email [e-mail] --job-title "Engineer" --scope-description "Full-time engineering work" --amount 5000 --currency USD --period monthly --start-date 2026-05-01 --yaml
hevn transfer --invoice-id <invoice-id> --memo "Invoice payment"
hevn deposit 100 usdc base
hevn deposit --amount 100 --currency usdc --chain base
hevn rate EUR
hevn rate --currency AED --yaml

Contract statuses:

pending_approval_by_contractor
pending_approval_by_client
active
completed
cancelled
paused

hevn hire is a convenience alias for creating a contractor contract. Preview it with hevn contracts preview --id <contract-id> --yaml, then approve with hevn contracts --id <contract-id> approve --yaml.

Contract migration guidance

When a user asks to move or import contracts or contractors into HEVN, load them by creating a new active contract from the contract file rather than only adding contractor records. For Deel migrations, first suggest that the user create a Deel API token at app.deel.com/settings/developer/tokens/create.