pp-bird

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/social-and-messaging/bird/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Bird — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `bird-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install bird --cli-only
   ```
2. Verify: `bird-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/bird/cmd/bird-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for bird-pp-cli when an AI agent or operator needs to interact with a Bird workspace from a terminal: sending one-off transactional SMS, batching reminders with reconcile, triaging open conversations, auditing message delivery, or maintaining the workspace allow/block list. Prefer this over raw curl when you want offline search, agent-shaped JSON, or a single command that folds multiple Bird endpoints into one answer.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds
- **`messages audit`** — Fold a message and its interactions into a chronological delivery timeline; exit non-zero on terminal failure.

  _Use this when an agent needs a one-shot answer to 'did this SMS land?' with a non-zero exit on failure for pipeline gating._

  ```bash
  bird-pp-cli messages audit msg_123 --json
  ```
- **`messages failures`** — Aggregate recent message-interaction failures grouped by reason code.

  _Reach for this before paging humans about an SMS outage — it tells you whether the failures are clustered (one bad number, one carrier) or spread._

  ```bash
  bird-pp-cli messages failures --since 24h --group-by reason --json
  ```
- **`sms search`** — Full-text search over message bodies, optionally filtered by sender or recipient phone number.

  _Use when an agent needs to find a specific outbound SMS without scrolling pages of console output._

  ```bash
  bird-pp-cli sms search "order confirmation" --to +31612345678 --json
  ```

### Send + reconcile
- **`sms send-batch`** — Send a batch of SMS messages from a CSV with per-row idempotency keys, persisting the batch in the local store for later reconcile.

  _Use this for any batch larger than a handful of recipients where you need to know which ones failed afterward._

  ```bash
  bird-pp-cli sms send-batch --csv recipients.csv --body-template "Hi {{name}}, your code is {{code}}" --dry-run
  ```
- **`sms reconcile`** — Re-fetch delivery interactions for every message in a batch, group failures by reason, and optionally retry.

  _Reach for this after every send-batch run — it answers 'how many landed?' and gives you a retry plan in one shot._

  ```bash
  bird-pp-cli sms reconcile batch_2026_05_10_a --retry-failed --json
  ```

### Triage and reach
- **`conversations timeline`** — Render a conversation's messages, participants, and delivery interactions in canonical chronological order.

  _Use when triaging a customer thread — one command shows the full back-and-forth plus per-outbound delivery state._

  ```bash
  bird-pp-cli conversations timeline conv_42 --json
  ```
- **`messages from`** — List every message exchanged with one phone number across all conversations.

  _Use when an agent needs the complete back-and-forth with one customer regardless of which conversation it lived in._

  ```bash
  bird-pp-cli messages from +31612345678 --json
  ```

### Compliance and onboarding
- **`tenant doctor`** — Run an SMS-tenant readiness checklist across channels, channel-config, anti-spam, compliance keywords, and messageability with a single exit code.

  _Use during onboarding for a new workspace or when an existing tenant's outbound SMS suddenly drops to zero._

  ```bash
  bird-pp-cli tenant doctor --test-contact contact_42 --json
  ```
- **`compliance auto-block`** — Scan local inbound messages for STOP-keyword fires within a time window; emit a CSV ready for bulk-add (or apply directly).

  _Use weekly to keep the workspace block list synchronized with customer opt-outs without writing a Python script._

  ```bash
  bird-pp-cli compliance auto-block --since 7d --json
  ```

## Command Reference

**channel-config** — Per-channel Conversations API configuration

- `bird-pp-cli channel-config get` — Get the Conversations configuration for a channel
- `bird-pp-cli channel-config update` — Update Conversations configuration for a channel

**channel-media** — Channel-specific pre-signed media uploads

- `bird-pp-cli channel-media <channel_id>` — Create a channel-scoped pre-signed media upload URL

**channels** — SMS channels available in the workspace

- `bird-pp-cli channels get` — Get one channel by ID
- `bird-pp-cli channels list` — List channels in the workspace (filter --kind sms)
- `bird-pp-cli channels messageability` — Check whether a channel can message a given contact (the customer-service window probe)

**compliance** — Channel compliance keyword routing (HELP/STOP/START)


**conversations** — Manage Bird conversation threads (cross-channel customer interactions)

- `bird-pp-cli conversations create` — Start a new conversation
- `bird-pp-cli conversations delete` — Delete a conversation
- `bird-pp-cli conversations get` — Get one conversation by ID
- `bird-pp-cli conversations list` — List conversations across the workspace
- `bird-pp-cli conversations update` — Update a conversation (status, name, etc.)

**media** — Pre-signed media uploads for messages with attachments

- `bird-pp-cli media` — Create a workspace-wide pre-signed media upload URL

**messages** — Channel-level messages (the SMS send/receive layer)

- `bird-pp-cli messages get` — Get one message by ID
- `bird-pp-cli messages interactions` — List delivery-event interactions for a message (sent, delivered, read, failed)
- `bird-pp-cli messages list` — List messages on a channel (chronological)
- `bird-pp-cli messages list-all` — List messages across the workspace

**participants** — Workspace-wide participant lookup

- `bird-pp-cli participants conversations` — List conversations a participant belongs to (by participant ID)
- `bird-pp-cli participants conversations-by-identifier` — List conversations a participant belongs to (by identifier key and value)

**sms** — Programmable SMS send (the headline command)

- `bird-pp-cli sms` — Send an SMS message

**workspace** — Workspace-level configuration: anti-spam and allow/block rules



### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
bird-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Recipes


### Bulk-send an OTP campaign with reconcile

```bash
bird-pp-cli sms send-batch --csv recipients.csv --body-template "Your code is {{code}}" --apply --json
```

Sends one SMS per