---
title: "Getting started"
description: "Install Hafi, configure provider credentials, connect Gmail or Lark, and run a safe dry run."
---

> Documentation Index
> Fetch the complete documentation index at: https://hafi-go-hands-free-docs.free-hero-8440.chatgpt.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

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

```sh
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](/gmail-setup) before connecting.

## Connect accounts

```sh
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](/workflow#example), then run:

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

```sh
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.

Source: https://hafi-go-hands-free-docs.free-hero-8440.chatgpt.site/getting-started/index.mdx