@heyamiko/amiko-cli 0.14.0-beta.2 → 0.14.0-beta.20

package/README.md

@@ -1,4 +1,4 @@
-# @heyamiko/amiko-cli (v0.14.0-beta.0)
+# @heyamiko/amiko-cli (v0.14.0-beta.15)
 
 Manage wallets, credits, swaps, MPP marketplace services, and your Amiko twin (identity, documents, voice, avatar, friends, feed) from the terminal. Works for both human users and AI agents running on OpenClaw.
 
@@ -120,13 +120,21 @@ Image generation typically takes 20–60s. In non-TTY environments (agents, pipe
 
 ## Create Studio
 
-The CLI half of the platform's Create Studio. `amiko create` generates media through Amiko's own authenticated endpoints (not the raw MPP pay-per-call surface `amiko markets` uses). Generation runs **asynchronously** and is **charged on success** from your twin's wallet — a failed or timed-out generation is never billed, and there's no up-front payment.
+The CLI half of the platform's Create Studio. `amiko create` generates media through Amiko's own authenticated endpoints (not the raw MPP pay-per-call surface `amiko markets` uses). Generation runs **asynchronously** and is **charged on success** from your twin's wallet — a failed or timed-out generation is never billed, and there's no up-front payment. On unified-billing accounts, `--pay credits` pays from your Amiko account credits instead: the quote is reserved at submit, captured only on success, and released on failure (legacy accounts get a clear server error — omit the flag to keep the twin-wallet default).
 
 ```bash
-amiko create image "a sunset over mountains"                    # default gpt-image-2, 1:1
-amiko create image "logo" --aspect 16:9 --model gpt-image-2     # widescreen
+amiko create image "a sunset over mountains"                    # default nano-banana-2, 1:1
+amiko create image "logo" --aspect 16:9 --model gpt-image-2     # widescreen, OpenAI
+amiko create image "a sunset" --pay credits --yes               # pay with Amiko account credits (unified accounts)
 amiko create video "a whale in space" --resolution 768P --seconds 6
+amiko create video "animate cover" --first-frame https://.../cover.png --yes
+amiko create video "dance clip" --model dreamina-seedance-2-0-fast-260128 \
+  --reference-image https://.../ref1.png --reference-audio https://.../beat.mp3 --generate-audio --yes
 amiko create tts "Hello world" --voice 21m00Tcm4TlvDq8ikWAM
+amiko create tts "Hello world" --provider minimax --model speech-2.8-turbo
+amiko create tts "Hello" --provider minimax --voice English_expressive_narrator --yes
+amiko voice clone ./me.mp3 --provider minimax
+amiko voice clone ./me.mp3 --provider elevenlabs
 amiko create music "lo-fi chill beat" --duration 30000
 amiko create music --lyrics "..." --instrumental               # instrumental
 amiko create sfx "thunder and heavy rain" --duration 5
@@ -139,7 +147,8 @@ Modes: `image`, `video`, `tts`, `music`, `sfx` (mirrors the platform Create Stud
 
 | Flag | Description |
 |------|-------------|
-| `--token <symbol>` | Charge token: `AMIKO`, `USDC`, `USDT`, `SOL` (default: auto, AMIKO-first) |
+| `--pay <method>` | Payment method: `wallet` (twin wallet, default) or `credits` (Amiko account credits — unified accounts only) |
+| `--token <symbol>` | Wallet charge token: `AMIKO`, `USDC`, `USDT`, `SOL` (default: auto, AMIKO-first); ignored with `--pay credits` |
 | `--yes` | Skip the pre-spend confirmation (required in non-interactive shells) |
 | `--raw` | Output the raw job result as JSON |
 
@@ -147,25 +156,46 @@ Modes: `image`, `video`, `tts`, `music`, `sfx` (mirrors the platform Create Stud
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--model <model>` | `gpt-image-2` | Image model |
+| `--model <model>` | `nano-banana-2` | Image model (`nano-banana[-2|-lite|-pro]`, `gpt-image-*`, `grok-imagine-image-quality`, `image-01`) |
 | `--aspect <ratio>` | `1:1` | Aspect ratio: `1:1`, `16:9`, `9:16`, `4:3`, `3:4` |
 
 **`amiko create video <prompt>`**
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--model <model>` | `MiniMax-Hailuo-2.3-Fast` | Video model |
+| `--model <model>` | smart | Video model (`MiniMax-Hailuo-*`, `dreamina-seedance-2-0-fast-260128`, …). Default: `MiniMax-Hailuo-02` for prompt-only (T2V), `MiniMax-Hailuo-2.3-Fast` when `--first-frame` is given (I2V) |
 | `--resolution <res>` | `768P` | `512P`, `720P`, `768P`, `1080P` |
 | `--seconds <n>` | `6` | Clip length: `6` or `10` |
 | `--aspect <ratio>` | — | Aspect ratio (provider-dependent) |
 | `--first-frame <url>` | — | Image-to-video: first frame URL or data URI |
+| `--last-frame <url>` | — | First-and-last-frame video: ending frame URL or data URI |
+| `--reference-image <url>` | — | Seedance multimodal reference image (repeatable, max 9) |
+| `--reference-video <url>` | — | Seedance multimodal reference video (repeatable, max 3) |
+| `--reference-audio <url>` | — | Seedance multimodal reference audio (repeatable, max 3) |
+| `--subject-reference <url>` | — | MiniMax S2V subject/character reference image |
+| `--generate-audio` | — | Seedance: generate audio in the output |
+| `--no-generate-audio` | — | Seedance: output silent video |
+
+Reference flags accept URLs or data URIs (not local paths). Typical I2V flow: `create image` → `create status <jobId>` for the image URL → `create video --first-frame <url>`.
 
 **`amiko create tts <text>`**
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--model <model>` | `eleven_multilingual_v2` | TTS model id |
-| `--voice <voiceId>` | `21m00Tcm4TlvDq8ikWAM` | Voice id |
+| `--provider <name>` | inferred / `elevenlabs` | `minimax` or `elevenlabs` — sets model/voice defaults when those flags are omitted |
+| `--model <model>` | EL: `eleven_multilingual_v2`; MiniMax: `speech-2.8-turbo` | MiniMax: `speech-2.8-turbo\|hd`, `speech-2.6-turbo\|hd`. ElevenLabs: `eleven_*` |
+| `--voice <voiceId>` | EL default hash; MiniMax: `English_expressive_narrator` | MiniMax system or cloned `voice_id`; ElevenLabs voice id |
+
+Examples: `amiko create tts "Hi" --provider minimax --yes` · `amiko create tts "Hi" --provider minimax --model speech-2.8-turbo --voice <clonedId> --yes`
+
+**`amiko voice clone <source>`** — audio path, https URL, or `-` (stdin)
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--provider <name>` | `minimax` | `minimax` (mpp rapid clone + ownership registry) or `elevenlabs` (legacy IVC) |
+| `--voice-id <id>` | auto | **MiniMax only** — optional custom voice_id (ignored for elevenlabs) |
+| `--model <model>` | `speech-2.8-turbo` | **MiniMax only** — preview speech model (ignored for elevenlabs) |
+| `--preview-text <text>` | provider default | **MiniMax only** — preview line; empty string skips preview (ignored for elevenlabs) |
 
 **`amiko create music [prompt]`** — pass a prompt and/or `--lyrics`
 
@@ -222,15 +252,48 @@ amiko chat list --limit 50 --archived            # include archived
 amiko chat read @sophie                          # recent messages with a user (by @handle)
 amiko chat read <conversationId> --limit 40      # by conversation id (from `chat list`) — works for groups too
 amiko chat send @sophie "on my way!" --yes       # send as the owner
+amiko chat send <userId> "hey!" --yes            # user id works too — the DM is opened automatically
+amiko chat send Mars "hey!" --yes                # or a name (friends first, then people search)
 amiko chat send <groupConversationId> "hi all" --yes   # send to a group chat
+amiko chat send "Trip planning" "standup in 5 @all" --yes     # @all — notifies every group member
+amiko chat send "Trip planning" "standup in 5" --all --yes    # same, via the explicit flag
 amiko chat send @sophie "look 👀" --image ./cat.png --yes         # attach a local image
 amiko chat send @sophie "made this 🎵" --audio <generated-url> --yes  # attach audio (e.g. from `amiko create`)
+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
+amiko chat pinned "Trip planning"                # list a conversation's pinned messages, oldest first
 ```
 
-- **`<target>`** for `read`/`send` is a **conversation id** (from `chat list` — use this for groups), an **`@handle`**, or a **name** (resolved via user search; if ambiguous, the CLI lists candidates instead of guessing).
-- A DM target that doesn't exist yet is **created automatically** (find-or-create).
+- **`<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.
 - **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL) and `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note). One media block per message (image *or* audio). **Video isn'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.)
+- **@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.
+- **`chat receipts <messageId>`** shows read receipts for **your own** messages (server-enforced; 403 otherwise): sent time, who read it with each person's first-read time, and who it was delivered to but hasn't read. Reads from before receipts tracking show as "exact time unknown". Read-only, ungated.
+- **Pinned messages**: `chat pin <messageId>` pins for the **whole conversation** (the chat sees an "X pinned a message" announcement) and `chat unpin <messageId>` removes it for everyone — both gated on `--yes`. In **groups** only admins can pin/unpin (403 otherwise); in DMs either side can. Max 20 pins per conversation. `chat pinned <target>` (same targets as `read`; never creates a DM) lists them oldest-first with each message's id and pinner — read-only, ungated.
+
+### Group chats
+
+Create and manage group chats **as the owner** via `amiko chat group`:
+
+```bash
+amiko chat group create "Leandro testing" --member Sophie --member Mars --member Matthew --yes
+amiko chat group list                            # your group chats: title, id, member count, unread
+amiko chat group info "Leandro testing"          # members + roles (admins marked); works with the id too
+amiko chat group rename <groupIdOrTitle> "New name" --yes
+amiko chat group add <groupIdOrTitle> --member @sophie --yes
+amiko chat group remove <groupIdOrTitle> --member Mars --yes
+amiko chat group promote <groupIdOrTitle> --member Sophie --yes   # make a member an admin
+amiko chat group mention-all <groupIdOrTitle> on --yes   # let everyone use @all (off = admins only, the default)
+amiko chat group leave <groupIdOrTitle> --yes    # alias: delete — see caveat below
+```
+
+- **`--member`** is repeatable and accepts a plain name, `@handle`, or user id. Plain names resolve against your **friends** first (then people search); an ambiguous name errors listing candidates instead of guessing, and one unresolvable member aborts the whole command **before anything is changed**.
+- **Groups address by id or title** — titles match case-insensitively (exact first, then substring) across your most recent 100 conversations; ambiguous titles error with candidates. `chat send "<group title>" "hi" --yes` also works when exactly one group title matches.
+- **`leave` (alias `delete`) only hides the group for you.** Other members keep the conversation and its history — the platform has no delete-for-everyone. Rename, add, remove-others, promote, and the @all toggle are **admin-only** (the creator is admin); the server enforces this.
+- **`mention-all <group> <on|off>`** controls who may @all in the group: `on` lets every member, `off` (the default) restricts it to admins. The current setting shows in `amiko chat group info` as `@all mentions: everyone | admins only`.
+- `create`/`add` are outward social actions and `rename`/`remove`/`leave`/`promote`/`mention-all` are destructive, so all are **gated on `--yes`** in non-interactive shells. `--raw` prints JSON everywhere.
 
 ## Twin Cards
 
@@ -309,8 +372,11 @@ amiko markets service call POST /v1/sfx '{"text":"Thunder with heavy rain","dura
 # Music generation ($0.10) — returns { url, format, service }
 amiko markets service call POST /v1/music '{"prompt":"Lo-fi chill beat","music_length_ms":30000}'
 
-# Text-to-speech (1 AMIKO) — returns { url, format, service }
+# Text-to-speech — ElevenLabs voice id (default)
 amiko markets service tts 21m00Tcm4TlvDq8ikWAM "Hello world"
+# MiniMax system or cloned voice_id
+amiko markets service tts English_expressive_narrator "Hello" --provider minimax --yes
+amiko markets service tts <clonedId> "Hello" --provider minimax --model speech-2.8-turbo --yes
 
 # Composition plan ($0.02)
 amiko markets service call POST /v1/music/plan '{"prompt":"Epic orchestral piece"}'
@@ -443,7 +509,7 @@ src/
 │   ├── avatar.ts         # avatar update
 │   ├── friends.ts        # friends list, requests, add, accept, remove, matches, reports
 │   ├── users.ts          # users search, profile
-│   └── feed.ts           # feed, post create, post comment
+│   └── feed.ts           # feed, post create/drafts/publish, post comment
 └── lib/
     ├── config.ts          # defaults + resolved auth wrapper
     ├── agent-config.ts    # .amiko.json reader + auth resolution
@@ -501,9 +567,12 @@ amiko users profile <handle>            # public profile
 # Feed & posts
 amiko feed                              # friends feed (default)
 amiko feed --type for_you --limit 20
-amiko post create --content "hello from the CLI"           # public post
+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 "private note" --visibility private
 amiko post create --content "look" --media https://...jpg
+amiko post create --content "wip idea" --draft         # save a draft — no share URL until published
+amiko post drafts                                       # list draft posts (--limit/--offset/--json)
+amiko post publish <postId>                             # publish a draft (fresh timestamp, prints the share URL)
 amiko post comment --id <postId> --comment "great post"
 amiko post comment --id <postId> --comment "nice!" --media https://...jpg
 ```
@@ -528,6 +597,49 @@ npm publish
 
 ## Changelog
 
+### 0.14.0-beta.20
+
+- **Draft posts: `amiko post create --draft`, `amiko post drafts`, `amiko post publish <postId>`.** `--draft` saves via `POST /api/posts { status: "draft" }` — no side effects fire and no share URL is printed (drafts 404 by id until published; success copy says "Draft saved" with a publish hint, and `post_url` is omitted from `--json`). `drafts` lists the owner's draft posts (`GET /api/posts?status=draft`, offset pagination via `--limit`/`--offset`; owner-wide across all the owner's twins). `publish` PATCHes `{ status: "published" }`, stamps a fresh timestamp, fires mention/hashtag notifications, and prints the canonical share URL; a 404 points at `amiko post drafts` since drafts can't be fetched by id. Requires the amiko-web draft-posts API (`feat/draft-posts`).
+
+### 0.14.0-beta.19
+
+- **Pinned messages: `amiko chat pin <messageId>`, `amiko chat unpin <messageId>`, `amiko chat pinned <target>`.** Pins are conversation-wide: `pin` posts an "X pinned a message" announcement to the whole chat (POST `/api/messages/{id}/pin`), so it sits behind the outward-action `--yes` gate with a content preview; `unpin` (DELETE, silent but removes shared state for everyone) sits behind the destructive gate. Groups are admin-gated server-side — a 403 names the rule and the `chat group info` check; DMs let either side pin. 409 at the 20-pin cap and 400 for unpinnable (system/in-flight) messages get status-specific copy. `pinned <target>` is an ungated read using the same target resolution as `chat read` (conversation id, user id, `@handle`, or name; never creates a DM), listing pins oldest-first with sender, message id, and pinner name; `--raw` on all three. Requires the companion amiko-web `feat/chat-pinned-messages` deploy.
+
+### 0.14.0-beta.18
+
+- **Read receipts: `amiko chat receipts <messageId>`.** Shows when the message was sent, who has read it (per-person first-read time), and who it was delivered to but hasn't read yet. Sender-only, enforced server-side — works for messages sent as the owner (`chat send`); anything else 403s with a clear message. Reader names resolve from the conversation's participant list (short-id fallback). Read-only and ungated, like `chat reactions`; `--raw` prints the API payload. Rows read before receipts tracking existed render as "exact time unknown". Requires the companion amiko-web `feat/chat-read-receipts` deploy (`GET /api/messages/{id}/receipts`).
+
+### 0.14.0-beta.17
+
+- **@all mentions in group chats + `amiko chat group mention-all <group> <on|off>`.** `chat send` gains `--all`, and a standalone literal `@all` word in the message converts too — both emit the canonical sentinel `@[all](all:all)` (kept in sync with amiko-web `src/utils/mentions.ts`), which amiko-chat expands into a mention notification for every group member. The CLI pre-checks permission client-side, mirroring the web gate plus the server-honored `owner` role (`admin`/`owner`, or the conversation's `allow_everyone_mention_all` flag; `left_at` participants excluded): a denied `--all` exits 1 naming the fix, before the approval gate and before any DM could be created, while a denied literal `@all` degrades to plain text with a note — the server treats an unauthorized token as inert either way. The new `chat group mention-all` toggle PATCHes `/api/conversations/{id}/mention-all-permission` (admin-gated server-side, 403 → admin tip) behind `confirmDestructive`, and the current setting shows in `chat group info` (`@all mentions: everyone | admins only`). Incoming mention markup (`@[Name](id:user|agent)` / `@[all](all:all)`) now renders as plain `@Name`/`@all` in `chat read`, `chat list`, and `chat group list` previews (new `src/lib/mentions.ts`). Requires the companion amiko-web `feat/group-mention-all` deploy.
+
+### 0.14.0-beta.15
+
+- Create Studio defaults to `--pay credits` (account credits) instead of twin wallet; pass `--pay wallet` for on-chain.
+
+### 0.14.0-beta.14
+
+- `credits balance` prefers `AMIKO_API_KEY` (`amk_`) → `billing.heyamiko.com/api/credits` directly; falls back to twin-token platform proxy. Override base with `AMIKO_BILLING_URL`.
+
+### 0.14.0-beta.13
+
+- **Create Studio TTS + voice clone: MiniMax.** `amiko create tts` accepts `--provider minimax|elevenlabs` (infers from `speech-*` / `eleven_*` models when omitted), with provider-specific defaults (`speech-2.8-turbo` + `English_expressive_narrator` vs `eleven_multilingual_v2` + Rachel). Quote body includes `voiceId`. Cloned-voice examples require `--provider minimax` when using a MiniMax `voice_id`.
+- **`amiko voice clone`** defaults to MiniMax (mpp rapid clone + ownership registry); `--provider elevenlabs` keeps legacy IVC. MiniMax-only flags: `--voice-id`, `--model`, `--preview-text`.
+- **`amiko markets service tts`** gains `--provider minimax|elevenlabs` and `--model` for MiniMax speech routing on `/v1/tts/:voiceId`.
+
+### 0.14.0-beta.7
+
+- **`amiko chat group invite <group>` — share a group's invite/join link + QR.** New read-only subcommand that fetches `GET /api/conversations/{id}/invite` (twin token) and prints the join link plus a scannable QR image URL. Admins-only: SKILL.md instructs the agent to confirm the asker holds `admin`/`owner` (via `amiko chat group info`) before sharing, and the endpoint is admin-gated server-side (403 → admin tip). Fails loudly if the response is missing its link/QR instead of printing a placeholder. Requires the companion amiko-web change (adds `qrUrl` to the invite response + a public `GET /api/conversations/join/[token]/qr` PNG route).
+
+### 0.14.0-beta.6
+
+- **`amiko chat send`/`read` accept user ids — DMs no longer require an existing conversation.** Target resolution is rebuilt: a cuid target is verified as a conversation first and, on 404, retried as a user id (user ids and conversation ids are both cuids — previously a user id went straight to the messages route and died with "Conversation not found"). Plain names now resolve **friends-first** (then people search) via the shared `resolveMembers`, with ambiguity reported as a candidate list. Resolution is fully read-only: for `send`, a missing DM is found-or-created only **after** the `--yes`/approval gate (no more empty conversations from an unapproved send), and `read` never creates a DM at all — it errors if none exists. The confirmation summary now shows the **resolved** recipient (`Send to DM with Mars (@mars): …`) so a wrong-person resolution is visible before anything goes out. Unknown cuids are rejected before any conversation is created (the backend accepts dangling participant ids silently), and a 403 on a real conversation no longer falls through to DM creation.
+- **Free outward actions no longer talk about cost.** `requireApproval` gained a `free` mode used by `chat send` and `chat group create/add`: the non-interactive refusal now says the action is free and tells the agent to confirm the action itself — instead of the old "This command will cost no charge… quote the cost to the user", which made twins ask owners to "approve the paid operation, cost 0". SKILL.md's Critical Rule 1 spells out the anti-pattern, documents user-id DM targets ("the owner never needs to start the conversation first"), and drops the false "server enforces friend rules" claim that fed authorization hallucinations.
+
+### 0.14.0-beta.5
+
+- **`amiko chat group` — group-chat management as the owner.** New subcommand group under `chat`: `create` (name + repeatable `--member`, one atomic POST), `list`, `info` (members + roles), `rename`, `add`, `remove`, `promote`, and `leave` (alias `delete`). Members resolve friends-first by name (then people search), all-or-nothing before any mutation; groups address by id or case-insensitive title. Uses the existing amiko-web conversation routes (twin token) — rename/add/remove-others/promote are admin-enforced server-side, and `leave|delete` is honest about the platform's semantics: it only hides the group for the caller, there is no delete-for-everyone. `create`/`add` gate on `requireApproval`, the destructive rest on `confirmDestructive` (both exit 2 without `--yes` in non-interactive shells). Plain-name `chat send`/`read` targets now prefer an exact, unambiguous group-title match over people search. Shared conversation types + resolution helpers extracted to `src/lib/conversations.ts`; `convLabel` self-filtering now strips the `did:privy:` prefix so DM labels no longer include the owner. SKILL.md gains a Group chats block + gating-list updates.
+
 ### 0.14.0-beta.0
 
 - **Direct USDC/USDT payment for MPP marketplace services (Bug #9).** `markets search`, `markets image`, and `markets amazon search` gain `--token <AMIKO|USDC|USDT>`; `markets service call` completes its `--usdc` path and adds `--usdt` (both accept `auto` to price from the endpoint's USD anchor). Stables are pinned at $1.00 — no forced swap to AMIKO and no credits conversion. Requires the matching mpp-service deploy: `charge()`/`chargeAmiko()` now read `X-Payment-Token` and verify the on-chain transfer against that token's mint (`verifySplTransfer`), with a ±0.5% tolerance for stables (±5% stays for AMIKO spot drift). Also fixes stale hardcoded amounts: `markets search` / `amazon search` paid a flat "1 AMIKO" regardless of spot — under current prices that under-pays the $0.01 anchor and fails verification; amounts are now quoted live before the approval gate, which shows the real cost instead of "1 AMIKO". Shared payment plumbing extracted to `src/lib/treasury-payment.ts` (one TREASURY constant, one transfer path).