@pigeonscale/cli

Customer-facing CLI for Pigeonscale.

• pigeonscale: send + receive email, manage accounts, query messages/threads

Admin control CLI lives in packages/ctl (pigeonscalectl).

Requirements

• Node.js 20+
• pnpm

Install / build (from repo)

pnpm install
pnpm --filter @pigeonscale/cli build

Run from source (dev):

pnpm pigeonscale --help

Or run built output:

node packages/cli/dist/index.js --help

Provider model (cloud vs resend)

pigeonscale supports two providers:

• cloud: talks to the Pigeonscale Worker (/v1/...) using either:
  • human session mode (pigeonscale auth login)
  • API key mode (PIGEONSCALE_API_KEY)
• resend: talks directly to Resend using RESEND_API_KEY

When cloud-authenticated (either session.json exists or PIGEONSCALE_API_KEY is set), the CLI is pinned to cloud and rejects --provider resend.

Platform API key mode (psp_live_*)

If PIGEONSCALE_API_KEY starts with psp_live_, the CLI enters platform mode.

• auth login is disabled
• auth logout is disabled
• mail accounts create is disabled
• platform admin keys (platform_subscription_admin) are rejected in the main CLI
• mailbox user keys (platform_mailbox_user) are supported for read/send operations on assigned mailbox grants

psk_live_* keys are still accepted by the API for compatibility.

Provider selection applies to all commands:

1. --provider cloud|resend (flag wins)
2. else config provider (set via pigeonscale providers use …)
3. else default to cloud

Base URL selection (cloud):

1. --url <url>
2. else PIGEONSCALE_URL
3. else config baseUrl
4. else https://api.pigeonscale.com

Config files

Files live under ~/.config/pigeonscale/:

• config.json: CLI config (provider, primaryAccount, resend addresses, safety settings, scan settings)
• session.json: session state. Tokens are stored in native keychain when available, else in this file with 0600 permissions (written by pigeonscale auth login).
• pending-approvals.json: pending approval tokens (created by intent commands; cleared on exchange)

System messages

The CLI can optionally display system messages (security notices + CLI updates) at the top of pigeonscale mail list (inbound).

Cloud mode (provider=cloud)

Cloud mode is opt-out: system messages are enabled by default and controlled from the human approval screen (checkbox), persisted in D1.

Resend mode (provider=resend)

Resend mode requires an explicit choice (forced when unset):

pigeonscale config set enableSystemMessages true

To disable:

pigeonscale config set enableSystemMessages false

Operator notes (publishing)

System messages are stored in Workers KV binding PIGEONSCALE_SYSTEM_MESSAGES_KV under key ps:system_messages as a JSON array:

[
  {
    "id": "msg_2026_02_10",
    "message": "Important security update…",
    "timestamp": "2026-02-10T00:00:00.000Z",
    "providers": ["cloud", "resend"]
  }
]

Quickstart: cloud

Point the CLI at your Worker (optional; defaults to https://api.pigeonscale.com):

export PIGEONSCALE_URL="https://<your-worker-host>"

Log in (email approval). This supports signup with a personal/work email:

pigeonscale auth login them.com

Optionally request specific grants to pre-fill the approval UI:

pigeonscale auth login them.com --grants mailboxCreate,allMailboxes

Pick provider and create a mailbox:

pigeonscale providers use cloud
pigeonscale mail accounts create --human them.com --handle henry --from-name "Henry the Agent"
# optional explicit domain:
pigeonscale mail accounts create --human them.com --handle henry --domain pigeoninbox.com --from-name "Henry the Agent"

Send:

pigeonscale mail send --to [email protected] --subject "Hi" --body "Hello from Pigeonscale"

List inbox:

pigeonscale mail list

Stream newly-ready inbox messages:

pigeonscale mail watch
pigeonscale mail watch --account [email protected]
pigeonscale mail watch --exec ./handle-message.sh --max-parallel 4
pigeonscale mail watch --template '{{.message.id}}\\t{{.message.from}}\\t{{.message.text}}'
pigeonscale mail watch --template '{{.message.id}}' --delim-null

Quickstart: platform API key mode

Set platform mailbox key:

export PIGEONSCALE_API_KEY="psp_live_..."
export PIGEONSCALE_URL="https://<your-worker-host>"

Inspect identity/grants:

pigeonscale auth whoami

Use assigned mailbox:

pigeonscale mail list --account [email protected] --unread
pigeonscale mail send --account [email protected] --to [email protected] --subject "Hi" --body "Hello"

Notes:

• mailbox provisioning is done by your platform admin via SDK/operator flows
• pigeonscale auth login, pigeonscale auth logout, and pigeonscale mail accounts create are disabled in this mode

Quickstart: resend

Set your Resend API key:

export RESEND_API_KEY="re_..."

Pick provider and add an address to local config:

pigeonscale providers use resend
pigeonscale mail accounts create --address [email protected] --from-name "Henry the Agent"
pigeonscale mail accounts use [email protected]

Send:

pigeonscale mail send --to [email protected] --subject "Hi" --body "Hello from Resend"

List inbox / sent:

pigeonscale mail list
pigeonscale mail list --direction out

Resend-only limitations (high level):

• No unread filter (pigeonscale mail list --unread)
• Threading is best-effort and relies on +ps.<uuid> plus-addressing + headers
• Attachment download requires message direction-aware ids (msg_in_* / msg_out_*)

CLI reference (pigeonscale)

Auth (cloud)

pigeonscale auth login [email]
pigeonscale auth whoami
pigeonscale auth status
pigeonscale auth logout

In platform API key mode (PIGEONSCALE_API_KEY=psp_live_*), auth login and auth logout are intentionally unavailable.

Providers

pigeonscale providers use cloud
pigeonscale providers use resend

Accounts

Cloud mailboxes:

pigeonscale mail accounts create --human them.com --handle <handle> --from-name "Your Agent Name"
# optional explicit domain:
pigeonscale mail accounts create --human them.com --handle <handle> --domain pigeoninbox.com|pigeonscale.email --from-name "Your Agent Name"
# Optional: pre-fill approval UI grants
pigeonscale mail accounts create --human them.com --handle <handle> --domain pigeoninbox.com --from-name "Your Agent Name" --grants mailboxReadSend
pigeonscale mail accounts list

Resend addresses (local config):

pigeonscale providers use resend
pigeonscale mail accounts create --address <email> --from-name "Your Agent Name"
pigeonscale mail accounts list

Primary account:

pigeonscale mail accounts use <email>

Send

pigeonscale mail send [-a, --account <email>] --to <email...> --subject <subject> --body <markdownOr@fileOr->

Notes:

• If --account is omitted, primaryAccount is used (set via pigeonscale mail accounts use …)
• --dry-run prints a structured response without sending
• --print-mime prints the MIME message to stdout

Mail

List/search:

pigeonscale mail list [--account <email>] [--direction in|out|all] [--unread] [--after <ts>] [--before <ts>] [--query <q>]
pigeonscale mail show <id>

Streaming:

pigeonscale mail watch [--account <email>] [--id-only]
pigeonscale mail watch --template '{{.message.id}}\\t{{.message.from}}\\t{{.message.text}}' [--delim <delim> | --delim-null]
pigeonscale mail watch --exec <command> [--max-parallel <n>]

Mark read/unread (cloud only):

pigeonscale mail mark read <id...>
pigeonscale mail mark unread <id...>

Attachments:

pigeonscale mail attach ls <messageId>
pigeonscale mail attach get <messageId> --id <attId>
pigeonscale mail attach get <messageId> --all
pigeonscale mail attach cat <messageId> --id <attId>

Threads

pigeonscale mail threads [--account <email>] [--unread]
pigeonscale mail thread show <threadId> [--account <email>]

Output formatting

Many commands support:

• --format json|jsonl|markdown
• --pretty (JSON only)

Safety config (local)

Restrict inbound senders and outbound recipients:

pigeonscale config set safeSenders "[email protected], [email protected]"
pigeonscale config set safeSendersMode warn   # or block

pigeonscale config set safeRecipients "[email protected], [email protected]"
pigeonscale config set safeRecipientsMode warn  # or block

Cloud account security scan settings

Per-account settings are stored locally and can be synced to the Worker:

pigeonscale mail accounts settings get [email protected]
pigeonscale mail accounts settings get [email protected] --remote
pigeonscale mail accounts settings set [email protected] inboundScanEnabled true
pigeonscale mail accounts settings push [email protected]

Admin CLI (pigeonscalectl)

See packages/ctl.