@heyamiko/amiko-cli 0.15.3 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.15.3",
+  "version": "0.16.1",
   "description": "Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace agents",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
     "prepublishOnly": "bun run build",
     "dev": "bun run src/index.ts",
     "typecheck": "bun x tsc --noEmit",
-    "test": "bun test"
+    "test": "bun test",
+    "gen:reference": "bun run scripts/gen-command-reference.ts"
   },
   "files": [
     "dist",

package/skills/SKILL.md

@@ -66,13 +66,13 @@ The CLI is installed globally and is pre-authenticated when you're inside your w
 
 ## Command groups
 
-Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `create` (Create Studio — async media generation, charged on success), `chat` (owner's DMs + group chats), `card` (Twin Cards — work/play/love), `wallets`, `credits`, `twin`, `drive` (files / folders / RAG; `docs` is an alias), `voice`, `avatar`, `friends`, `users` (search, profiles, follows), `post` (a.k.a. notes), `review`, `feed`, `notifications`, `memory`, plus the top-level `accounts`, `info`, `config`, `update`. `--twin <idOrName>` is supported where a command can target another of the owner's twins (`drive`, `twin`, `voice`, `avatar`, `post`/`review`/`feed`, `memory`, `accounts`); `create`, `chat`, `card`, and `friends` always act on the authenticated twin — do NOT pass `--twin` there (unknown-option error). Most commands support `--json`.
+Discover everything via `amiko --help` (or `amiko <group> --help` / `amiko <group> <subcommand> --help` for the flags of one command). The README's **Command Reference** section is the same information as one list — every group, subcommand, argument, flag and default — generated from the CLI's own command tree, so it and `--help` can never disagree. Groups: `search` (paid web/X/Amazon/news/… search — see below), `markets` (paid MPP services), `create` (Create Studio — async media generation, charged on success), `chat` (owner's DMs + group chats), `card` (Twin Cards — work/play/love), `wallets`, `credits`, `twin`, `drive` (files / folders / RAG; `docs` is an alias), `voice`, `avatar`, `friends`, `users` (search, profiles, follows), `post` (a.k.a. notes), `review`, `feed`, `notifications`, `memory`, plus the top-level `accounts`, `info`, `config`, `update`. `--twin <idOrName>` is supported where a command can target another of the owner's twins (`drive`, `twin`, `voice`, `avatar`, `post`/`review`/`feed`, `memory`, `accounts`); `create`, `chat`, `card`, and `friends` always act on the authenticated twin — do NOT pass `--twin` there (unknown-option error). Most commands support `--json`.
 
 > **Two chat surfaces — pick by identity.** `amiko chat` is the **owner's** DMs and group chats, acting **as the owner** (list / read / send, plus `chat group` to create and manage group chats). The openhermit gateway's `session_list` / `session_send` are the **agent's own** sessions, acting **as the agent**. "Send a message to Sophie for me" → `amiko chat send`; "have the twin reply as itself" → gateway. (The old `amiko conversation` namespace was removed in 0.10.1-beta.4; `amiko chat` is its owner-identity replacement.)
 
 ## Critical Rules
 
-1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `markets *`, `create *`, `card mint`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.** The same `--yes` gate also covers **free outward social actions** — `chat send`, `chat pin` (the whole chat sees a pinned-message announcement), `chat group create`, `chat group add` (real people see them, so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat unpin` (removes the pin for everyone), `chat mark-read --all` (irreversibly marks every conversation read — senders see read ticks), `chat group remove/leave/rename/promote/mention-all`, `chat lists create/rename/add/remove/delete` (private to the owner, but they reshape the owner's chat UI), `friends nickname set/remove` (private to the owner, but it changes how that friend is displayed everywhere in the owner's apps), `twin update --public`, `drive delete`, `drive share` / `drive folder share` (exposes the file — or the folder's ENTIRE subtree — to anyone with the link), `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`. **For these free actions never mention cost, never say "the cost is 0", and never call it a paid operation** — ask for plain confirmation of the action itself (e.g. "Send "hi" to Mars — go ahead?").
+1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `search *`, `markets *`, `create *`, `card mint`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.** The same `--yes` gate also covers **free outward social actions** — `chat send`, `chat pin` (the whole chat sees a pinned-message announcement), `chat group create`, `chat group add` (real people see them, so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat unpin` (removes the pin for everyone), `chat mark-read --all` (irreversibly marks every conversation read — senders see read ticks), `chat group remove/leave/rename/promote/mention-all`, `chat lists create/rename/add/remove/delete` (private to the owner, but they reshape the owner's chat UI), `friends nickname set/remove` (private to the owner, but it changes how that friend is displayed everywhere in the owner's apps), `twin update --public`, `drive delete`, `drive share` / `drive folder share` (exposes the file — or the folder's ENTIRE subtree — to anyone with the link), `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`. **For these free actions never mention cost, never say "the cost is 0", and never call it a paid operation** — ask for plain confirmation of the action itself (e.g. "Send "hi" to Mars — go ahead?").
 2. **After every paid command, report the remaining balance.** The CLI prints a `Balance: N credits` line — include that figure in your reply.
 3. **Never retry a failed command.** Report and stop. Every paid call costs tokens even on failure.
 4. **Auth is automatic.** Never suggest `amiko login` / `amiko connect`. Run from the agent's workspace folder; if anything looks off, `amiko accounts` shows the resolved `userId` / `twinId`.
@@ -93,6 +93,25 @@ Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `
 
 ### Quoting cost before running
 
+## Search — `amiko search <vertical> <query>`
+
+One group, seventeen verticals, **$0.01 each** (`engines` is free). Run `amiko search --help` for the list and `amiko search <vertical> --help` for that vertical's flags.
+
+`web` (google by default, `--engine bing|duckduckgo`), `x` (X/Twitter), `news`, `images`, `videos`, `youtube`, `scholar`, `patents`, `maps`, `jobs`, `shopping`, `amazon`, `walmart`, `finance`, `trends`, and `engines` (free — lists what is actually live on the backend and the parameters each engine accepts).
+
+```bash
+amiko search web "who won the 2026 world cup" --yes
+amiko search news "openai" --country us --since last_day --yes
+amiko search amazon "usb c hub" --max 40 --limit 10 --yes
+amiko search scholar "protein folding" --from 2020 --raw --yes
+```
+
+- **Use `--raw`.** It prints the full JSON response and nothing else on stdout, so it parses directly. Warnings and errors go to stderr and never contaminate it.
+- **`--limit <n>`** caps what is printed (default 5); `--param key=value` (repeatable) forwards any upstream parameter the curated flags don't cover.
+- **Pick the narrow vertical over `web`.** `search scholar` beats `search web "… site:scholar.google.com"`; same for `news`, `amazon`, `jobs`, `maps`.
+- **Payment settles on-chain BEFORE the request and has no refund path.** A failed search still cost money — the CLI says what it charged and prints the tx hash. Don't blind-retry a failing search in a loop.
+- `amiko markets search` (X) and `amiko markets amazon search` still work but are **deprecated**; they warn and delegate to `amiko search x` / `amiko search amazon`. Use the new names.
+
 Prices change. Before any paid call, run `amiko markets service list` or `amiko markets discover` to fetch the live price, then quote it to the user. Rough order of magnitude: text/search/TTS ≈ 1 AMIKO, SFX ≈ $0.05, music ≈ $0.10, image gen varies by model/quality (e.g. nano-banana ≈ $0.05, nano-banana-pro ≈ $0.17).
 
 ## The `--wallet` default (read this before any paid command)
@@ -127,7 +146,7 @@ Supported: AMIKO, SOL, USDC, USDT. Balance can lag a few seconds after topup —
 
 All paid markets commands auto-select the twin's active Solana wallet (see `--wallet` default above). Audio and image endpoints return permanent Supabase Storage URLs. Use `markets service call <METHOD> <path> [body]` for any MPP endpoint not covered by a dedicated subcommand.
 
-**Prefer `amiko create` for anything it supports.** For media generation — image, video, speech (TTS), music, SFX — use `amiko create` (async, charge-on-success, never loses money on a timeout), NOT `markets`. Reach for `markets` **only for what `create` does not cover**: X/Twitter search, Amazon, AI chat, speech-to-text/transcription, and arbitrary MPP endpoints via `markets service call`.
+**Prefer `amiko create` for anything it supports.** For media generation — image, video, speech (TTS), music, SFX — use `amiko create` (async, charge-on-success, never loses money on a timeout), NOT `markets`. For **search of any kind** — web, X/Twitter, news, images, scholar, maps, jobs, shopping, Amazon — use the `amiko search` group, NOT `markets`. Reach for `markets` **only for what neither covers**: AI chat, speech-to-text/transcription, Amazon ordering, and arbitrary MPP endpoints via `markets service call`.
 
 ### Voice IDs — never guess
 
@@ -144,11 +163,11 @@ This twin has **two** optional TTS ids. They are **not** the same:
 - System MiniMax voices (no clone) also work: e.g. `--voice English_expressive_narrator --provider minimax` (same approval gate before `--yes`).
 - `markets service tts <voiceId> "…" --provider minimax --yes` needs the same MiniMax id and approval gate.
 
-**Payment token:** `markets search`, `markets image`, and `markets amazon search` accept `--token <AMIKO|USDC|USDT>` (default AMIKO); `markets service call` uses `--usdc`/`--usdt` (pass `auto` to price from USD). Stables are pinned at $1.00 — the amount equals the endpoint's USD price — so there is no forced swap through AMIKO. When the owner asks to pay in USDT/USDC, pass the flag; do NOT swap first.
+**Payment token:** every `amiko search <vertical>` subcommand and `markets image` accept `--token <AMIKO|USDC|USDT>` (default AMIKO); `markets service call` uses `--usdc`/`--usdt` (pass `auto` to price from USD). Stables are pinned at $1.00 — the amount equals the endpoint's USD price — so there is no forced swap through AMIKO. When the owner asks to pay in USDT/USDC, pass the flag; do NOT swap first.
 
 ## Create Studio — behavior notes
 
-`amiko create <image|video|tts|music|sfx>` is the CLI half of the platform Create Studio. It generates through Amiko's own authenticated endpoints (not raw MPP), runs **async**, and is **charged on success** from the twin's custodial wallet — a failed or timed-out generation is **never billed**, and there is no pre-pay. **The command returns immediately** with a `jobId` and `status: PENDING` — it does NOT block for the whole generation (so you're not held for 60s–9min). It prints how to check + a rough ETA. **Do NOT sit in a tight polling loop** (it burns turns/tokens). After submitting, **tell the user roughly how long to wait and stop** — image ~15–60s, video ~2–9min, music ~30–120s, tts/sfx ~5–20s (e.g. "your video's generating — check back in a few minutes"). Then retrieve it **once** later — when the user next asks, or after the ETA — with `amiko create status <jobId>` (re-query that job, ~24h) or `amiko create media` (list recent generations; `--service`/`--limit`/`--raw`). Result is a permanent Supabase Storage URL. **Every successful generation is also auto-saved to the drive** (folder "Create Studio Files", with the prompt as title/description) — so `amiko drive search "<prompt words>"` finds past creations, and `drive share <docId>` can hand out a link; no manual re-upload. **Do NOT use `--wait`** — there's no such option; `create` is always non-blocking, so submit then check later with `amiko create status <jobId>`. `--token <AMIKO|USDC|USDT|SOL>` selects the charge token (default auto, AMIKO-first). `--pay credits` pays from the owner's **Amiko account credits** instead of the twin wallet (unified-billing accounts only — reserved at submit, captured only on success, released on failure; the server rejects it for legacy accounts, so fall back to the default `--pay wallet` if it errors). Prefer `create` over `markets image` for media generation — it doesn't lose money on timeouts. `markets image` remains the raw MPP pre-pay path. For **music**, a plain prompt is enough — `create music "a triumphant orchestral ballad"` sings from the prompt (lyrics auto-written); add `--lyrics "…"` to set exact words, or `--instrumental` for no vocals. Don't paste long lyrics into the prompt itself. **Track length is `--duration <seconds>`** (1–300, same unit as `sfx --duration` and `video --seconds`) — e.g. a 3.5-minute track is `--duration 210`. On `music-3.0` this is the **price input**: it bills per second, so `--duration 210` costs 210× the per-second rate. Omit it for the 60s default; never put the length in the prompt text instead (the model can't act on it). **Image models** (`--model`): `nano-banana-2` (default), `nano-banana`, `nano-banana-lite`, `nano-banana-pro` (Google Gemini — when the owner says "nano banana", pass it verbatim; `-pro` is the premium/priciest tier at ~$0.17); `gpt-image-2` and `gpt-image-1.5/-1/-1-mini` (OpenAI); `grok-imagine-image-quality` (xAI); `image-01` (MiniMax).
+`amiko create <image|video|tts|music|sfx>` is the CLI half of the platform Create Studio. It generates through Amiko's own authenticated endpoints (not raw MPP), runs **async**, and is **charged on success** from the twin's custodial wallet — a failed or timed-out generation is **never billed**, and there is no pre-pay. **The command returns immediately** with a `jobId` and `status: PENDING` — it does NOT block for the whole generation (so you're not held for 60s–9min). It prints how to check + a rough ETA. **Do NOT sit in a tight polling loop** (it burns turns/tokens). After submitting, **tell the user roughly how long to wait and stop** — image ~15–60s, video ~2–9min, music ~30–120s, tts/sfx ~5–20s (e.g. "your video's generating — check back in a few minutes"). Then retrieve it **once** later — when the user next asks, or after the ETA — with `amiko create status <jobId>` (re-query that job, ~24h) or `amiko create media` (list recent generations; `--service`/`--limit`/`--raw`). Result is a permanent Supabase Storage URL. **Every successful generation is also auto-saved to the drive** (folder "Create Studio Files", with the prompt as title/description) — so `amiko drive search "<prompt words>"` finds past creations, and `drive share <docId>` can hand out a link; no manual re-upload. **Do NOT use `--wait`** — there's no such option; `create` is always non-blocking, so submit then check later with `amiko create status <jobId>`. `--token <AMIKO|USDC|USDT|SOL>` selects the charge token (default auto, AMIKO-first). `--pay credits` pays from the owner's **Amiko account credits** instead of the twin wallet (unified-billing accounts only — reserved at submit, captured only on success, released on failure; the server rejects it for legacy accounts, so fall back to the default `--pay wallet` if it errors). Prefer `create` over `markets image` for media generation — it doesn't lose money on timeouts. `markets image` remains the raw MPP pre-pay path. For **music**, a plain prompt is enough — `create music "a triumphant orchestral ballad"` sings from the prompt (lyrics auto-written); add `--lyrics "…"` to set exact words, or `--instrumental` for no vocals. Don't paste long lyrics into the prompt itself. **Track length is `--duration <seconds>`** (1–300, same unit as `sfx --duration` and `video --seconds`) — e.g. a 3.5-minute track is `--duration 210`. On `music-3.0` this is the **price input**: it bills per second, so `--duration 210` costs 210× the per-second rate. Omit it for the 60s default; never put the length in the prompt text instead (the model can't act on it). **Image models** (`--model`): `nano-banana-2` (default), `nano-banana`, `nano-banana-lite`, `nano-banana-pro` (Google Gemini — when the owner says "nano banana", pass it verbatim; `-pro` is the premium/priciest tier at ~$0.17); `gpt-image-2` and `gpt-image-1.5/-1/-1-mini` (OpenAI); `grok-imagine-image-quality` (xAI); `image-01` (MiniMax). Images also take `--reference-image <file|url>` for image-to-image — see "Reference limits" below.
 
 ### Video — critical agent rules (read before claiming failure)
 
@@ -158,16 +177,33 @@ This twin has **two** optional TTS ids. They are **not** the same:
 - **Cover art → motion (I2V):** pass the cover's Amiko URL as `--first-frame <url>` (from `amiko create status` on the image job or `amiko create media`). The default model is now **input-aware**: prompt-only video defaults to `MiniMax-Hailuo-02` (T2V), and `--first-frame` runs default to `MiniMax-Hailuo-2.3-Fast` (I2V) — so omitting `--model` is safe in both shapes. Explicit `--model` always wins; Fast alone still rejects prompt-only (it needs a reference image).
 - **Before giving up on video**, you must have: (1) submitted with `amiko create video … --yes`, (2) waited through the ETA, (3) run `amiko create status <jobId>` **or** `amiko create media --service video`. If `COMPLETED` + `assetUrl`, report success with the URL. If still `PROCESSING`, say it's still rendering — don't claim the pipeline is broken.
 
-**Video with reference assets** — frame/reference flags take **URLs or data URIs**, not local file paths. Generate or fetch assets first, then pass their Amiko/Supabase URLs from `amiko create status` or `amiko create media`.
+**Every media flag takes a local file path as well as a URL.** `create image --reference-image`, `create video --first-frame/--last-frame/--reference-image/--reference-video/--reference-audio/--subject-reference`, and `create music --audio-url` all accept a **local path** (uploaded for you, no `drive upload` step) or an **https URL** — so an image the owner just handed you, or a clip on disk, goes straight in. Amiko/Supabase URLs from `amiko create status` / `amiko create media` still work unchanged. Local paths are the better choice when they exist: the CLI reads the bytes, so it can also check clip **durations** before anything is billed.
+
+**Images take references too.** `create image "…" --reference-image <file|url>` is image-to-image. `nano-banana*` / `gpt-image*` accept up to **4** references (multi-anchor: style, subject, composition); `image-01` accepts **exactly 1** front-facing character portrait; `grok-imagine-image-quality` supports none — the CLI names an alternative instead of burning the generation.
 
 | Goal | Flow |
 |---|---|
+| Image-to-image | `create image "same character in the snow" --reference-image ./portrait.png --yes` |
 | Image-to-video (single start frame) | `create image "cover art" --yes` → later `create status <jobId>` for URL → `create video "animate this" --first-frame <url> --yes` |
 | First + last frame | `create video "morph between frames" --first-frame <startUrl> --last-frame <endUrl> --yes` |
-| Seedance multimodal refs | `create video "dance to this beat" --model dreamina-seedance-2-0-fast-260128 --reference-image <url> --reference-audio <audioUrl> --generate-audio --yes` (repeat `--reference-image` up to 9×, `--reference-video`/`--reference-audio` up to 3×) |
+| Seedance multimodal refs | `create video "dance to this beat" --model dreamina-seedance-2-0-fast-260128 --reference-image <url> --reference-audio ./beat.wav --generate-audio --yes` (repeat `--reference-image` up to 9×, `--reference-video`/`--reference-audio` up to 3×) |
 | MiniMax subject reference (S2V) | `create video "character walks forward" --subject-reference <portraitUrl> --yes` |
 | MiniMax H3 long clip (per-second billing) | `create video "slow pan over dunes at dusk" --model MiniMax-H3 --seconds 12 --resolution 2K --aspect 21:9 --yes` — quote first; cost scales with `--seconds`, and 2K bills more per second than 768P |
-| MiniMax H3 reference-to-video | `create video "same character, now dancing" --model MiniMax-H3 --reference-image <url> --reference-video <clipUrl> --yes` — never mix `--first-frame`/`--last-frame` with reference flags on H3; the CLI/server reject the combination |
+| MiniMax H3 reference-to-video | `create video "same character, now dancing" --model MiniMax-H3 --reference-image <url> --reference-video ./clip.mp4 --yes` — never mix `--first-frame`/`--last-frame` with reference flags on H3; the CLI/server reject the combination |
+
+**Reference limits, per family.** The CLI checks all of these **before** the quote, so a bad combination costs nothing. What it refuses is not pedantry: several providers accept the job, bill it, and silently ignore the media they don't read.
+
+| | reference images | reference video | reference audio | frames | notes |
+|---|---|---|---|---|---|
+| **MiniMax-H3** | 9 | 3 | 3 | `--first-frame`/`--last-frame` (either alone) | **12 files total**; frames and references are mutually exclusive (audio counts as a reference); each audio clip 2–15s; video+audio combined ≤15s |
+| **Seedance** | 9 | 3 | 3 | both, `--last-frame` needs `--first-frame` | frames exclusive with image/video references; audio needs an image or video reference beside it; video+audio combined ≤15s |
+| **Veo 3.1** | 3 | — | — | both, `--last-frame` needs `--first-frame` | frames exclusive with references; `-lite` is prompt-only |
+| **Grok** | 9 | — | — | `--first-frame` only | |
+| **Hailuo v1** (02 / 2.3 / 2.3-Fast) | — | — | — | `--first-frame` only | `--reference-image` is silently dropped — use `--subject-reference`, which Hailuo does read |
+
+`--subject-reference` **replaces** a reference-image slot rather than adding one (except on Hailuo v1, where it's a separate field). The ≤15s combined budget and H3's 2–15s per-clip audio window are checked from the **local file's bytes** — so they're verified for `.wav` / `.mp4` / `.mov` paths and skipped (allowed through) for https URLs and `.mp3`, where the server has the last word.
+
+**Provider toggles** (each has a `--no-…` form): `--generate-audio`, `--watermark`, `--camera-fixed` (Seedance); `--prompt-optimizer` (MiniMax H3 + Hailuo v1); `--fast-pretreatment` (Hailuo v1). Passing one to a model that ignores it is harmless — the server drops it.
 
 MiniMax Hailuo (02/2.3) is silent — there is no CLI mux step to attach a separate music track after the fact; use Seedance `--reference-audio` + `--generate-audio` when the owner wants audio baked into the video.