strawpoll-cli

Command-line interface for the StrawPoll API v3. Supports three poll types: multiple-choice, meeting (availability), and ranking.

Installation

# Homebrew (macOS/Linux)
brew install dedene/tap/strawpoll

# Or via Go
go install github.com/dedene/strawpoll-cli/cmd/strawpoll@latest

Authentication

An API key is required. Get one at strawpoll.com/account/settings.

# Store in system keyring (interactive prompt)
strawpoll auth set-key

# Or use environment variable (for scripts/CI)
export STRAWPOLL_API_KEY="your-key-here"

# Verify setup
strawpoll auth status

Quick Start

# Create a poll
strawpoll poll create "Favorite language?" Go Rust Python TypeScript

# View poll details (accepts ID or full URL)
strawpoll poll get NPgxkzPqrn2
strawpoll poll get https://strawpoll.com/NPgxkzPqrn2

# View results with vote counts
strawpoll poll results NPgxkzPqrn2

# Delete (with confirmation)
strawpoll poll delete NPgxkzPqrn2

Poll Types

Multiple-Choice Polls

# Basic poll
strawpoll poll create "Best editor?" Vim Emacs "VS Code" Neovim

# With voting rules
strawpoll poll create "Pick up to 3" A B C D E \
  --is-multiple-choice --multiple-choice-max 3 \
  --dupcheck session --deadline 24h

# Private poll, copy URL to clipboard
strawpoll poll create "Team vote" Opt1 Opt2 --is-private --copy

# Open in browser after creation
strawpoll poll create "Quick poll" Yes No --open

# List your polls
strawpoll poll list --limit 10

# Update a poll
strawpoll poll update NPgxkzPqrn2 --title "New title" --add-option "New option"

# Reset votes (with confirmation)
strawpoll poll reset NPgxkzPqrn2

Meeting Polls (Availability)

# With all-day dates
strawpoll meeting create "Team standup" \
  -d 2025-03-10 -d 2025-03-11 -d 2025-03-12

# With time ranges
strawpoll meeting create "1:1 meeting" \
  -r "2025-03-10 09:00-10:00" \
  -r "2025-03-10 14:00-15:00" \
  --tz "America/New_York" --location "Room 4B"

# Interactive wizard (no dates = launches wizard)
strawpoll meeting create "Sprint planning"

# View availability grid
strawpoll meeting results xYz123abc

# List meeting polls
strawpoll meeting list

Ranking Polls

# Create ranking poll
strawpoll ranking create "Rank these frameworks" React Vue Svelte Angular Solid

# View Borda count results
strawpoll ranking results rAnK456

# Verbose: per-position breakdown
strawpoll ranking results rAnK456 --verbose

# List ranking polls
strawpoll ranking list

Output Formats

All commands support three output modes:

# Default: colored table (human-readable)
strawpoll poll results NPgxkzPqrn2

# JSON: structured output for scripting
strawpoll poll results NPgxkzPqrn2 --json

# Plain: tab-separated values
strawpoll poll results NPgxkzPqrn2 --plain

# Disable colors (also respects NO_COLOR env var)
strawpoll poll results NPgxkzPqrn2 --no-color

Scripting Examples

# Get poll ID from creation
POLL_ID=$(strawpoll poll create "Vote" A B --json | jq -r '.id')

# Pipe results
strawpoll poll results "$POLL_ID" --plain | cut -f1,3

# Delete without confirmation
strawpoll poll delete "$POLL_ID" --force

# Results with participant breakdown
strawpoll poll results "$POLL_ID" --participants --json

Configuration Defaults

Save preferred settings to avoid repetitive flags:

# Set defaults
strawpoll config set dupcheck session
strawpoll config set results_visibility after_vote
strawpoll config set is_private true

# View config
strawpoll config show

# Config file location
strawpoll config path

Config stored at ~/.config/strawpoll/config.yaml.

Interactive Mode

Create commands launch an interactive wizard when run in a terminal without arguments:

# Launches wizard (poll title, options, settings)
strawpoll poll create

# Launches meeting wizard (dates, times, location)
strawpoll meeting create "Team sync"

Wizards render on stderr; data output goes to stdout. In non-TTY (pipes), provide all arguments via flags.

Important Notes

• Poll options: minimum 2, maximum 30
• Poll IDs: accepts bare IDs or full URLs (with/without https://, www., /polls/)
• Deadlines: RFC3339 (2025-03-15T18:00:00Z) or duration (24h, 1h30m)
• Meeting dates: YYYY-MM-DD for all-day, YYYY-MM-DD HH:MM-HH:MM for time ranges
• Timezones: IANA format (e.g., Europe/Berlin, America/New_York)
• No voting endpoint — voting is browser-only via the poll URL

Shell Completions

strawpoll completion bash > /etc/bash_completion.d/strawpoll
strawpoll completion zsh > "${fpath[1]}/_strawpoll"
strawpoll completion fish > ~/.config/fish/completions/strawpoll.fish

See reference.md for complete flag reference for all commands.

Installation

brew install dedene/tap/strawpoll