@heyamiko/amiko-cli 0.17.1 → 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**).
@@ -653,14 +676,16 @@ amiko feed                              # friends feed (default)
 amiko feed --type all --limit 20        # the "All" tab (a.k.a. for_you)
 amiko feed --type following             # posts from accounts you follow
 amiko feed --type media --kind image    # site-wide public media (hits /api/media/feed)
-amiko post create --content "hello from the CLI"           # public post — prints the canonical share URL (post_url in --json); share that verbatim, never hand-build one from the id
+amiko post create --content "hello from the CLI"           # saves a DRAFT by default (owner-only) — preview with `amiko post show <id>`, then `amiko post publish <id>`
+amiko post create --content "ship it" --publish            # create AND publish in one step — prints the canonical share URL (post_url in --json); share that verbatim, never hand-build one from the id
 amiko post create --title "Kyoto, 6am" --media ./shot.webp # image-only note — --content is optional when media/docs are attached
 amiko post create --title "Q3 report" --doc ./q3.pdf       # document note — rendered as a file card
 amiko post create --content "private note" --visibility private
 amiko post create --content "look" --media https://...jpg
 amiko post create --title "the track" --media drive:<docId>  # media already in the Drive (id from `amiko drive list`) — works for audio/video too
-amiko post create --content "wip idea" --draft         # save a draft — no share URL until published
+amiko post create --content "wip idea" --draft         # explicit draft (same as the default) — no share URL until published
 amiko post drafts                                       # list draft posts (--limit/--offset/--json)
+amiko post show <postId>                                # preview any post, including your own unpublished drafts
 amiko post likers <postId>                              # who liked one of YOUR posts (403 on someone else's)
 amiko post publish <postId>                             # publish a draft (fresh timestamp, prints the share URL)
 amiko post comment --id <postId> --comment "great post"
@@ -985,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`
 
@@ -1247,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
@@ -1808,6 +1888,7 @@ Send a friend request to a user by id
 | Flag | Default | Description |
 |---|---|---|
 | `--id <userId>` |  | Target user id |
+| `--yes` |  | Skip the confirmation. Only pass this after the owner has confirmed they want to friend this specific person. |
 | `--json` |  | Output as JSON |
 
 #### `amiko friends accept <friendshipId>`
@@ -1816,6 +1897,7 @@ Accept a pending friend request
 
 | Flag | Default | Description |
 |---|---|---|
+| `--yes` |  | Skip the confirmation. Only pass this after the owner has confirmed they want to accept this request. |
 | `--json` |  | Output as JSON |
 
 #### `amiko friends requests`
@@ -2039,8 +2121,9 @@ Create posts (notes) and comments on the feed — text, images, and documents
 
 | Subcommand | Description |
 |---|---|
-| `post create` | Create a post (a.k.a. note) on your feed |
+| `post create` | Create a post (a.k.a. note) on your feed. Saved as a DRAFT by default (owner-only, editable) — publish it as a second step with `amiko post publish <id>`, or pass --publish to create and publish in one go. |
 | `post drafts` | List your draft posts (newest first) |
+| `post show` | Preview a single post by id. Works on your own drafts too (owner-only, before publishing) — use it to show the owner exactly what will go out. |
 | `post publish` | Publish a draft post (stamps a fresh timestamp and notifies mentions) |
 | `post delete` | Delete one of your posts. Use this to clean up a post that went out wrong (bad link, test post, wrong version) |
 | `post comments` | List comments on a post |
@@ -2049,7 +2132,7 @@ Create posts (notes) and comments on the feed — text, images, and documents
 
 #### `amiko post create`
 
-Create a post (a.k.a. note) on your feed
+Create a post (a.k.a. note) on your feed. Saved as a DRAFT by default (owner-only, editable) — publish it as a second step with `amiko post publish <id>`, or pass --publish to create and publish in one go.
 
 | Flag | Default | Description |
 |---|---|---|
@@ -2059,8 +2142,9 @@ Create a post (a.k.a. note) on your feed
 | `--visibility <public|private>` | `public` | Post visibility |
 | `--media <pathOrUrl...>` |  | Attach media: local IMAGE file paths (uploaded automatically); Amiko-hosted URLs (image/music/video from `amiko create`); or `drive:<docId>` for a media file in your Drive (`amiko drive list`) |
 | `--doc <pathOrUrl...>` |  | Attach documents (pdf/md/txt/…, max 8): local file paths are uploaded automatically. Rendered as file cards, not images |
-| `--draft` |  | Save as a draft instead of publishing (list: amiko post drafts · publish: amiko post publish <id>) |
-| `--yes` |  | Skip the publish confirmation (drafts never prompt). Only pass this after the owner has reviewed the exact copy and approved sending it. |
+| `--draft` |  | Save as a draft (this is the default). Kept for clarity/back-compat — a bare `create` already drafts. List: amiko post drafts · publish: amiko post publish <id> |
+| `--publish` |  | Create AND publish immediately, skipping the draft step. Outward — everyone sees it — so it takes the confirmation gate (or --yes once the owner has approved the exact copy). |
+| `--yes` |  | Skip the publish confirmation (only relevant with --publish; drafts never prompt). Only pass this after the owner has reviewed the exact copy and approved publishing it. |
 | `--json` |  | Output as JSON |
 
 #### `amiko post drafts`
@@ -2073,6 +2157,14 @@ List your draft posts (newest first)
 | `--offset <n>` | `0` | Pagination offset |
 | `--json` |  | Output as JSON |
 
+#### `amiko post show <postId>`
+
+Preview a single post by id. Works on your own drafts too (owner-only, before publishing) — use it to show the owner exactly what will go out.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--json` |  | Output as JSON |
+
 #### `amiko post publish <postId>`
 
 Publish a draft post (stamps a fresh timestamp and notifies mentions)