@heyamiko/amiko-cli 0.7.7 → 0.7.9

package/README.md

@@ -1,4 +1,4 @@
-# @heyamiko/amiko-cli (v0.7.0)
+# @heyamiko/amiko-cli (v0.7.9)
 
 Manage wallets, credits, swaps, and MPP marketplace services from the terminal. Works for both human users and AI agents running on OpenClaw.
 
@@ -63,23 +63,43 @@ amiko whoami                      # show current auth status
 
 ```bash
 amiko credits balance             # credit balance + wallet balances across all chains
-amiko credits topup <amount>      # top up credits (amount in credits, e.g. 10000)
+amiko credits topup <amount>      # top up credits (positional amount is credits)
 ```
 
-**Top-up options:**
+**10,000 credits = $1.00 USD.**
+
+**Three input forms — pick one.** The topup command accepts exactly one of:
+
+| Form | Meaning | Example |
+|------|---------|---------|
+| `<amount>` (positional) | credits | `topup 10000 --token AMIKO` → 10,000 credits = $1 |
+| `--usd <n>` | US dollars | `topup --usd 5 --token USDC` → $5 = 50,000 credits |
+| `--spend <n>` | spend N of `--token`, price-converted live | `topup --spend 1 --token SOL` → "1 SOL worth of credits" |
+
+Map user intent directly to the form, no manual price math needed:
+
+```bash
+amiko credits topup --spend 1 --token SOL          # "1 SOL worth of credits"
+amiko credits topup --spend 1 --token USDC         # "1 USDC worth of credits"
+amiko credits topup --usd 5 --token USDC           # "$5 worth of credits"
+amiko credits topup 10000 --token AMIKO            # 10,000 credits in AMIKO
+```
+
+**Confirmation.** Every topup prints a `Top-up Summary` (credits, cost in tokens, USD, source wallet) and then waits at `Proceed? [y/N]` on stdin. Pass `--yes` to skip (only after you've shared the summary with the user).
+
+**Other flags:**
 
 ```bash
-amiko credits topup 10000                             # auto-select best wallet + token
-amiko credits topup 10000 --token AMIKO               # use AMIKO (Solana)
-amiko credits topup 10000 --token USDC --chain base   # use USDC on Base
-amiko credits topup 5000 --method mpp                 # use MPP 402 payment
-amiko credits topup 10000 --wallet Gu2b...QVya        # specific wallet address
-amiko credits topup 10000 --yes                       # skip confirmation
+amiko credits topup 10000 --token USDC --chain base   # USDC on Base
+amiko credits topup 5000 --method mpp                 # MPP 402 payment
+amiko credits topup 10000 --wallet Gu2b...QVya        # specific wallet
 ```
 
 **Supported tokens:** AMIKO, SOL, USDC, USDT
 **Supported chains:** Solana, Base, Ethereum, Tempo
 
+**After every paid command, the CLI prints a `Balance: N credits (~$X.XX)` line** so agents can relay the remaining balance to the user without a separate `credits balance` call.
+
 ## Search
 
 ```bash
@@ -103,6 +123,8 @@ amiko image "banner" --raw                               # raw JSON
 
 Costs 5 AMIKO per image. Returns a Supabase Storage URL.
 
+Image generation typically takes 20–60s. In non-TTY environments (agents, piped shells), the CLI prints a `…still working (Ns elapsed)` tick to stderr every 3s so the parent process can tell it hasn't hung.
+
 ## Amazon
 
 ```bash
@@ -167,6 +189,19 @@ amiko service call POST /v1/music/plan '{"prompt":"Epic orchestral piece"}'
 
 Audio and image endpoints upload to Supabase Storage and return permanent URLs.
 
+## Error Output
+
+When a paid command fails (payment already sent, but the upstream service returned 4xx/5xx), the CLI prints the actual upstream response body so you can see the real failure reason:
+
+```
+Service call failed: 400 Bad Request
+Response body:
+Prompt failed upstream content moderation. Try rephrasing.
+Payment tx: https://solscan.io/tx/2mtcNTkYksJz2j15...
+```
+
+JSON `error` / `message` / `detail` fields are extracted when present; raw body up to 2000 chars otherwise. Agents should relay this verbatim to the user instead of guessing at reasons.
+
 ## Wallet
 
 ```bash
@@ -186,10 +221,21 @@ amiko wallet fund                        # fund via Tempo dashboard
 amiko discovery                          # MPP service info + pricing
 amiko config show                        # view config
 amiko config set <key> <value>           # set config value
-amiko update                             # update CLI to latest
+amiko update                             # update CLI to latest (full twin refresh — no restart needed)
 amiko --help                             # all commands
 ```
 
+### `amiko update` on twins
+
+On Claude/Amiko twin containers, the CLI is persisted to `/data/.amiko-cli/` so updates survive restarts, and `/usr/local/bin/amiko` is symlinked into that directory. Running `amiko update`:
+
+1. `npm install -g @heyamiko/amiko-cli@latest` (global package update)
+2. If `/data/.amiko-cli/` exists (i.e. we're on a twin), copy the new package over it
+3. Refresh the `/usr/local/bin/amiko` symlink
+4. Copy the updated `skills/SKILL.md` to both `/data/.openclaw/skills/amiko-cli/` and `/data/.openclaw/workspace/skills/amiko-cli/` so the agent sees the new docs immediately
+
+The result is a one-shot upgrade — no container redeploy required. On non-twin machines (local dev, CI) step (2)–(4) are skipped.
+
 ## Agent Integration (OpenClaw)
 
 ### Install as OpenClaw plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace agents",
   "type": "module",
   "bin": {

package/skills/SKILL.md

@@ -147,7 +147,7 @@ amiko bridge send 10 --from solana --to tempo    # execute bridge
 amiko wallet balance [address]                   # USDC.e balance on Tempo
 amiko discovery                                  # MPP service info + pricing
 amiko config show                                # view config
-amiko update                                     # update CLI to latest
+amiko update                                     # update CLI to latest (on twins: also refreshes /data, symlink, skill)
 amiko --help                                     # all commands
 ```