@heyamiko/amiko-cli 0.9.0-beta.7 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.9.0-beta.7",
+  "version": "0.9.0",
   "description": "Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace agents",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target node --format esm",
+    "prepublishOnly": "bun run build",
     "dev": "bun run src/index.ts",
     "typecheck": "bun x tsc --noEmit",
     "test": "bun test"

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: amiko-cli
-description: Token swaps, credits, marketplace (search/image/amazon/audio), and twin/social operations on Amiko
+description: The Amiko CLI lets an agent act on the Amiko platform end-to-end — manage Solana/Base wallets (create, swap via Jupiter, bridge USDC via Across), top up and spend credits, call paid MPP marketplace services (X/Twitter search, image generation, Amazon product search, TTS/STT, AI chat, SFX/music), manage the twin's identity and RAG documents, voice and avatar, social graph (friends, posts, comments, feed), and Composio OAuth connections. Auth is automatic when run from the agent's workspace folder; payments are platform-custodied (no keys on disk). Use this skill whenever the user asks to do anything that would show up in their Amiko account or cost AMIKO/credits.
 homepage: https://platform.heyamiko.com
 metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
 ---
@@ -11,24 +11,50 @@ metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
 
 Run `amiko <command>` via your **shell execution tool** (e.g. `bash`). This skill is documentation, not a callable tool. **Do NOT** try to call `amiko_cli`, `amiko-cli`, `amiko`, or this skill's name as a tool — no such tool exists. The only working invocation is the shell command `amiko`.
 
-The `amiko` CLI is installed globally. Auth is automatic via `.amiko.json` (walking up from cwd, falling back to `/data/.openclaw/workspace/.amiko.json`) — never suggest `amiko login` or `amiko connect`.
+The `amiko` CLI is installed globally. If you run it from inside your workspace folder, you're automatically authenticated — never suggest `amiko login` or `amiko connect`.
+
+## Top-level commands at a glance
+
+Each row is a first-level command group or command. Start here when the user asks what the CLI can do.
+
+| Command | What it does |
+|---------|--------------|
+| `amiko markets <cmd>` | Paid MPP services: X search, image gen, Amazon, TTS/STT/chat, generic service call, discover |
+| `amiko wallets <cmd>` | Wallet ops: create, list, sync balance, swap on Solana (Jupiter), bridge USDC cross-chain (Across) |
+| `amiko credits <cmd>` | Show credit balance, top up with AMIKO/SOL/USDC/USDT (10,000 credits = $1) |
+| `amiko twin <cmd>` | Update the twin's identity — name, description, public visibility |
+| `amiko docs <cmd>` | Manage twin RAG documents — list, upload (path/URL/stdin), delete, presign |
+| `amiko voice <cmd>` | Design/clone/reset the twin's voice, create a voice from sample |
+| `amiko avatar <cmd>` | Set the twin's avatar image (max 5 MB) |
+| `amiko friends <cmd>` | Social graph — list, requests, add, accept, remove, matches, reports |
+| `amiko users <cmd>` | Search users, view public profile |
+| `amiko post <cmd>` | Create posts and comments on the feed (optionally with media) |
+| `amiko feed` | Read the friends feed, for-you feed, or filter by hashtag |
+| `amiko composio <cmd>` | Connect / disconnect third-party OAuth apps (Gmail, GitHub, …) |
+| `amiko accounts` | Show the resolved identity (authenticated, userId, twinId, platform) |
+| `amiko info` | Show the active twin (name, description, public, voice, avatar) |
+| `amiko config <cmd>` | Show resolved config |
+| `amiko update` | Self-update the CLI |
 
-## Command layout (v0.9+)
+All twin-scoped commands accept `--twin <id>` to target a non-default twin.
+
+## The `--wallet` default (read this before any paid command)
 
-The top level has three groups:
+Every paid command (`markets search`, `markets image`, `markets amazon search`, `markets service *`, `wallets swap send`) spends tokens from an on-chain wallet. As of v0.9.0-beta.9 you almost never need to pass `--wallet` explicitly:
 
-- `amiko market <cmd>` — paid MPP services (search, image, amazon, service, discover)
-- `amiko wallets <cmd>` — wallet operations (list, balance, swap, bridge)
-- `amiko credits <cmd>` — credit balance and topup
+- **Default**: the CLI auto-selects the twin's first active **Solana** wallet from `GET /api/agents/{id}/wallets`.
+- **Override**: pass `--wallet <address>` only if you want a different wallet than the default.
+- **No wallet yet?** The CLI will tell you to run `amiko wallets create --chain solana` first. Create once per twin; reuse forever.
+- **Bridges**: `wallets bridge quote/send` similarly default `--depositor` to the wallet on the origin chain (Solana for `--from solana`, Base for `--from base`).
 
-Plus subcommand groups: `twin <action>`, `docs <action>`, `voice <action>`, `avatar <action>`, `friends <action>`, `post <action>`, `composio <action>`. Plus flat commands: `config`, `update`, `accounts`, `info`, `feed`.
+> Never prompt the user for their wallet address when the default would work. Only surface `--wallet` if the command errors out saying there's no default.
 
 ## Critical Rules
 
-1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI *refuses* to run `market image`, `market search`, `market amazon search`, `market service call`, `market service tts`, `market service stt`, `market service chat`, `credits topup`, `wallets swap send`, or `wallets bridge send` unless `--yes` is passed. The refusal is loud: it prints the cost and the command you should re-run. **Quote the cost to the user, get explicit approval, THEN append `--yes`**. Same for destructive non-paid commands (`twin update --public`, `docs delete`, `friends remove`, `avatar update`, `voice reset`, `composio disconnect`).
+1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI *refuses* to run `markets image`, `markets search`, `markets amazon search`, `markets service call`, `markets service tts`, `markets service stt`, `markets service chat`, `credits topup`, `wallets swap send`, or `wallets bridge send` unless `--yes` is passed. The refusal is loud: it prints the cost and the command you should re-run. **Quote the cost to the user, get explicit approval, THEN append `--yes`**. Same for destructive non-paid commands (`twin update --public`, `docs delete`, `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `composio disconnect`).
 2. **After every paid command, report the remaining balance.** The CLI prints a `Balance: N credits` line at the end of every paid command — include that figure in your reply.
 3. **Never retry a failed command.** Report the error and stop. Every paid call costs tokens even on failure.
-4. **Never suggest `amiko login` or `amiko connect`.** These don't exist. Auth is automatic via `.amiko.json`.
+4. **Never suggest `amiko login` or `amiko connect`.** These don't exist. Auth is automatic when you run from your workspace folder.
 5. **Check balance before expensive operations.** Run `amiko credits balance` first if unsure.
 6. **Payments are automatic.** The platform signs and moves tokens from the twin's wallet for each paid call — the CLI never holds keys.
 
@@ -36,14 +62,14 @@ Plus subcommand groups: `twin <action>`, `docs <action>`, `voice <action>`, `ava
 
 | Command | Cost |
 |---------|------|
-| `amiko market search "<query>"` | 1 AMIKO |
-| `amiko market image "<prompt>"` | 5 AMIKO |
-| `amiko market amazon search "<query>"` | 1 AMIKO |
-| `amiko market amazon quote <ASIN>` | Free |
-| `amiko market service tts <voiceId> "<text>"` | 1 AMIKO |
-| `amiko market service call POST /v1/sfx ...` | $0.05 |
-| `amiko market service call POST /v1/music ...` | $0.10 |
-| `amiko market service call POST /v1/music/plan ...` | $0.02 |
+| `amiko markets search "<query>"` | 1 AMIKO |
+| `amiko markets image "<prompt>"` | 5 AMIKO |
+| `amiko markets amazon search "<query>"` | 1 AMIKO |
+| `amiko markets amazon quote <ASIN>` | Free |
+| `amiko markets service tts <voiceId> "<text>"` | 1 AMIKO |
+| `amiko markets service call POST /v1/sfx ...` | $0.05 |
+| `amiko markets service call POST /v1/music ...` | $0.10 |
+| `amiko markets service call POST /v1/music/plan ...` | $0.02 |
 | `amiko wallets swap quote ...` | Free |
 | `amiko wallets swap send ...` | Solana gas + 10bps |
 | `amiko credits topup ...` | Whatever amount you top up |
@@ -73,46 +99,48 @@ Map user intent directly — no manual price math:
 - "top up $5 in USDC" → `--usd 5 --token USDC`
 - "top up 10000 credits with AMIKO" → `10000 --token AMIKO`
 
-Supported tokens: AMIKO, SOL, USDC, USDT. The CLI fetches the live price, the platform transfers from the twin's wallet, and on-chain verification credits the account.
+Supported tokens: AMIKO, SOL, USDC, USDT. The CLI fetches the live price, the platform transfers from the twin's wallet, and on-chain verification credits the account. Balance can lag by a few seconds after topup — re-run `amiko credits balance` if it looks stale.
 
 ## Wallets
 
 ```bash
 amiko wallets list                                   # all twin wallets + cached balances
+amiko wallets create --chain solana                  # create a wallet (solana | base)
 amiko wallets balance <address>                      # force-sync one wallet; returns fresh balances
 amiko wallets swap quote 1.0 SOL USDC                # Jupiter quote (free)
-amiko wallets swap send 1.0 SOL USDC --wallet <addr> --yes
+amiko wallets swap send 1.0 SOL USDC --yes           # --wallet defaults to your Solana wallet
 amiko wallets swap tokens                            # supported tokens list
-amiko wallets bridge quote 10 --from solana --to tempo
-amiko wallets bridge send 10 --from solana --to tempo --yes
+amiko wallets bridge quote 10 --from solana --to tempo --recipient <addr>
+amiko wallets bridge send 10 --from solana --to tempo --recipient <addr> --yes
 amiko wallets bridge status <txHash>
 amiko wallets bridge routes
 amiko wallets bridge limits
 ```
 
-`wallets list` returns cached balances (platform doesn't auto-sync). If balances look stale, run `wallets balance <address>` to force a sync for that wallet.
-
-Swaps run via Jupiter on Solana. Supported: SOL, USDC, USDT, AMIKO, PYUSD, BONK, JUP, RAY, JitoSOL — or any mint address. Bridging goes through Across Protocol.
+- `wallets list` returns **cached** balances (platform doesn't auto-sync). If they look stale, run `wallets balance <address>` to force a sync for that wallet.
+- `wallets create` is one-shot per `chain+custodian` pair (409 if one already exists) — run once for the twin and reuse.
+- Swaps run via Jupiter on Solana. Supported: SOL, USDC, USDT, AMIKO, PYUSD, BONK, JUP, RAY, JitoSOL — or any mint address.
+- Bridging goes through Across Protocol. Solana ↔ EVM requires `--recipient` (different address formats).
 
 ## Market (paid MPP services)
 
 ```bash
-amiko market search "AI agents"                      # 1 AMIKO — X/Twitter search
-amiko market image "a sunset over mountains" --yes   # 5 AMIKO — gpt-image-1 by default
-amiko market image "logo" --background transparent   # transparent bg
-amiko market image "portrait" --size 1024x1792       # custom size
-amiko market amazon search "usb c cable"             # 1 AMIKO — product search
-amiko market amazon quote B01GGKYKQM                 # free — price quote
-amiko market service list                            # all services + prices
-amiko market service call POST /v1/sfx '{"text":"thunder","duration_seconds":5}'
-amiko market service call POST /v1/music '{"prompt":"lo-fi beat","music_length_ms":30000}'
-amiko market service tts 21m00Tcm4TlvDq8ikWAM "Hello world"
-amiko market service call POST /v1/music/plan '{"prompt":"epic orchestral"}'
-amiko market service call <METHOD> <path> [body]     # any MPP endpoint
-amiko market discover                                # service info + pricing
+amiko markets search "AI agents"                      # 1 AMIKO — X/Twitter search
+amiko markets image "a sunset over mountains" --yes   # 5 AMIKO — gpt-image-1 by default
+amiko markets image "logo" --background transparent   # transparent bg
+amiko markets image "portrait" --size 1024x1792       # custom size
+amiko markets amazon search "usb c cable"             # 1 AMIKO — product search
+amiko markets amazon quote B01GGKYKQM                 # free — price quote
+amiko markets service list                            # all services + prices
+amiko markets service call POST /v1/sfx '{"text":"thunder","duration_seconds":5}'
+amiko markets service call POST /v1/music '{"prompt":"lo-fi beat","music_length_ms":30000}'
+amiko markets service tts 21m00Tcm4TlvDq8ikWAM "Hello world"
+amiko markets service call POST /v1/music/plan '{"prompt":"epic orchestral"}'
+amiko markets service call <METHOD> <path> [body]     # any MPP endpoint
+amiko markets discover                                # service info + pricing
 ```
 
-Paid market commands require `--wallet <address>` (the Solana wallet that pays) unless one can be resolved from `.amiko.json`. Audio and image endpoints return permanent Supabase Storage URLs.
+All paid markets commands auto-select the twin's active Solana wallet. Pass `--wallet <address>` only to override. Audio and image endpoints return permanent Supabase Storage URLs.
 
 ## Account & Twin
 
@@ -124,8 +152,6 @@ amiko twin update --description "..."
 amiko twin update --public true --yes            # destructive — requires --yes in non-TTY
 ```
 
-All twin-scoped commands accept `--twin <id>` to target a non-default twin.
-
 ## Documents (RAG)
 
 ```bash
@@ -157,9 +183,58 @@ amiko avatar update --file ./portrait.png --yes  # max 5 MB, destructive
 ```bash
 amiko friends list                               # list all
 amiko friends list --type user                   # filter
+amiko friends requests                           # pending requests (incoming + outgoing)
+amiko friends requests --direction incoming
 amiko friends add --id <userId>
 amiko friends accept <friendshipId>
 amiko friends remove <friendshipId> --yes        # destructive
+amiko friends matches                            # pre-generated match candidates (from cron)
+amiko friends matches --dimension personality
+amiko friends find --relationship "cofounder with design taste"  # on-demand LLM match for a custom relationship
+amiko friends reports list                       # all reports (any status)
+amiko friends reports pending                    # pending-consent: awaiting mine + awaiting theirs
+amiko friends reports view <reportId>
+amiko friends reports request --id <userId> --type friend|romantic|career --yes
+amiko friends reports consent <reportId>         # respondent approves; report then generates
+amiko friends reports cancel <reportId>
+amiko friends reports retry <reportId>           # re-run a failed generation
+```
+
+### Answering relationship questions ("how is my relationship with X?")
+
+When the user asks about their relationship / compatibility with a specific person (by name or handle), follow this playbook:
+
+1. **Resolve the person to a user id.** Check `amiko friends list --json` first. If not a friend, try `amiko users search "<name>" --json`. If still ambiguous, ask the user which one they mean.
+2. **Look for an existing report.** Run `amiko friends reports list --json` and filter by `initiator.id` or `respondent.id` matching the resolved user id. If one exists with `status=completed`, use `amiko friends reports view <id>` and summarize. If `status=pending_consent` or `generating`, tell the user it is in progress.
+3. **If none exists**, don't silently create one. Ask the user which of the three report types they want (`friend` / `romantic` / `career`), and confirm that the other user will be notified to consent. Only then run `amiko friends reports request --id <userId> --type <type> --yes`.
+4. **For "who is waiting on whom"**, use `amiko friends reports pending` — it splits `pending_consent` reports into *awaiting my consent* (I can `consent <id>`) vs *awaiting theirs* (I can `cancel <id>`). Use this before deciding to `request` — you cannot have two active reports of the same type between the same pair (the API returns 409).
+
+Both users must have a personality profile, otherwise the request returns 422.
+
+### Recommending interesting people ("who should I meet / connect with?")
+
+The discovery primitive is **`amiko friends matches`** — it returns personality-match candidates with a score (0–1), a match dimension, a pairing label, and compatibility highlights.
+
+**`friends find` vs `users search` — do not confuse them:**
+
+| Command | Purpose | Input | Backend |
+|---|---|---|---|
+| `users search <query>` | **Look up a specific known person** by name or handle ("find wendao", "search for someone called Sophie") | Exact/substring text against `name` / `handle` | Simple SQL lookup in `/api/search?type=people` |
+| `friends find --relationship <text>` | **Discover unknown people** whose personality matches a free-form relationship description ("cofounder with design taste", "someone to hike with") | Free-form relationship description | LLM-generated MatchingSpec + semantic matching across ~250 candidate profiles |
+
+Rule of thumb: if the user already has a name in mind → `users search`. If the user is describing what *kind of person* they want to meet → `friends find`. For already-curated ambient recommendations with no input required → `friends matches`.
+
+1. Start broad: `amiko friends matches --limit 20 --json`. Summarize the top few by `display_name`, `score`, `match_dimension`, `pairing_label`, and `recommendation_reason`. These are pre-generated by a cron job.
+2. If the user wants to narrow, filter by `--dimension personality` or `--dimension interest` (the only two dimensions the matching cron actually produces). `--relationship-type` also exists but takes free-form LLM-generated labels (often localized, e.g. `深度思维_对打手`) — usually not worth filtering on unless you first inspect the `--json` output to pick a known value.
+3. If the user describes a **specific kind of person** not covered by the cron matches ("a cofounder who is good at design", "a hiking buddy", "someone to debate philosophy with"), use `amiko friends find --relationship "<description>"`. This is an on-demand, LLM-backed matcher against ~250 candidates; may take ~10s and may return zero matches if nothing clears the internal score threshold.
+4. Skip anyone whose `friendship_status` is already `accepted` unless the user explicitly wants to revisit existing friends.
+5. Follow-ups: `amiko users profile <handle>` for a fuller view, `amiko friends add --id <matched_user_id>` (after explicit user approval) to send a friend request, and — once the friendship is accepted — `amiko friends reports request --type friend|romantic|career` for a deeper compatibility report. Note that report `--type` is a separate enum and has nothing to do with `match.relationship_type`.
+
+## Users
+
+```bash
+amiko users search <query>                       # search by name/handle
+amiko users profile <handle>                     # public profile
 ```
 
 ## Feed & Posts
@@ -198,6 +273,13 @@ Most commands support `--json` for structured output:
 
 ```bash
 amiko wallets list --json | jq '.wallets[].wallet_address'
-amiko friends --json | jq '.items[] | .friend.name'
+amiko friends list --json | jq '.friends[] | .friend.name'
 amiko info --json | jq -r '.name'
 ```
+
+## Where to run
+
+**Each agent must run `amiko` from inside its own workspace directory.** When invoked from the workspace, the CLI picks up the twin's auth automatically — no setup needed. Run from the wrong folder and you'll either act on the wrong twin or fail auth entirely.
+
+- Before the first `amiko` call in a session, `cd` into the agent's workspace folder.
+- If anything looks off, run `amiko accounts` — it prints the resolved `userId` and `twinId` so you can confirm scope.