Command Reference

Global Flags

Flag	Short	Default	Description
--api-url		$SQUAWK_API_URL or https://api.squawkpipe.ai/v1	Override the API base URL
--tenant		$SQUAWK_TENANT_ID	Tenant ID
--output	-o	json	Output format: json, pretty
--verbose	-v	false	Enable debug logging to stderr
--version			Print version and exit
--help	-h		Show help

Environment Variables

Variable	Description
SQUAWK_API_URL	API base URL (overridden by --api-url)
SQUAWK_TENANT_ID	Tenant ID (overridden by --tenant)
SQUAWK_API_KEY	API key for agent or CI/CD auth
FIREBASE_API_KEY	Firebase project API key (required for squawk login)
FIREBASE_CLIENT_ID	Firebase OAuth 2.0 client ID (required for squawk login)

Exit Codes

Code	Meaning
0	Success
1	General error (network, API error, invalid args)
2	Authentication error (not logged in, token expired)

---

squawk login

Authenticate with Squawkpipe via browser using Firebase Auth (PKCE flow).

squawk login

Opens the default browser. Credentials are stored in the OS keychain. No flags.

Example output (stderr):

🔐 Starting authentication...
Opening browser for authentication...
✅ Authentication successful! Credentials saved to keychain.

---

squawk logout

Remove all stored credentials from the OS keychain.

squawk logout

No flags.

---

squawk api-key

Interactively set an API key for agent or CI/CD authentication.

squawk api-key [--tenant <id>]

Prompts for the key with hidden input, validates it against the API, then stores it in the OS keychain.

Example:

squawk api-key --tenant acme-corp
Enter API key: (hidden)
🔍 Validating API key...
✅ API key validated and saved to keychain.

---

squawk listen

Watch for new conversation activity in real-time.

squawk listen [flags]

Flags:

Flag	Default	Description
--json	false	Output JSONL to stdout (AI-pipe mode)
--claude		Auto-reply using Claude with a custom prompt
--status	active	Conversation status filter: active, paused, killed
--interval	5s	Base polling interval

Interactive TUI (default):

╭─────────────────────────────────────────────────╮
│ ⠋ squawk listen                                  │
│                                                   │
│  Last checked: 3s ago   Polling every: 5s         │
│                                                   │
│  Recent activity:                                 │
│  ● WhatsApp  Sarah Chen (2 new)                   │
│    Hi, I need to change my delivery address       │
│  ● Email  James Wilson (1 new)                    │
│    Re: Order #12345 — refund question             │
│                                                   │
│  Press q to quit                                  │
╰─────────────────────────────────────────────────╯

Press q to quit.

JSONL mode (--json):

Each new conversation is emitted as a single JSON object on stdout. Status/log messages go to stderr.

squawk listen --json

{"id":"conv_abc123","channel":"whatsapp","contactName":"Sarah Chen","status":"active","unrespondedCount":2}
{"id":"conv_def456","channel":"email","contactName":"James Wilson","status":"active","unrespondedCount":1}

Claude mode (--claude):

Automatically replies to each new conversation using Claude with a custom prompt.

squawk listen --claude "You are a friendly support agent. Reply professionally and warmly."

Polling behaviour:

• Starts at 5-second intervals
• Doubles the interval (up to 5 minutes) when nothing new is found
• Resets to 5 seconds immediately when new activity arrives
• Runs until Ctrl+C

---

squawk conversation <id>

Get the full context of a conversation: metadata, contact details, and message history.

squawk conversation <id> [--output json|pretty] [--tenant <id>]

JSON output (default):

squawk conversation conv_abc123

{
  "conversation": { "id": "conv_abc123", "channel": "whatsapp", "contactName": "Sarah Chen", "status": "active" },
  "contact": { "contactId": "...", "phone": "+447700900123", "fullName": "Sarah Chen" },
  "messages": [
    { "id": "msg_1", "senderType": "contact", "senderName": "Sarah Chen", "body": "Hi, I need help", "createdAt": "2026-04-05T14:30:00Z" }
  ]
}

Pretty output:

squawk conversation conv_abc123 -o pretty

━━━ Conversation conv_abc123 ━━━━━━━━━━━━━━━━━━━━━━

  Channel:     WhatsApp
  Contact:     Sarah Chen (+447700900123)
  Status:      ACTIVE
  Unresponded: 2 message(s)

━━━ Messages ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  [14:30] Sarah Chen:
    Hi, I need to change my delivery address

  [14:30] Agent:
    Of course! What's your order number?

---

squawk reply <id>

Send a reply to a conversation.

squawk reply <id> [--body "..."] [--tenant <id>]

Via flag:

squawk reply conv_abc123 --body "Your order has been shipped!"

Via stdin:

echo "Your order has been shipped!" | squawk reply conv_abc123

Output (stdout):

{"id":"msg_xyz789","body":"Your order has been shipped!","createdAt":"2026-04-05T14:35:00Z"}

Error — conversation paused or killed (HTTP 409):

Error: conversation is paused or closed — cannot send message

---

squawk link

Route each new conversation to an external agent script.

squawk link --agent ./my-agent.sh --pipe email

Flags:

Flag	Description
--agent	Path to agent script
--pipe	Channel filter: email, whatsapp (repeatable)

The agent script receives full conversation JSON on stdin and can call any squawk commands.

Run concurrent agents for multiple channels:

squawk link --agent ./email-agent.sh --pipe email &
squawk link --agent ./whatsapp-agent.sh --pipe whatsapp &