@heyamiko/amiko-cli 0.17.2 → 0.18.0

package/README.md

@@ -371,6 +371,29 @@ amiko chat lists delete "Focus" --yes            # the conversations themselves
 - The server stores a list as a plain conversation-id array and `PATCH` replaces it wholesale, so `add`/`remove` read-modify-write the full array — existing entries always survive an `add`, and one unresolvable `--conversation` aborts the whole command before anything is written.
 - Lists are private, but mutations still take the `--yes` gate in non-interactive shells (they reshape your chat sidebar on every device). The bare listing is an ungated read; `--raw` prints JSON everywhere.
 
+### Polls
+
+Create and answer **chat polls** as the owner via `amiko chat poll` — the same polls as the app's chat (single or multiple answers, anonymous voting, quizzes).
+
+```bash
+amiko chat poll create "Trip planning" "Where to?" --option Beach --option Mountains --option City --yes
+amiko chat poll create @sophie "Lunch?" --option Tacos --option Sushi --multiple --anonymous --yes
+amiko chat poll create "Trip planning" "Capital of France?" --option Lyon --option Paris --quiz --correct 2 --explanation "Since 987" --yes
+amiko chat poll show <messageId>                 # options, tallies, voters, your vote (id from `chat read`)
+amiko chat poll vote <messageId> 2 --yes         # by option number…
+amiko chat poll vote <messageId> Beach City --yes  # …or text / option id; multi-answer polls take several
+amiko chat poll retract <messageId> --yes        # take your vote back
+amiko chat poll close <messageId> --yes          # end your poll — permanent
+```
+
+- A poll is a chat message: `chat read` shows it as `📊 <question>` followed by its options, tallies and a `●` on your own choices, and its message **id** is what `show`/`vote`/`retract`/`close` take.
+- **`vote` sets your answer to exactly the choices given**, replacing any earlier vote (like tapping in the app). A single-answer poll takes one choice. Choices are the option's number (as `show` prints it), its text (case-insensitive), or its id.
+- **Quizzes** have one correct answer (`--correct <n>`, 1-based). Results and the answer stay hidden until you answer, a quiz answer is final (no changing or retracting it), and you can't answer your own quiz. `--explanation` shows with the answer once it's revealed.
+- **Anonymous** polls show counts only — nobody (the creator included) sees who voted for what. Otherwise `show` lists voter names.
+- Only the poll's **creator** can `close` it. Closing is permanent: votes stop, results stay, and a quiz's answer is revealed to everyone.
+- Polls work in **DMs and group chats with at least two people** — not in channels, support chats, or your chat with your twin. Limits: question ≤300 chars, 2–12 unique options ≤100 chars each, explanation ≤200 chars (checked before anything is sent).
+- `create`, `vote` and `retract` are outward (the chat sees them) and `close` is irreversible, so all are **gated on `--yes`** in non-interactive shells. `show` is an ungated read; `--raw` prints JSON everywhere.
+
 ## Twin Cards
 
 Generate, view, download, and mint your **Twin Card** (template `twins_take`, flavors **work / play / love**).
@@ -987,6 +1010,7 @@ Your conversations (DMs + group chats) as the owner — list, read, send, manage
 | `chat gifs` | Search Klipy GIFs (trending when no query) — pass a result URL to `amiko chat send --gif` |
 | `chat group` | Group chats — create, list, info, rename, add/remove members, @all permission, leave |
 | `chat lists` | Your chat lists (private folders of conversations) — run bare to see them; create, rename, add/remove conversations, delete |
+| `chat poll` | Chat polls — create, show, vote, retract your vote, close (as the owner) |
 
 #### `amiko chat list`
 
@@ -1249,6 +1273,60 @@ Delete a chat list (the conversations in it are untouched)
 | `--yes` |  | Skip the confirmation (required in non-interactive shells) |
 | `--raw` |  | Output raw JSON |
 
+#### `amiko chat poll`
+
+Chat polls — create, show, vote, retract your vote, close (as the owner)
+
+##### `amiko chat poll create <target> <question>`
+
+Post a poll as yourself (the owner) to a DM or group chat (conversation id, user id, @handle, or name — DMs are opened automatically). Pass 2-12 answers with --option.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--option <text>` |  | An answer option — repeat for each (2-12, in order, unique) |
+| `--multiple` |  | Let people pick more than one answer |
+| `--anonymous` |  | Hide who voted for what (everyone sees counts only) |
+| `--quiz` |  | Quiz mode: one correct answer, revealed to each person once they answer |
+| `--correct <n>` |  | Quiz only: the number of the correct option (1-based) |
+| `--explanation <text>` |  | Quiz only: shown with the answer once it's revealed (≤200 characters) |
+| `--yes` |  | Skip the confirmation (required in non-interactive shells) |
+| `--raw` |  | Output raw JSON |
+
+##### `amiko chat poll show <messageId>`
+
+Show a poll's options, results, voters and your own vote (the poll's message id, from `amiko chat read`)
+
+| Flag | Default | Description |
+|---|---|---|
+| `--raw` |  | Output raw JSON |
+
+##### `amiko chat poll vote <messageId> <choices>`
+
+Vote as yourself (the owner). Sets your answer to exactly these options — each by number (as in `chat poll show`), text, or option id — replacing any earlier vote.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--yes` |  | Skip the confirmation (required in non-interactive shells) |
+| `--raw` |  | Output raw JSON |
+
+##### `amiko chat poll retract <messageId>`
+
+Take back your vote on a poll (quiz answers can't be retracted)
+
+| Flag | Default | Description |
+|---|---|---|
+| `--yes` |  | Skip the confirmation (required in non-interactive shells) |
+| `--raw` |  | Output raw JSON |
+
+##### `amiko chat poll close <messageId>`
+
+End a poll you created — no one can vote afterwards and it can't be reopened
+
+| Flag | Default | Description |
+|---|---|---|
+| `--yes` |  | Skip the confirmation (required in non-interactive shells) |
+| `--raw` |  | Output raw JSON |
+
 ### `amiko card`
 
 Twin Cards (work/play/love) — generate, view, download, mint