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 Homebrew
macOS / Linux
Windows
npx (zero-install)
npm (global)
brew install pickfu/tap/pickfu
Platform Architecture Install method macOS Apple Silicon (arm64) Homebrew, curl, npx, npm macOS Intel (x64) Homebrew, curl, npx, npm Linux x64 curl, npx, npm Linux arm64 curl, npx, npm Windows x64 PowerShell, npx, npm
The curl/PowerShell installers download a standalone binary — no Node.js required. The npx method requires Node.js 20+ but needs no installation.
Authentication OAuth (recommended) Log in through the browser to connect the CLI to your PickFu account:
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:
# Interactive prompt (key never appears in shell history) pickfu auth set-key # Or pipe from clipboard (macOS) pbpaste | pickfu auth set-key # Or use an environment variable (for CI/automation) export PICKFU_API_KEY = sk_ ... pickfu survey list # Or pass per-command via flag pickfu survey list --token sk_...
Avoid echo "sk_..." | pickfu auth set-key — the key appears in shell history. Use the interactive prompt or pipe from clipboard instead.
Token precedence: --token flag > PICKFU_API_KEY env var > stored OAuth token > stored API key.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 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
{ "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-filePath to a JSON file with survey definition --nameSurvey name --questionThe question text --typeQuestion type (see supported types ) --optionOption text (repeatable — use once per option) --sample-sizeNumber of respondents --countryCountry code (default: US) --targetingTargeting trait in key=value format (repeatable)
Get survey details pickfu survey get < survey-i d >
List surveys Flag Description Default --statusFilter by status (completed, in-progress, unpublished, archived) All --limitResults per page 20 --pagePage number 1 --sort-bySort field (createdAt, name, creator, status) createdAt--dirSort direction (asc, desc) desc
Update a draft survey pickfu survey update < survey-i d > --name "Updated name" --sample-size 100
Or update from a JSON file:
pickfu survey update < survey-i d > --from-file updated-survey.json
Flag Description --from-filePath to JSON file with updates --nameUpdated survey name --sample-sizeUpdated respondent count --countryUpdated country code
Publish a survey Publish a draft survey to start collecting responses:
pickfu survey publish < survey-i d >
View responses Get individual responses with explanations and demographics:
pickfu survey responses < survey-i d >
Flag Description Default --pagePage number 1 --limitResponses per page 20 --question-idFilter responses by question All questions
Watch a survey Block until a survey completes — useful in scripts and CI:
pickfu survey watch < survey-i d >
Flag Description Default --intervalPolling interval in seconds 30 --exit-statusExit 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.
pickfu tag list # List your tags pickfu tag list --query "amazon" # Search tags pickfu tag create "Q2 testing" # Create a new tag
Generate an image Generate an image from a text prompt and get a CDN URL:
pickfu media generate --prompt "A playful logo for a kids app" pickfu media generate --prompt "Product banner" --aspect-ratio 16:9
Flag Description Default --promptText prompt describing the image (required) --aspect-ratioAspect ratio (1:1, 16:9, 9:16, 3:2, 2:3, etc.) 1:1
Upload an image or video to the PickFu CDN from a URL or local file:
pickfu media upload --url https://example.com/image.png pickfu media upload --file ./logo.png pickfu media upload --file ./demo.mp4 --resource-type video
Flag Description --urlURL of the media to upload (mutually exclusive with --file) --filePath to a local file to upload (mutually exclusive with --url) --filenameDisplay name hint for the uploaded media --resource-typeimage or video (auto-detected if omitted)
YouTube, Vimeo, and Wistia URLs are returned as-is since PickFu embeds them natively.
Projects pickfu project list # List projects pickfu project create --name "Q2 Research" # Create a project pickfu project get < project-i d > # Get project details pickfu project update < project-i d > --name "Updated name"
Flag Description --nameProject name --descriptionProject description --bookmarkBookmark the project --archiveArchive the project
Playbooks Browse step-by-step research guides:
pickfu playbook list # List available playbooks pickfu playbook get < slu g > # Get full playbook with instructions
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_headA/B comparison where respondents pick a favorite (2 options) rankedRespondents rank options in preference order (3-8 options) open_endedSingle-concept poll with written feedback click_testHeatmap generation from image clicks emoji_ratingEmoji sentiment selection with explanation star_rating1-5 star rating with feedback five_second_testBrief timed exposure for first impressions screen_recordingRecord user interaction with content single_selectChoose one from multiple options (3-8 options) multi_selectSelect multiple answers from options (3-8 options)
Sample sizes Available respondent counts: 15 , 30 , 50 , 75 , 100 , 200 , 300 , 500
Need help? pickfu --help pickfu survey --help pickfu survey create --help
Or contact support@pickfu.com for assistance. 