Metadata-Version: 2.4
Name: hevn-cli
Version: 0.1.0
Summary: Command-line client for the HEVN backend API and MCP transfers.
License: MIT
License-File: LICENSE
Keywords: hevn,cli,fintech,payments,invoicing,mcp,stablecoin
Author: HEVN Team
Author-email: team@hevn.finance
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: click (>=8.1.8,<8.2)
Requires-Dist: httpx (==0.28.1)
Requires-Dist: prompt-toolkit (==3.0.36)
Requires-Dist: python-dotenv (==1.2.2)
Requires-Dist: pyyaml (==6.0.3)
Requires-Dist: qrcode (==8.2)
Requires-Dist: questionary (==2.1.0)
Requires-Dist: rich (==13.9.4)
Requires-Dist: typer[all] (==0.15.1)
Project-URL: Homepage, https://github.com/hevn/hevn-cli
Project-URL: Repository, https://github.com/hevn/hevn-cli
Description-Content-Type: text/markdown

# HEVN CLI

Standalone command-line wrapper for the [HEVN](https://app.gethevn.com) backend API and MCP transfers.

> Requires an active HEVN account. Sign up at [app.gethevn.com](https://app.gethevn.com) before installing.

## Install

For end users:

```bash
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:

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

For local development:

```bash
poetry install
poetry run hevn --help
```

For local wheel smoke testing only:

```bash
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

```bash
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:

```bash
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:

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

Clear saved CLI credentials:

```bash
hevn logout
```

## Examples

```bash
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 vendor@example.com
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 vendor@example.com --contractor-name Vendor --item "Consulting:1:100" --due-date 2026-06-01
hevn invoice upload-incoming --path ./invoice.pdf --contractor-email vendor@example.com --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 contractor@example.com --type default_contractor --amount 1000 --currency USD --period monthly --activation-at 2026-05-01 --yaml
hevn contracts new --contractor-email contractor@example.com --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":"contractor@example.com"}' --yaml
hevn contracts --id <contract-id> approve --yaml
hevn hire --contractor-email contractor@example.com --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:

```text
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](https://app.deel.com/settings/developer/tokens/create).

