> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helohq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the Helo CLI and manage your account and send email from the command line

The `helo` CLI covers the whole Helo API from your terminal: send email, manage domains, channels and webhooks, and look up activity and statistics. Its output is JSON, so it works well in scripts and with AI agents too.

## Install

<Tabs>
  <Tab title="Homebrew">
    On macOS or Linux:

    ```bash theme={null}
    brew install helo-email/tap/helo
    ```

    Use the full name `helo-email/tap/helo`. Plain `helo` installs an unrelated app.
  </Tab>

  <Tab title="Install script">
    On macOS or Linux:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/helo-email/helo-cli/main/install.sh | sh
    ```

    The script downloads the latest release for your platform, verifies its checksum and installs `helo` to `~/.local/bin`. Set `HELO_INSTALL_DIR` to install it somewhere else.
  </Tab>

  <Tab title="Go">
    With Go installed:

    ```bash theme={null}
    go install github.com/helo-email/helo-cli/cmd/helo@latest
    ```
  </Tab>

  <Tab title="Windows">
    Download the `.zip` for your architecture from the [latest release](https://github.com/helo-email/helo-cli/releases/latest), extract `helo.exe`, and put it in a folder on your `PATH`.
  </Tab>
</Tabs>

<Note>
  On macOS, install with Homebrew or the install script rather than downloading the archive in your browser. macOS blocks browser-downloaded binaries that aren't notarized by Apple.
</Note>

Check that it works:

```bash theme={null}
helo --version
```

## Authenticate

The CLI authenticates with an [API credential](/core/credentials). Set it as an environment variable:

```bash theme={null}
export HELO_API_KEY="your-api-key"
```

You can also pass it on each command with `--token`.

If your credential can send through more than one [Channel](/core/channels), also set the Channel to send through:

```bash theme={null}
export HELO_CHANNEL_ID="your-channel-id"
```

Commands that send take `--channel-id` to override it.

## Send an email

```bash theme={null}
helo sending send-transactional \
  --from '{"email": "you@yourdomain.com", "name": "Your Name"}' \
  --to '[{"email": "recipient@example.com"}]' \
  --subject "Hello from Helo" \
  --text "This is a test message, delivered with <3 by Helo."
```

<Info>
  While your account is in test mode, you can only send to email addresses on domains you have verified.
</Info>

Add `--dry-run` to any command to print the request it would send, without sending it.

## Common commands

```bash theme={null}
helo domains list                                                # list your domains
helo channels list                                               # list your Channels
helo activity list-messages --start-date 24h                     # messages from the last 24 hours
helo statistics retrieve-daily --from 7d --to 0d --timezone UTC  # daily statistics for the last week
```

Run `helo --help` to list every command, and `helo <command> --help` for a command's flags.

## Input and output

Each field of a request body has its own flag. You can also pass the whole body as JSON with `--data`, inline or from a file:

```bash theme={null}
helo sending send-transactional --data @message.json
```

Results print to stdout as JSON:

```json theme={null}
{
  "ok": true,
  "data": { ... }
}
```

Add `--quiet` to print only `data`, which is handy for piping into `jq`:

```bash theme={null}
helo domains list --quiet | jq '.results[].name'
```

Errors go to stderr. Each kind of error has its own exit code, so scripts can tell them apart: `3` means a credential problem, `5` means the API rejected the request, and `6` means a retry may help. Run `helo --help` for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.