PickFu CLI

A command-line interface for the PickFu consumer research platform. Create surveys, check results, and manage your account from the terminal.

Why a CLI?

PickFu's CLI is built for two audiences:

1. AI agents — the primary consumer. Agents use the CLI to run PickFu surveys autonomously. The CLI is designed to be agent-friendly: structured --json output, actionable error messages, non-interactive by default, and efficient polling via survey watch that blocks at the process level so agents don't burn tokens sleeping.

2. Developers — power users who want quick access to surveys, results, and account management without opening a browser.

The CLI, MCP server, and web app all consume the same PickFu API. The CLI is a thin client — all business logic lives in the API.

Install

brew install pickfu/tap/pickfu

Or use other methods:

curl -fsSL https://agents.pickfu.com/install.sh | bash   # macOS/Linux binary
npm install -g @pickfu/cli                                 # npm (requires Node.js 20+)
npx @pickfu/cli@latest survey list                         # zero-install via npx

Authentication

Interactive (browser-based OAuth)

pickfu auth login

Opens your browser for OAuth consent via WorkOS Connect. Tokens are stored in ~/.config/pickfu/config.json.

Non-interactive (API key)

Store a key via stdin (never appears in shell history):

echo "sk_..." | pickfu auth set-key    # piped
pbpaste | pickfu auth set-key          # from clipboard (macOS)
pickfu auth set-key                    # interactive prompt

Or use an environment variable:

export PICKFU_API_KEY=sk_...
pickfu survey list

Or pass it per-command:

pickfu survey list --token sk_...

Token precedence: --token flag > PICKFU_API_KEY env > stored OAuth token > stored API key.

Commands

Auth

pickfu auth login              # OAuth login (opens browser)
pickfu auth login --headless   # Print URL instead of opening browser
pickfu auth set-key            # Store an API key from stdin
pickfu auth logout             # Clear stored credentials
pickfu auth status             # Show auth method, email, token expiry

Surveys

pickfu survey list                              # List surveys
pickfu survey list --status completed --limit 5 # Filter and paginate
pickfu survey get <id>                          # Survey details
pickfu survey create --from-file survey.json    # Create from JSON file
pickfu survey update <id> --name "New Name"     # Update a draft
pickfu survey update <id> --from-file patch.json
pickfu survey publish <id>                      # Publish (charges account)
pickfu survey responses <id>                    # View responses
pickfu survey watch <id>                        # Block until complete

Targeting & Reporting

pickfu targeting list                          # List targeting options (US default)
pickfu targeting list --country GB             # List for specific country
pickfu reporting list                          # List reporting demographics
pickfu reporting list --country GB --json      # Machine-readable

Tags

pickfu tag list                                # List tags
pickfu tag list --query "beta"                 # Search by name
pickfu tag create "Beta Features"              # Create a tag
pickfu tag create "Beta Features" --json       # Machine-readable

Schema (for AI agents)

pickfu schema                  # List all commands with input/output schemas
pickfu schema survey get       # Single command detail

Returns structured JSON describing every command's flags, args, and JSON response shapes. Agents use this for runtime introspection instead of parsing --help text.

Generic API

pickfu api GET /v1/surveys                     # Any API endpoint
pickfu api POST /v1/surveys --body '{"name":"Test"}'

JSON output

Every command supports --json for machine-readable output:

pickfu survey list --json
pickfu survey get abc123 --json

Agent workflow

The key pattern for AI agents:

# Create and publish a survey
SURVEY_ID=$(pickfu survey create --from-file survey.json --json | jq -r '.id')
pickfu survey publish $SURVEY_ID

# Block until complete — agent's LLM is NOT called while this runs
pickfu survey watch $SURVEY_ID --json

# Agent wakes up here with results on stdout

survey watch is a process-level block. The CLI sleeps between polls (default 30s). The agent's LLM isn't invoked during this time — zero token cost for waiting.

Development

npm install              # Install dependencies
npm run build            # Compile TypeScript
npm test                 # Run tests (vitest)
./bin/dev.js survey list # Run without building (uses tsx)

Architecture

| Component | Technology | |-----------|-----------| | CLI framework | oclif v4 (ESM) | | HTTP client | Native fetch() | | Auth | PKCE via WorkOS Connect | | Config | ~/.config/pickfu/config.json (XDG) | | Test runner | vitest | | API host | https://api.pickfu.com |

License

MIT