Skip to main content

​
Install

The CLI command surface is generated from the documented API route metadata. Regenerate the local manifest and endpoint snippets whenever an API reference route changes: 
npx tsx scripts/generate-cli.ts
During local development, run the generated CLI entrypoint directly: 
npx tsx cli/puffle.ts list --help
When packaged, the same generated manifest backs the puffle executable. The package build writes dist/cli/puffle.js and exposes it as the puffle bin: 
npm run build:cli
From an installed package or linked checkout, run the binary directly: 
puffle list --help

​
Authenticate

Set your API key in PUFFLE_API_KEY. 
export PUFFLE_API_KEY="pk_live_..."
The CLI sends the key as a Bearer token to the same API routes shown in the API reference.

​
Usage

puffle <resource> <command> [arguments] [flags]
Commands are derived from API routes. For example, GET /api/lists becomes puffle list, and action routes such as POST /api/campaigns/{id}/launch become puffle campaign launch --id <id>. Path parameters, query parameters, and request body fields become flags unless a route explicitly opts into positional arguments. Use --help on any generated command to see the route summary, required flags, optional flags, and examples from the manifest. Examples: 
puffle list
puffle list --id <list-id>
puffle campaign
puffle campaign launch --id <campaign-id>
puffle lead search create --prompt "founder-led devtools companies in SF" --fetch-count 25
puffle list import --list-id <list-id> --leads '[{"name":"Alex Lee","company":"ExampleCo"}]'
puffle thread message --id <thread-id>

​
Global Flags

FlagDescription
--format jsonPrint the response data as formatted JSON. This is the default.
--format prettyAlias for formatted JSON output.
--format rawPrint the raw JSON response body.
Set PUFFLE_API_BASE_URL to point the CLI at a preview or local server. 
PUFFLE_API_BASE_URL="http://localhost:3000" puffle list

​
Flag Values

String and number flags are passed as shell values. Boolean flags are presence-only, so --include-stats sends true. Array and object request fields are JSON flags. Quote JSON values so the shell passes them as one argument: 
puffle campaign lead add --id <campaign-id> --prospects '[{"email":"alex@example.com","first_name":"Alex","company":"ExampleCo"}]'
If JSON parsing fails, the CLI exits before making a request.

​
API Reference

CLI commands are generated from route metadata and emitted into OpenAPI as CLI metadata. Every endpoint page in the API reference gets a generated CLI: snippet from the same manifest that powers the executable. Session-only, admin-only, UI-only, and private routes do not get public CLI commands.

​
For AI Agents

The CLI is a terminal client for the API contract. Agents should prefer the API reference for request and response schemas, then use the CLI when a shell workflow is more convenient. If an endpoint is removed from the API reference, its generated CLI command should disappear with it. For machine-readable workflows, keep the default --format json output and parse stdout. Request failures are written to stderr and return a non-zero exit code.