@heyamiko/amiko-cli 0.17.2 → 0.19.0

package/README.md

@@ -314,6 +314,10 @@ amiko chat send @sophie "made this 🎵" --audio <generated-url> --yes  # attach
 amiko chat send @sophie --gif "happy dance" --yes                 # send the top Klipy GIF for a search (message optional)
 amiko chat gifs "happy dance"                    # browse GIFs first, then send a specific one:
 amiko chat send @sophie "we did it!" --gif <gifUrl> --yes         # attach an exact GIF by its Klipy URL
+amiko chat library --kind image                  # your Library (Create Studio creations) with refs
+amiko chat explore --search sunset               # public Explore media with refs
+amiko chat send @sophie "for review" --attach drive:<docId> --attach library:<id> --yes   # attach files you already have
+amiko chat send @sophie --attach explore:post:<postId>:0 --yes    # message optional with --attach
 amiko chat receipts <messageId>                  # who read your message + when (id from `chat read`)
 amiko chat pin <messageId> --yes                 # pin for everyone (id from `chat read`; groups: admins only)
 amiko chat unpin <messageId> --yes               # remove a pin for everyone
@@ -324,7 +328,12 @@ amiko chat mark-read --all --yes                 # mark EVERY conversation as re
 - **`<target>`** for `read`/`send` is a **conversation id** (from `chat list` — use this for groups), a **user id**, an **`@handle`**, or a **name**. Names resolve against your **friends first**, then people search; if ambiguous, the CLI lists candidates instead of guessing. A cuid that isn't one of your conversations is retried as a user id, so pasting a user id "just works".
 - `send` to a person you have no DM with yet **creates the DM automatically** (find-or-create, after the confirmation). `read` never creates one — it errors if no DM exists yet.
 - **Unread mentions & replies**: rows whose unread messages **concern you directly** get an `@you` marker next to the unread count, and `chat list --mentions` filters to just those. The flag is server-computed over your unread messages and covers three cases: a direct **@mention** of you, a permitted **@all** in a group, and a **reply to one of your messages**. Composes with `--limit`/`--archived`/`--raw` (the raw payload is filtered too). Requires the amiko-web `has_unread_mention` deploy. On an older server the field is absent and reads as **false for every conversation**: plain `chat list` still shows unread counts, just without `@you`, and `chat list --mentions` returns no matches.
-- **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL), `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note), and `--gif <queryOrUrl>` (search words send the **top Klipy result**; or pass an exact Klipy URL from `amiko chat gifs` — non-Klipy URLs are refused; to send another image, use `--image` with a local file or an Amiko URL). One media block per message (image *or* audio *or* gif). **General video files aren't supported in chat yet.** A local file is uploaded; an Amiko URL (e.g. a generated asset from `amiko create`) attaches directly with no re-upload. (A local *audio* file is sent as a voice note, with your text as a separate message.)
+- **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL), `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note), and `--gif <queryOrUrl>` (search words send the **top Klipy result**; or pass an exact Klipy URL from `amiko chat gifs` — non-Klipy URLs are refused; to send another image, use `--image` with a local file or an Amiko URL). One of those per message (image *or* audio *or* gif) — `--image` can also be combined with `--attach` below. **Local video files aren't supported in chat yet** (Library/Explore videos are, via `--attach`). A local file is uploaded; an Amiko URL (e.g. a generated asset from `amiko create`) attaches directly with no re-upload. (A local *audio* file is sent as a voice note, with your text as a separate message.)
+- **Attach from Drive, Library or Explore**: `--attach <ref>` (repeatable, up to 6 per message including `--image`) sends files you already have on Amiko — the same sources as the web composer's "Add from Drive" and "Add from Library or Explore". Nothing is re-uploaded.
+  - `drive:<docId>` — an **image or document** (pdf, docx, …, ≤25MB) from your Drive; ids from `amiko drive list --json` / `drive search`. Audio/video Drive files are refused. Sent as a file attachment that keeps its Drive `doc_id`.
+  - `library:<id>` — one of your Create Studio creations (image, video or audio); refs from `amiko chat library` (`--kind`, `--search`, `--limit`, `--cursor`, `--raw`).
+  - `explore:post:<postId>:<n>` — media from a public post on Explore; refs from `amiko chat explore` (same flags, minus `--twin`).
+  - Drive and Library use your current twin; `--twin <id>` picks another. The message text is optional with `--attach` (recipients see an "Image"/"Video"/"Audio"/"File" label). Library/Explore refs are checked before the confirmation; Drive files are validated and signed only after you approve, so a declined send leaves nothing behind. `--attach` can't be combined with `--audio` or `--gif`.
 - **GIFs**: `amiko chat gifs [query]` lists Klipy GIFs (trending with no query; `--page`/`--limit`/`--raw`) — read-only and ungated, powered by KLIPY. The message text is optional with `--gif` (a captionless GIF sends as just the GIF); a caption renders under the GIF on every client.
 - **@all in groups**: `--all` prepends an @all mention, and a standalone `@all` word typed in the message converts too — either way **every member** is notified. Group **admins/owners** can always use it; everyone else only after an admin runs `amiko chat group mention-all <group> on`. Without permission, `--all` fails with the fix named, while a typed `@all` is delivered as plain text (with a note). Incoming mention markup renders as plain `@name`/`@all` in `chat read` and `chat list`.
 - `chat send` messages a real person, so it's **gated on `--yes`** in non-interactive shells. Delivery is real-time. `--raw` prints raw JSON on any subcommand.
@@ -371,6 +380,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**).
@@ -975,7 +1007,7 @@ Your conversations (DMs + group chats) as the owner — list, read, send, manage
 |---|---|
 | `chat list` | List your conversations (DMs and group chats) |
 | `chat read` | Read recent messages in a conversation (conversation id, user id, @handle, or name) |
-| `chat send` | Send a message as yourself (the owner) to a conversation or person (conversation id, user id, @handle, or name — DMs are opened automatically). The message is optional only with --gif. |
+| `chat send` | Send a message as yourself (the owner) to a conversation or person (conversation id, user id, @handle, or name — DMs are opened automatically). The message is optional only with --gif or --attach. |
 | `chat react` | React to a message as yourself (the owner). Get the message id from `amiko chat read`. One reaction per message — a new emoji replaces your previous one. |
 | `chat unreact` | Remove your (the owner's) reaction from a message. Get the message id from `amiko chat read`. |
 | `chat reactions` | Show the reactions on a message. Get the message id from `amiko chat read`. |
@@ -985,8 +1017,11 @@ Your conversations (DMs + group chats) as the owner — list, read, send, manage
 | `chat pinned` | List a conversation's pinned messages, oldest first (conversation id, user id, @handle, or name) |
 | `chat mark-read` | Mark ALL conversations as read (requires --all). Clears every unread badge on the owner's devices; senders see read ticks. |
 | `chat gifs` | Search Klipy GIFs (trending when no query) — pass a result URL to `amiko chat send --gif` |
+| `chat library` | List your Library (Create Studio creations) — pass a ref to `amiko chat send --attach` |
+| `chat explore` | List recent public media from Explore — pass a ref to `amiko chat send --attach` |
 | `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`
 
@@ -1010,13 +1045,15 @@ Read recent messages in a conversation (conversation id, user id, @handle, or na
 
 #### `amiko chat send <target> [message]`
 
-Send a message as yourself (the owner) to a conversation or person (conversation id, user id, @handle, or name — DMs are opened automatically). The message is optional only with --gif.
+Send a message as yourself (the owner) to a conversation or person (conversation id, user id, @handle, or name — DMs are opened automatically). The message is optional only with --gif or --attach.
 
 | Flag | Default | Description |
 |---|---|---|
 | `--image <pathOrUrl>` |  | Attach an image: local file (jpg/png/webp/gif, ≤10MB) or an Amiko URL (e.g. from `amiko create`) |
 | `--audio <pathOrUrl>` |  | Attach audio as a voice note: local file (≤25MB) or an Amiko URL |
 | `--gif <queryOrUrl>` |  | Attach a GIF: search words (sends the top Klipy result) or a Klipy URL from `amiko chat gifs` |
+| `--attach <ref>` |  | Attach a file you already have on Amiko (repeatable, up to 6): drive:<docId> (image or document from `amiko drive list`), library:<id> (from `amiko chat library`), explore:post:<postId>:<n> (from `amiko chat explore`). Combines with --image. |
+| `--twin <id>` |  | Twin whose Drive/Library --attach reads (default: your current twin) |
 | `--all` |  | Mention @all — notifies every member of the group (admins/owners always; others only when enabled via `amiko chat group mention-all`) |
 | `--yes` |  | Skip the confirmation (required in non-interactive shells) |
 | `--raw` |  | Output raw JSON |
@@ -1101,6 +1138,31 @@ Search Klipy GIFs (trending when no query) — pass a result URL to `amiko chat
 | `--limit <n>` | `10` | Max results shown (1-24) |
 | `--raw` |  | Output raw JSON |
 
+#### `amiko chat library`
+
+List your Library (Create Studio creations) — pass a ref to `amiko chat send --attach`
+
+| Flag | Default | Description |
+|---|---|---|
+| `--twin <id>` |  | Twin whose Library to list (default: current twin) |
+| `--kind <kind>` |  | Only image, video, or audio |
+| `--search <text>` |  | Filter by prompt text |
+| `--limit <n>` | `20` | Items to fetch (1-50) |
+| `--cursor <cursor>` |  | Continue from a previous page |
+| `--raw` |  | Output raw JSON |
+
+#### `amiko chat explore`
+
+List recent public media from Explore — pass a ref to `amiko chat send --attach`
+
+| Flag | Default | Description |
+|---|---|---|
+| `--kind <kind>` |  | Only image, video, or audio |
+| `--search <text>` |  | Filter by title |
+| `--limit <n>` | `20` | Posts to fetch (1-96) |
+| `--cursor <cursor>` |  | Continue from a previous page |
+| `--raw` |  | Output raw JSON |
+
 #### `amiko chat group`
 
 Group chats — create, list, info, rename, add/remove members, @all permission, leave
@@ -1249,6 +1311,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