CLI

The PickFu CLI (@pickfu/cli) lets you create surveys, check results, and manage polls directly from your terminal. It supports structured JSON output for automation and CI/CD workflows.

Installation

npm install -g @pickfu/cli

Or run commands directly with npx:

npx @pickfu/cli <command>

Authentication

OAuth (recommended)

pickfu auth login

This opens a browser window for OAuth authorization. Once approved, your credentials are stored locally and refreshed automatically. For headless environments (servers, CI), use the --headless flag to print the authorization URL instead of opening a browser:

pickfu auth login --headless

API key

For non-interactive environments like CI pipelines or automation scripts, use an API key instead of OAuth:

# Via environment variable
export PICKFU_API_KEY=your_api_key
pickfu survey list

# Or via flag (overrides env var and stored OAuth token)
pickfu survey list --token your_api_key

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

Managing credentials

pickfu auth status       # Check authentication status
pickfu auth status --local  # Check without contacting the API
pickfu auth logout       # Clear stored credentials

Commands

All commands support --json for machine-readable output.

Surveys

Create a survey

pickfu survey create

The CLI walks you through poll creation interactively. You can also provide options via flags:

pickfu survey create \
  --name "Logo test" \
  --question "Which logo do you prefer?" \
  --type head_to_head \
  --option "Logo A" \
  --option "Logo B" \
  --sample-size 50 \
  --country US \
  --targeting gender=female

Or create from a JSON file:

pickfu survey create --from-file survey.json

Show JSON file format

{
  "name": "Logo test",
  "country": "US",
  "sample_size": "50",
  "survey_intent": "Determine which logo resonates better with our target audience",
  "questions": [
    {
      "type": "head_to_head",
      "prompt": "Which logo do you prefer for a children's educational app?",
      "context": {
        "text": "We're launching a new learning app for kids aged 5-10"
      },
      "options": [
        { "value": "Logo A — playful, colorful design" },
        { "value": "Logo B — clean, modern design" }
      ]
    }
  ],
  "targeting": ["gender=female", "age=25-34"],
  "reporting": ["gender", "age-range"]
}

Flag	Description
`--from-file`	Path to a JSON file with survey definition
`--name`	Survey name
`--question`	The question text
`--type`	Question type (see supported types)
`--option`	Option text (repeatable — use once per option)
`--sample-size`	Number of respondents
`--country`	Country code (default: US)
`--targeting`	Targeting trait in `key=value` format (repeatable)

Get survey details

pickfu survey get <survey-id>

List surveys

pickfu survey list

Flag	Description	Default
`--status`	Filter by status (`completed`, `in-progress`, `unpublished`, `archived`)	All
`--limit`	Results per page	20
`--page`	Page number	1
`--sort-by`	Sort field (`createdAt`, `name`, `creator`, `status`)	`createdAt`
`--dir`	Sort direction (`asc`, `desc`)	`desc`

Update a draft survey

pickfu survey update <survey-id> --name "Updated name" --sample-size 100

Or update from a JSON file:

pickfu survey update <survey-id> --from-file updated-survey.json

Flag	Description
`--from-file`	Path to JSON file with updates
`--name`	Updated survey name
`--sample-size`	Updated respondent count
`--country`	Updated country code

Publish a survey

Publish a draft survey to start collecting responses:

pickfu survey publish <survey-id>

View responses

Get individual responses with explanations and demographics:

pickfu survey responses <survey-id>

Flag	Description	Default
`--page`	Page number	1
`--limit`	Responses per page	20
`--question-id`	Filter responses by question	All questions

Watch a survey

Block until a survey completes — useful in scripts and CI:

pickfu survey watch <survey-id>

Flag	Description	Default
`--interval`	Polling interval in seconds	30
`--exit-status`	Exit with code 2 if cancelled or archived	false

Targeting and reporting

List available targeting traits

pickfu targeting list --country US

Returns all demographic targeting traits available for the specified country. Use the permalink values as targeting keys in survey create --targeting.

List available reporting demographics

pickfu reporting list --country US

Returns all demographic breakdowns available for survey results.

Schema introspection

View the full input/output schemas for any command — useful for building integrations:

pickfu schema             # List all commands
pickfu schema survey.create  # Detailed schema for a specific command

Generic API access

Make authenticated API requests directly:

pickfu api GET /v1/surveys
pickfu api POST /v1/surveys --body '{"name": "test"}'
pickfu api GET /v1/traits/targeting --query country=US

Supported question types

Type	Description
`head_to_head`	A/B comparison where respondents pick a favorite (2 options)
`ranked`	Respondents rank options in preference order (3-8 options)
`open_ended`	Single-concept poll with written feedback
`click_test`	Heatmap generation from image clicks
`emoji_rating`	Emoji sentiment selection with explanation
`star_rating`	1-5 star rating with feedback
`five_second_test`	Brief timed exposure for first impressions
`screen_recording`	Record user interaction with content
`single_select`	Choose one from multiple options (3-8 options)
`multi_select`	Select multiple answers from options (3-8 options)

Sample sizes

Available respondent counts: 15, 30, 50, 75, 100, 200, 500

Need help?

pickfu --help
pickfu survey --help
pickfu survey create --help

Or contact support@pickfu.com for assistance.

Getting started

Tools

Installation

Authentication

OAuth (recommended)

API key

Managing credentials

Commands

Surveys

Create a survey

Get survey details

List surveys

Update a draft survey

Publish a survey

View responses

Watch a survey

Targeting and reporting

List available targeting traits

List available reporting demographics

Tags

Schema introspection

Generic API access

Supported question types

Sample sizes

Need help?

Getting started

Tools

​Installation

​Authentication

​OAuth (recommended)

​API key

​Managing credentials

​Commands

​Surveys

​Create a survey

​Get survey details

​List surveys

​Update a draft survey

​Publish a survey

​View responses

​Watch a survey

​Targeting and reporting

​List available targeting traits

​List available reporting demographics

​Tags

​Schema introspection

​Generic API access

​Supported question types

​Sample sizes

​Need help?

Installation

Authentication

OAuth (recommended)

API key

Managing credentials

Commands

Surveys

Create a survey

Get survey details

List surveys

Update a draft survey

Publish a survey

View responses

Watch a survey

Targeting and reporting

List available targeting traits

List available reporting demographics

Tags

Schema introspection

Generic API access

Supported question types

Sample sizes

Need help?