CLI reference
The pairpoll command is for people and agents with local file access. The package is not published to npm yet. Until it is, run it from a checkout of the Pairpoll repository. It needs Node.js 22 or newer and nothing else:
alias pairpoll="node /path/to/pairpoll/packages/cli/bin/pairpoll.js"
pairpoll --help
Sign in
export PAIRPOLL_API_URL=https://pairpoll.com
pairpoll login
The CLI uses https://pairpoll.com unless you set another API URL. For a local server, use http://localhost:4321. The command prints a short code and browser URL, waits for approval, then stores the API key in a private config file. On macOS and Linux the default is ~/.config/pairpoll/config.json. On Windows it is in the Pairpoll folder under %APPDATA%.
pairpoll whoami
pairpoll logout
Logout removes the local key. It does not revoke it. Revoke the key in the browser if it should stop working.
Create a poll
pairpoll create ./one.png ./two.png \
--question "Which image is strongest?" \
--top 3 \
--max-voters 50 \
--open
You can pass files, folders or both. A folder adds its direct files in name order. One poll accepts 2 to 16 images or 2 to 16 videos. Do not mix them.
Options:
--top 1|3|5sets the number of ranked places. The default is 3.--play-onceis for videos. Each video must finish once per pair before a voter can choose.--max-voters Naccepts 1 to 200. The default is 50.--openopens voting after upload. Without it, the poll stays a draft.
If ffmpeg is on PATH, the CLI uploads one poster frame for each video.
Manage polls
pairpoll list
pairpoll open <poll-id>
pairpoll close <poll-id>
pairpoll results <poll-id>
pairpoll results <poll-id> --json
pairpoll results <poll-id> --csv
pairpoll delete-voter <poll-id> <voter-id>
pairpoll delete <poll-id>
The voter ID is a run id from pairpoll results <poll-id> --json. Removing a voter deletes their result but does not free their place under the voter limit. Closing and deletion are final.
Agent output and local servers
Add --json to any command for machine-readable output. Login emits one JSON line while waiting and one after approval. Errors use standard error. Usage errors exit with code 2. Other failures exit with code 1.
export PAIRPOLL_API_URL=https://pairpoll.com
export PAIRPOLL_API_KEY=ppk_your_key
pairpoll --json list
--api-url overrides PAIRPOLL_API_URL. PAIRPOLL_API_KEY overrides the saved key.