npm package: @pickfu/cli
Description: PickFu CLI — create surveys, check results, and manage your account from the terminal
Author: PickFu
Latest version: 0.6.1

# PickFu CLI

A command-line interface for the [PickFu](https://www.pickfu.com) 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

```bash
npm install -g @pickfu/cli
```

Or run without installing:

```bash
npx @pickfu/cli@latest survey list
```

Requires Node.js 20+.

## Authentication

### Interactive (browser-based OAuth)

```bash
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):

```bash
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:

```bash
export PICKFU_API_KEY=sk_...
pickfu survey list
```

Or pass it per-command:

```bash
pickfu survey list --token sk_...
```

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

## Commands

### Auth

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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:

```bash
pickfu survey list --json
pickfu survey get abc123 --json
```

## Agent workflow

The key pattern for AI agents:

```bash
# 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

```bash
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](https://oclif.io) 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