Install Hafi, configure provider credentials, connect Gmail or Lark, and run a safe dry run.

Getting started

Hafi currently runs from source with Bun 1.3 or later. It has no release binary yet. You also need the local Codex CLI and credentials for the providers in your workflow.

Install and inspect the CLI

From the Hafi repository:

bun install
bun run dev help

bun run dev runs the CLI from source without watch mode. Use bun run --silent dev help --json when machine-readable output should not include Bun’s script banner. In this guide, commands shown as hafi ... are CLI command forms; prefix them with bun run dev while running from source.

Configure provider credentials

Jev uses hafi connect jev to collect and store its API key locally. Provider app credentials are environment variables:

Provider	Variables
Gmail	`HAFI_GMAIL_CLIENT_ID`, `HAFI_GMAIL_CLIENT_SECRET`
Lark	`HAFI_LARK_APP_ID`, `HAFI_LARK_APP_SECRET`, `HAFI_LARK_REDIRECT_URI`

Keep app credentials out of committed files. User tokens are stored in the operating system credential store, not in workflow YAML.

For Gmail, use a Google OAuth client whose application type is Desktop app. Hafi binds its browser callback to 127.0.0.1 on a random available port. A Web application client with a fixed redirect URI can fail with redirect_uri_mismatch. Follow Gmail OAuth setup and troubleshooting before connecting.

Connect accounts

bun run dev connect gmail --account personal
bun run dev connect lark --account work
bun run dev connect jev

Connect only the providers listed in your workflow. personal and work are local credential aliases; they do not store secrets in YAML. For the default Gmail alias, hafi connect gmail uses personal.

Browser authorization is a user step. A coding assistant can run the CLI during onboarding, but it cannot complete the account owner’s consent for them.

Validate and dry run

Create a workflow from the example YAML, then run:

bun run dev workflow validate hafi.yaml
bun run dev dev --workflow hafi.yaml

hafi dev --workflow <file> is the safe dry run: it reads and evaluates messages without advancing cursors or saving drafts. Live provider permissions and coverage still need end-to-end verification.

Run and review

When ready, run the one-shot workflow with bun run dev run-once --workflow hafi.yaml. Review results with bun run dev results --workflow <workflow-id> and check progress with bun run dev status --workflow <workflow-id>. These commands are implemented; live account behavior should be verified in your environment before scheduling.

Print (do not install) a cron entry with:

bun run dev schedule print --workflow hafi.yaml --platform cron

The command prints the schedule entry. Add it to your system cron yourself after reviewing the path and environment it needs. Hafi runs as a short-lived process and does not require a permanent daemon.