CLI

Every endpoint in this documentation is also a command. @pidgeon-ai/cli has one per operation, generated from the same OpenAPI document as the clients, so it cannot offer a command the API does not have.

npm install -g @pidgeon-ai/cli
export PIDGEON_API_KEY=pgn_live_…

pidgeon identities list

The shape

pidgeon <group> <command> [--flags]

The group is the resource, the command is what you are doing to it. pidgeon --help lists every group; pidgeon <group> <command> --help describes one command, names the endpoint it calls, and lists its flags with the required ones marked.

pidgeon messages send \
--from you@yourdomain.com \
--to someone@example.com \
--subject "First one" \
--text "It works."

Flags

A list flag repeats. Several recipients are several --to:

pidgeon messages send --from you@yourdomain.com \
--to one@example.com --to two@example.com --subject Hi --text Hello

--flag value and --flag=value are the same thing, and a value may contain an = — a subject often does.

A nested object takes JSON. Flags are the top level of a request body; anything below that is a field you pass as a string:

pidgeon identities update --id idn_4f2a1 --send_policy reply_only

Where it points

PIDGEON_BASE_URL sends it somewhere other than production, which is what you want against a local server:

PIDGEON_BASE_URL=http://localhost:3000/api/v1 pidgeon identities list

What it returns

The response body, as JSON, on stdout. Nothing is reformatted or summarised, so jq works and so does piping it into anything else:

pidgeon identities list --limit 5 | jq -r '.data[].email'

A failure prints the API's own message to stderr and exits non-zero — 2 for something wrong with the command line, 1 for anything else. The message is the one a person should read: "That address can only reply to people who have written to it first" rather than a status code.