npm package: @squawkpipe/cli
Description: Squawk CLI for the Squawk conversation platform
Author: Dental Dash
Latest version: 1.1.3

# Squawkpipe

## The Control Plane for Agentic Conversations

**Squawkpipe** is the guardian layer for the autonomous era. It provides the essential "Human-in-the-Loop" (HITL) infrastructure required to monitor, intercept and govern AI-to-human communications in real-time.

The Squawkpipe CLI is a developer-first tool designed to pipe conversation data into any agentic workflow, allowing you to build human-in-the-loop guardrails or deploy reactive AI agents with full oversight.

## Core Use Cases

- **Agentic Responding:** Link your AI agents directly to conversation pipes to enable real-time, autonomous customer interaction under human supervision.

- **Realtime Guardrails:** Pipe live streams into auditing agents to detect hallucinations, PII leaks, or policy violations before they reach the end user.

- **Structured Routing:** Transform unstructured conversation data into structured payloads for downstream agents, webhooks or internal analysis tools.

## Quick Start

```bash
# Install the CLI
npm install -g @squawkpipe/cli

# Initialize configuration (one-time setup with API key)
squawk init

# Authenticate (alternative to using API key)
squawk login

# Link an agent to a specific conversation pipe
squawk link --agent ./my-agent-script.js --pipe channel-id

# Watch for new activity
squawk listen

# Get a conversation (JSON, for piping)
squawk conversation conv_abc123

# Send a reply
squawk reply conv_abc123 --body "Your order has been shipped!"
```

## Installation

### Via npm

```bash
npm install -g @squawkpipe/cli
squawk --version
```

### uninstall via npm

```bash
npm unisntall -g @squawkpipe/cli

```

## Configuration

Configuration is stored in `~/.squawkrc` (all platforms, including Windows).

**Set up configuration:**

```bash
squawk init
```

This prompts you for:
- **API Key**
- **Tenant ID** (optional, can be set per-command)

**Manual editing:**

Edit `~/.squawkrc` directly (JSON format):

```json
{
  "tenant_id": "your-tenant-id"
}
```

**Config precedence** (highest to lowest):
1. Command flags: `squawk listen --tenant my-tenant`
2. Environment variables: `SQUAWKPIPE_TENANT_ID=my-tenant`
3. Config file: `~/.squawkrc`

---

## Commands

| Command | Description |
|---------|-------------|
| `squawk init` | Set up configuration interactively |
| `squawk login` | Authenticate via browser (Firebase PKCE) |
| `squawk logout` | Remove stored credentials |
| `squawk api-key` | Store an API key for agent/CI use |
| `squawk listen` | Interactive TUI — watch for new activity |
| `squawk listen --json` | JSONL stream to stdout (AI-pipe mode) |
| `squawk listen --claude <prompt>` | Auto-reply using Claude with a custom prompt |
| `squawk conversation <id>` | Get full message history as JSON |
| `squawk reply <id> --body "..."` | Send a reply |

## AI Integration

```bash
# Auto-reply using Claude with a custom prompt
squawk listen --claude "You are a friendly dental receptionist. Reply to conversations in a professional but warm tone."

# Log everything to a file
squawk listen --claude "Reply professionally to customer inquiries" | tee replies.log

# Manual pipeline — watch for conversations and auto-respond
squawk listen --json | while read -r line; do
  echo "$line" | claude -p "Draft a helpful reply for this conversation"
done

# Read context and generate + send a reply in one pipeline
squawk conversation conv_abc123 \
  | claude --prompt "Draft a concise, helpful reply" \
  | squawk reply conv_abc123
```

## Environment Variables

| Variable             | Description |
|----------------------|-------------|
| `SQUAWK_API_URL`     | Override the API base URL |
| `SQUAWK_TENANT_ID`   | Set the tenant ID |
| `FIREBASE_API_KEY`   | Firebase project API key (for login) |
| `FIREBASE_CLIENT_ID` | Firebase OAuth client ID (for login) |

---

## Development

### Prerequisites

- Go 1.22+
- `make` (for cross-platform builds)

### Building

**Local build:**

```bash
cd cli
go build -o squawk .
./squawk --version
```

**Cross-platform builds:**

```bash
cd cli
make build-all
# Outputs:
# build/squawk-darwin-amd64
# build/squawk-darwin-arm64
# build/squawk-linux-amd64
# build/squawk-windows-amd64.exe
```

**Install locally:**

```bash
cd cli
make install
# Installs to /usr/local/bin/squawk
```

### Releasing

1. **Bump the version** — the version is auto-injected via git tags using `git describe --tags`

2. **Create and push a release tag:**

   ```bash
   git tag cli-v1.0.0
   git push origin cli-v1.0.0
   ```

3. **GitHub Actions will:**
   - Run tests
   - Build all platforms (`.github/workflows/build-cli.yml`)
   - Create a GitHub Release with binaries attached
   - Keep artifacts for 30 days

To see the release: https://github.com/dental-dash/squawk/releases

---

## Documentation

See [`docs/cli/`](../docs/cli/) for full documentation:

- [Authentication guide](../docs/cli/authentication.md)
- [Command reference](../docs/cli/commands.md)
- [AI integration patterns](../docs/cli/ai-integration.md)
- [Troubleshooting](../docs/cli/troubleshooting.md)