Skill: dedene/strawpoll-cli (version 1.0.2)

--- name: strawpoll-cli description: > Create and manage StrawPoll polls, meeting polls, and ranking polls from the terminal using the strawpoll CLI. Use when the user wants to create polls, view poll results, schedule meetings with availability, run ranked-choice votes, delete or update polls, or automate StrawPoll workflows in scripts. license: MIT homepage: https://github.com/dedene/strawpoll-cli metadata: author: dedene version: "1.1.0" openclaw: primaryEnv: STRAWPOLL_API_KEY requires: bins: - strawpoll install: - kind: brew tap: dedene/tap formula: strawpoll bins: [strawpoll] - kind: go package: github.com/dedene/strawpoll-cli/cmd/strawpoll bins: [strawpoll] --- # strawpoll-cli Command-line interface for the [StrawPoll API v3](https://strawpoll.com/). Supports three poll types: multiple-choice, meeting (availability), and ranking. ## Installation ```bash # 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](https://strawpoll.com/account/settings). ```bash # 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 ```bash # 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 ```bash # 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) ```bash # 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 ```bash # 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: ```bash # 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 ```bash # 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: ```bash # 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: ```bash # 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 ```bash 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](reference.md) for complete flag reference for all commands. ## Installation ```bash brew install dedene/tap/strawpoll ```

path: reference.md
content: # strawpoll-cli Flag Reference

## Global Flags

Available on all commands:

| Flag | Short | Description |
|------|-------|-------------|
| `--json` | `-j` | Output JSON to stdout |
| `--plain` | | Output plain TSV (for scripting) |
| `--no-color` | | Disable colors |
| `--copy` | | Copy poll URL to clipboard |
| `--open` | | Open poll URL in browser |
| `--version` | | Print version and exit |

## Poll Commands

### `strawpoll poll create [TITLE] [OPTIONS...]`

Both args optional — launches interactive wizard if missing in TTY.

**Voting Rules:**

| Flag | Default | Values |
|------|---------|--------|
| `--dupcheck` | `ip` | `ip`, `session`, `none` |
| `--is-multiple-choice` | `false` | Allow multiple selections |
| `--multiple-choice-min` | | Min selections (requires `--is-multiple-choice`) |
| `--multiple-choice-max` | | Max selections (requires `--is-multiple-choice`) |
| `--allow-other` | `false` | Allow voters to add options |
| `--require-names` | `false` | Require voter names |

**Privacy & Access:**

| Flag | Default | Values |
|------|---------|--------|
| `--is-private` | `false` | Hide from public listings |
| `--results-vis` | `always` | `always`, `after_deadline`, `after_vote`, `hidden` |
| `--hide-participants` | `false` | Hide participant names |
| `--allow-vpn` | `true` | Allow VPN users |
| `--edit-vote-perms` | `admin_voter` | `admin`, `admin_voter`, `voter`, `nobody` |

**Display & Scheduling:**

| Flag | Default | Description |
|------|---------|-------------|
| `--deadline` | | RFC3339 or duration (e.g., `24h`) |
| `--randomize` | `false` | Randomize option order |
| `--allow-comments` | `false` | Allow comments |

### `strawpoll poll get <POLL_ID>`

Accepts poll ID or full URL.

### `strawpoll poll list`

| Flag | Default | Description |
|------|---------|-------------|
| `--limit` | `20` | Polls per page |
| `--page` | `1` | Page number |
| `--type` | `created` | `created`, `participated` |

### `strawpoll poll update <POLL_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--title` | `-t` | New poll title |
| `--add-option` | `-a` | Add option (repeatable) |
| `--remove-option` | `-r` | Remove option by position index (repeatable) |

### `strawpoll poll delete <POLL_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--force` | `-f` | Skip confirmation prompt |

### `strawpoll poll results <POLL_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--participants` | `-p` | Show per-participant breakdown |

### `strawpoll poll reset <POLL_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--force` | `-f` | Skip confirmation prompt |

## Meeting Commands

### `strawpoll meeting create <TITLE>`

Title required. Launches wizard if no dates/ranges provided.

| Flag | Short | Description |
|------|-------|-------------|
| `--date` | `-d` | All-day date `YYYY-MM-DD` (repeatable) |
| `--range` | `-r` | Time range `YYYY-MM-DD HH:MM-HH:MM` (repeatable) |
| `--tz` | | IANA timezone (default: local) |
| `--location` | | Meeting location |
| `--description` | | Poll description |
| `--allow-maybe` | | Allow "if need be" responses (default: `true`) |
| `--no-allow-maybe` | | Disable "if need be" responses |
| `--dupcheck` | | Duplication checking (default: `none`) |
| `--deadline` | | Deadline (RFC3339 or duration) |

### `strawpoll meeting get <MEETING_ID>`

Accepts meeting poll ID or URL.

### `strawpoll meeting list`

| Flag | Default | Description |
|------|---------|-------------|
| `--limit` | `20` | Results per page |
| `--page` | `1` | Page number |

### `strawpoll meeting update <MEETING_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--title` | `-t` | New poll title |
| `--location` | | Meeting location |
| `--add-date` | `-d` | Add all-day date `YYYY-MM-DD` (repeatable) |
| `--add-range` | `-r` | Add time range `YYYY-MM-DD HH:MM-HH:MM` (repeatable) |
| `--tz` | | IANA timezone |

### `strawpoll meeting delete <MEETING_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--force` | `-f` | Skip confirmation prompt |

### `strawpoll meeting results <MEETING_ID>`

Displays participant-by-timeslot availability grid with Yes/No/Maybe and summary totals.

## Ranking Commands

### `strawpoll ranking create <TITLE> <OPTIONS...>`

Both title and options required (no wizard).

| Flag | Default | Description |
|------|---------|-------------|
| `--dupcheck` | `ip` | `ip`, `session`, `none` |
| `--is-private` | `false` | Hide from public listings |
| `--results-vis` | `always` | Results visibility |
| `--deadline` | | Deadline (RFC3339 or duration) |
| `--allow-comments` | `false` | Allow comments |
| `--description` | | Poll description |

### `strawpoll ranking get <RANKING_ID>`

Accepts ranking poll ID or URL.

### `strawpoll ranking list`

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--limit` | `-l` | `20` | Max results per page |
| `--page` | `-p` | `1` | Page number |

### `strawpoll ranking update <RANKING_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--title` | `-t` | New poll title |
| `--add-option` | `-a` | Add option (repeatable) |
| `--remove-option` | `-r` | Remove option by position index (repeatable) |

### `strawpoll ranking delete <RANKING_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--force` | `-f` | Skip confirmation prompt |

### `strawpoll ranking results <RANKING_ID>`

| Flag | Short | Description |
|------|-------|-------------|
| `--verbose` | `-v` | Show per-option position breakdown (Borda count) |

## Auth Commands

### `strawpoll auth set-key`

| Flag | Description |
|------|-------------|
| `--stdin` | Read API key from stdin (for scripts) |

### `strawpoll auth status`

Shows API key status, keyring backend, and config path.

### `strawpoll auth remove`

Deletes stored API key from keyring.

## Config Commands

### `strawpoll config show`

Displays current configuration.

### `strawpoll config set <KEY> <VALUE>`

Valid keys:

| Key | Values |
|-----|--------|
| `keyring_backend` | `auto`, `keychain`, `file` |
| `dupcheck` | `ip`, `session`, `none` |
| `results_visibility` | `always`, `after_deadline`, `after_vote`, `hidden` |
| `is_private` | `true`, `false` |
| `allow_comments` | `true`, `false` |
| `allow_vpn_users` | `true`, `false` |
| `hide_participants` | `true`, `false` |
| `edit_vote_permissions` | `admin`, `admin_voter`, `voter`, `nobody` |

### `strawpoll config path`

Prints config file location (`~/.config/strawpoll/config.yaml`).

## Environment Variables

| Variable | Description |
|----------|-------------|
| `STRAWPOLL_API_KEY` | API key (overrides keyring) |
| `STRAWPOLL_KEYRING_BACKEND` | Keyring backend: `keychain`, `file`, `auto` |
| `STRAWPOLL_KEYRING_PASSWORD` | Password for file-based keyring |
| `NO_COLOR` | Disable colored output |

## Completion Commands

```bash
strawpoll completion bash    # Bash completions
strawpoll completion zsh     # Zsh completions
strawpoll completion fish    # Fish completions
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)