@heyamiko/amiko-cli 0.7.7 → 0.7.8

package/README.md

@@ -1,4 +1,4 @@
-# @heyamiko/amiko-cli (v0.7.0)
+# @heyamiko/amiko-cli (v0.7.8)
 
 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

package/package.json

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