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

# CLI

> Send and inspect emails from your terminal with the pulsesend command.

`pulsesend` is a single binary with no dependencies. It talks to the same [API](/api-reference/introduction) as your code, with the same keys.

## Install

On macOS and Linux:

```bash theme={"dark"}
curl -fsSL https://pulse-send.jiordiviera.me/install.sh | sh
```

The script picks the build for your system (Linux x86\_64 or ARM64, macOS Intel or Apple Silicon), checks its SHA-256 checksum, and installs it in `~/.local/bin`. Two variables change that:

```bash theme={"dark"}
# A specific version, in another folder
curl -fsSL https://pulse-send.jiordiviera.me/install.sh | PULSESEND_VERSION=0.1.0 PULSESEND_INSTALL_DIR=/usr/local/bin sh
```

On Windows, download [`pulsesend-0.1.0-x86_64-pc-windows-gnu.zip`](https://media.pulse-send.jiordiviera.me/cli/0.1.0/pulsesend-0.1.0-x86_64-pc-windows-gnu.zip), unzip it, and put `pulsesend.exe` in a folder on your `PATH`.

Check the install:

```bash theme={"dark"}
pulsesend --version
```

## Log in

Create a key in the dashboard under **API keys**, then:

```bash theme={"dark"}
pulsesend login
```

The CLI asks for the key without showing it, checks it against the API, and saves it in `~/.config/pulsesend/config.json`, readable only by you. `pulsesend whoami` shows which key is in use and whether it works; `pulsesend logout` removes it.

In CI or scripts, skip `login` and set the key in the environment instead:

```bash theme={"dark"}
export PULSESEND_API_KEY=ps_live_…
```

`--api-key` on any command takes precedence over both.

<Tip>Use a `ps_test_` key while you try things out: emails are recorded but never delivered, and they cost no credits.</Tip>

## Send an email

```bash theme={"dark"}
pulsesend send \
  --from "Acme <hello@acme.com>" \
  --to customer@example.com \
  --subject "Your code is 482910" \
  --text "Your verification code is 482910. It expires in 10 minutes."
```

The body can come from a file, or from standard input with `-`:

```bash theme={"dark"}
pulsesend send --from hello@acme.com --to customer@example.com \
  --subject "Your receipt" --html-file receipt.html

render-receipt | pulsesend send --from hello@acme.com --to customer@example.com \
  --subject "Your receipt" --html-file -
```

| Option | |
| - | - |
| `--to`, `--cc`, `--bcc` | Repeat the option or separate addresses with commas |
| `--html`, `--html-file`, `--text`, `--text-file` | At least one body; files accept `-` for stdin |
| `--reply-to` | Reply-to address |
| `--tag` | Repeatable, up to 10 |
| `--header "Name: value"` | Repeatable, up to 20 |
| `--idempotency-key` | Makes retries safe, see [Idempotency](/guides/idempotency) |

The same [limits](/guides/limits) as the API apply, and the sender must be on a [verified domain](/guides/domains) with a live key.

## Inspect emails

```bash theme={"dark"}
pulsesend emails list            # the latest 20, newest first
pulsesend emails list --limit 50
pulsesend emails get em_01j9z…
```

When there are more emails, the list ends with the command for the next page.

## JSON output

Add `--json` to any command to get the raw API response, for scripts and `jq`:

```bash theme={"dark"}
pulsesend emails list --json | jq -r '.data[] | select(.status == "bounced") | .id'
```

## Errors

Errors print the API's message, its [error code](/errors) with a link to the docs, and the request id to give support. The command then exits with code `1`.

```text theme={"dark"}
error: Invalid or revoked API key. (401)
  code:    invalid_api_key
  type:    authentication_error
  request: req_01m5b1kzmt4kjqewgxm1x8eq9c
  docs:    https://docs.pulse-send.jiordiviera.me/errors#invalid_api_key
```

## Environment variables

| Variable | |
| - | - |
| `PULSESEND_API_KEY` | API key, instead of `pulsesend login` |
| `PULSESEND_BASE_URL` | API URL, defaults to `https://pulse-send.jiordiviera.me` |
| `HTTPS_PROXY`, `HTTP_PROXY` | Proxy for outgoing requests |


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