@heyamiko/amiko-cli 0.10.1-beta.0 → 0.10.1-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -1
- package/package.json +1 -1
- package/skills/SKILL.md +101 -354
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# @heyamiko/amiko-cli (v0.10.1-beta.
|
|
1
|
+
# @heyamiko/amiko-cli (v0.10.1-beta.2)
|
|
2
2
|
|
|
3
3
|
Manage wallets, credits, swaps, MPP marketplace services, and your Amiko twin (identity, documents, voice, avatar, friends, feed, Composio apps) from the terminal. Works for both human users and AI agents running on OpenClaw.
|
|
4
4
|
|
|
@@ -393,6 +393,14 @@ npm publish
|
|
|
393
393
|
|
|
394
394
|
## Changelog
|
|
395
395
|
|
|
396
|
+
### 0.10.1-beta.2
|
|
397
|
+
|
|
398
|
+
- **SKILL.md slimmed ~55%** (31.6 KB / 429 lines → 14.3 KB / 169 lines; ~8.5k → ~3.5k tokens). The skill now leads with "this is the mental model, not a syntax reference — run `amiko <group> --help` for exact flags" and drops per-namespace bash blocks that duplicated `--help` output (credits/wallets/markets/account/docs/voice/avatar/friends/users/feed/posts/conversations/notifications/memory/composio/JSON). Kept everything the CLI's own help *can't* tell an agent: shell-tool invocation rule + "no `amiko_cli` tool exists" failure modes, the `--yes` / report-balance / no-retry critical rules, `--wallet` default behavior, the credits intent-mapping cheatsheet (1 SOL → `--spend`, $5 → `--usd`, 10000 → positional), wallets/markets/conversations behavior notes that aren't in help, the "relationship report" and "who should I meet" playbooks (`friends find` vs `users search` vs `friends matches`), feed/post draft-review workflow + "reading via CLI counts as reading", DM-vs-built-in-sessions routing, and the full memory `search-before-you-answer` doctrine. Pricing table replaced with a one-paragraph "run `markets service list` for live prices" pointer plus rough order-of-magnitude. Result: skill stays well within recommended SKILL.md size budget while preserving every judgment / mental-model line that agents can't learn from `--help`.
|
|
399
|
+
|
|
400
|
+
### 0.10.1-beta.1
|
|
401
|
+
|
|
402
|
+
- **SKILL.md** documents the two new feed/post surfaces so agents actually find them: top-of-file Examples table gets rows for "any new posts I haven't seen?" → `amiko feed --unread` and "what comments are on my post?" → `amiko post comments --id <postId>`; top-level command index updated; the Feed & Posts section gains a callout that *reading via the CLI counts as reading the post* (every `amiko feed` / `amiko post comments` call auto-marks for this twin, so successive `feed --unread` calls drain without bookkeeping; user-side reads are written by the web client only). No CLI behavior change.
|
|
403
|
+
|
|
396
404
|
### 0.10.1-beta.0
|
|
397
405
|
|
|
398
406
|
- **`amiko post comments --id <postId>`** (new): lists comments on a post via `GET /api/posts/[id]/comments`. Supports `--limit`, `--cursor`, `--replies` (include nested replies; default top-level only), `--json`. Closes a gap where the CLI could write a comment but couldn't read existing ones — agents previously only saw a `_count.comments` integer from `amiko feed`.
|
package/package.json
CHANGED
package/skills/SKILL.md
CHANGED
|
@@ -7,9 +7,11 @@ metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
|
|
|
7
7
|
|
|
8
8
|
# Amiko CLI
|
|
9
9
|
|
|
10
|
+
This file is the **mental model**, not a syntax reference. For exact flags and subcommands, run `amiko <group> --help` — the CLI's help is the authoritative source and stays in sync with each release.
|
|
11
|
+
|
|
10
12
|
## How to invoke — ALWAYS use your shell-execution tool
|
|
11
13
|
|
|
12
|
-
Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar) and run `amiko <subcommand>`. Amiko is a shell program, not a callable tool.
|
|
14
|
+
Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar) and run `amiko <subcommand>`. Amiko is a shell program, not a callable tool.
|
|
13
15
|
|
|
14
16
|
### Examples — copy this pattern
|
|
15
17
|
|
|
@@ -20,403 +22,148 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
|
|
|
20
22
|
| "swap 1 SOL to USDC" | shell → `amiko wallets swap quote 1 SOL USDC` (then send with `--yes` after approval) |
|
|
21
23
|
| "did anyone DM me?" | shell → `amiko conversation list` |
|
|
22
24
|
| "any notifications?" | shell → `amiko notifications list --unread` |
|
|
25
|
+
| "any new posts I haven't seen?" | shell → `amiko feed --unread` |
|
|
26
|
+
| "what comments are on my post?" | shell → `amiko post comments --id <postId>` |
|
|
23
27
|
| "search memory for X" | shell → `amiko memory search "X"` |
|
|
24
28
|
| "what can amiko do?" | shell → `amiko --help` |
|
|
25
29
|
|
|
26
|
-
The CLI is installed globally and is pre-authenticated when you're inside your workspace folder. Never suggest `amiko login` or `amiko connect
|
|
30
|
+
The CLI is installed globally and is pre-authenticated when you're inside your workspace folder. Never suggest `amiko login` or `amiko connect` — they don't exist.
|
|
27
31
|
|
|
28
32
|
### Failure modes to avoid
|
|
29
33
|
|
|
30
|
-
- A tool named `amiko_cli` / `amiko-cli` / `amiko` (or this skill's name) does **not** exist. The only path is the shell tool above. If you try to call any of those
|
|
31
|
-
- Do not invent intermediate "amiko" tools (`amiko.balance`,
|
|
32
|
-
|
|
33
|
-
##
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
| `amiko review <cmd>` | Review queue — list, approve, or reject twin-drafted comments |
|
|
50
|
-
| `amiko feed` | Read the friends feed, for-you feed, or filter by hashtag |
|
|
51
|
-
| `amiko composio <cmd>` | Connect / disconnect third-party OAuth apps (Gmail, GitHub, …) |
|
|
52
|
-
| `amiko conversation <cmd>` | DM/chat — list, find, create, send messages |
|
|
53
|
-
| `amiko notifications <cmd>` | Platform notifications — list, mark as read |
|
|
54
|
-
| `amiko memory <cmd>` | Cross-agent memory — `search` before answering personal questions, `add` what's worth remembering, `list` / `rm` / `status` / `sync` local memory files |
|
|
55
|
-
| `amiko accounts` | Show the resolved identity (authenticated, userId, twinId, platform) |
|
|
56
|
-
| `amiko info` | Show the active twin (name, description, public, voice, avatar) |
|
|
57
|
-
| `amiko config <cmd>` | Show resolved config |
|
|
58
|
-
| `amiko update` | Self-update the CLI |
|
|
59
|
-
|
|
60
|
-
All twin-scoped commands accept `--twin <id>` to target a non-default twin.
|
|
34
|
+
- A tool named `amiko_cli` / `amiko-cli` / `amiko` (or this skill's name) does **not** exist as a callable tool. The only path is the shell tool above. If you try to call any of those, the gateway returns `Tool ... not found` — and retries burn credits. Don't retry; re-route through the shell.
|
|
35
|
+
- Do not invent intermediate "amiko" tools (`amiko.balance`, etc.). Every action goes through one path: shell tool → `amiko <subcommand>`.
|
|
36
|
+
|
|
37
|
+
## Command groups
|
|
38
|
+
|
|
39
|
+
Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `wallets`, `credits`, `twin`, `docs`, `voice`, `avatar`, `friends`, `users`, `post`, `review`, `feed`, `composio`, `conversation`, `notifications`, `memory`, plus the top-level `accounts`, `info`, `config`, `update`. All twin-scoped commands accept `--twin <id>`. Most commands support `--json`.
|
|
40
|
+
|
|
41
|
+
## Critical Rules
|
|
42
|
+
|
|
43
|
+
1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `markets *`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` (and destructive ops like `twin update --public`, `docs delete`, `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `composio disconnect`, `review reject`) unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.**
|
|
44
|
+
2. **After every paid command, report the remaining balance.** The CLI prints a `Balance: N credits` line — include that figure in your reply.
|
|
45
|
+
3. **Never retry a failed command.** Report and stop. Every paid call costs tokens even on failure.
|
|
46
|
+
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`.
|
|
47
|
+
5. **Check balance before expensive ops.** Run `amiko credits balance` if unsure.
|
|
48
|
+
6. **Payments are custodied.** The platform signs and moves tokens from the twin's wallet — the CLI never holds keys.
|
|
49
|
+
|
|
50
|
+
### Quoting cost before running
|
|
51
|
+
|
|
52
|
+
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 (OpenAI pass-through × 1.30 markup).
|
|
61
53
|
|
|
62
54
|
## The `--wallet` default (read this before any paid command)
|
|
63
55
|
|
|
64
|
-
Every paid / value-moving command
|
|
56
|
+
Every paid / value-moving command spends from an on-chain wallet, but you almost never need `--wallet` explicitly:
|
|
65
57
|
|
|
66
|
-
- **Default**:
|
|
67
|
-
- **Override**: pass `--wallet <address>` only if you want a different wallet
|
|
68
|
-
- **No wallet yet?** The CLI
|
|
69
|
-
- **Bridges**: `wallets bridge quote/send`
|
|
58
|
+
- **Default**: CLI auto-selects the twin's first active **Solana** wallet.
|
|
59
|
+
- **Override**: pass `--wallet <address>` only if you want a different wallet.
|
|
60
|
+
- **No wallet yet?** The CLI tells you to run `amiko wallets create --chain solana`. One-shot per `chain+custodian`; reuse forever.
|
|
61
|
+
- **Bridges**: `wallets bridge quote/send` defaults `--depositor` to the wallet on the origin chain (Solana for `--from solana`, Base for `--from base`).
|
|
70
62
|
|
|
71
|
-
> Never prompt the user for
|
|
63
|
+
> Never prompt the user for a wallet address when the default works. Only surface `--wallet` if the command errors out.
|
|
72
64
|
|
|
73
|
-
##
|
|
65
|
+
## Credits — intent mapping
|
|
74
66
|
|
|
75
|
-
|
|
76
|
-
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.
|
|
77
|
-
3. **Never retry a failed command.** Report the error and stop. Every paid call costs tokens even on failure.
|
|
78
|
-
4. **Never suggest `amiko login` or `amiko connect`.** These don't exist. Auth is automatic when you run from your workspace folder.
|
|
79
|
-
5. **Check balance before expensive operations.** Run `amiko credits balance` first if unsure.
|
|
80
|
-
6. **Payments are automatic.** The platform signs and moves tokens from the twin's wallet for each paid call — the CLI never holds keys.
|
|
81
|
-
|
|
82
|
-
### Pricing cheat sheet (quote this to the user before running)
|
|
83
|
-
|
|
84
|
-
| Command | Cost |
|
|
85
|
-
|---------|------|
|
|
86
|
-
| `amiko markets search "<query>"` | 1 AMIKO |
|
|
87
|
-
| `amiko markets image "<prompt>"` | varies by model/quality/size (≈$0.005–$1.30 × 1.30 markup) |
|
|
88
|
-
| `amiko markets amazon search "<query>"` | 1 AMIKO |
|
|
89
|
-
| `amiko markets amazon quote <ASIN>` | Free |
|
|
90
|
-
| `amiko markets service tts <voiceId> "<text>"` | 1 AMIKO |
|
|
91
|
-
| `amiko markets service call POST /v1/sfx ...` | $0.05 |
|
|
92
|
-
| `amiko markets service call POST /v1/music ...` | $0.10 |
|
|
93
|
-
| `amiko markets service call POST /v1/music/plan ...` | $0.02 |
|
|
94
|
-
| `amiko wallets swap quote ...` | Free |
|
|
95
|
-
| `amiko wallets swap send ...` | Solana gas + 10bps |
|
|
96
|
-
| `amiko wallets transfer ...` | Chain gas only |
|
|
97
|
-
| `amiko credits topup ...` | Whatever amount you top up |
|
|
98
|
-
|
|
99
|
-
## Credits
|
|
100
|
-
|
|
101
|
-
**Display credits: 10,000 credits = $1.00 USD.**
|
|
102
|
-
|
|
103
|
-
```bash
|
|
104
|
-
amiko credits balance # show balance as "N credits"
|
|
105
|
-
amiko credits topup --spend 1 --token SOL --yes # "1 SOL worth of credits"
|
|
106
|
-
amiko credits topup --usd 5 --token USDC --yes # $5 paying in USDC
|
|
107
|
-
amiko credits topup 10000 --token AMIKO --yes # 10,000 credits = $1
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
`topup` accepts **one** of three amount forms:
|
|
111
|
-
|
|
112
|
-
| Form | Meaning | Example |
|
|
113
|
-
|------|---------|---------|
|
|
114
|
-
| `<amount>` (positional) | credits | `amiko credits topup 10000 --token AMIKO` |
|
|
115
|
-
| `--usd <n>` | US dollars | `amiko credits topup --usd 5 --token USDC` |
|
|
116
|
-
| `--spend <n>` | spend N of `--token` | `amiko credits topup --spend 1 --token SOL` |
|
|
117
|
-
|
|
118
|
-
Map user intent directly — no manual price math:
|
|
67
|
+
Display unit: **10,000 credits = $1.00 USD.** `topup` accepts one of three amount forms — map user intent directly, no manual price math:
|
|
119
68
|
|
|
120
69
|
- "top up 1 SOL of credits" → `--spend 1 --token SOL`
|
|
121
70
|
- "top up $5 in USDC" → `--usd 5 --token USDC`
|
|
122
|
-
- "top up 10000 credits with AMIKO" → `10000 --token AMIKO`
|
|
123
|
-
|
|
124
|
-
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.
|
|
125
|
-
|
|
126
|
-
## Wallets
|
|
127
|
-
|
|
128
|
-
```bash
|
|
129
|
-
amiko wallets list # all twin wallets + cached balances
|
|
130
|
-
amiko wallets create --chain solana # create a wallet (solana | base)
|
|
131
|
-
amiko wallets balance <address> # force-sync one wallet; returns fresh balances
|
|
132
|
-
amiko wallets transfer --to <addr> --amount 100 --token amiko --yes # send tokens out of a twin wallet
|
|
133
|
-
amiko wallets swap quote 1.0 SOL USDC # Jupiter quote (free)
|
|
134
|
-
amiko wallets swap send 1.0 SOL USDC --yes # --wallet defaults to your Solana wallet
|
|
135
|
-
amiko wallets swap tokens # supported tokens list
|
|
136
|
-
amiko wallets bridge quote 10 --from solana --to base --recipient <addr>
|
|
137
|
-
amiko wallets bridge send 10 --from solana --to base --recipient <addr> --yes
|
|
138
|
-
amiko wallets bridge status <txHash>
|
|
139
|
-
amiko wallets bridge routes
|
|
140
|
-
amiko wallets bridge limits
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
- `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.
|
|
144
|
-
- `wallets create` is one-shot per `chain+custodian` pair (409 if one already exists) — run once for the twin and reuse.
|
|
145
|
-
- `wallets transfer` sends tokens from a twin wallet to an external address. Only Crossmint-custodied wallets are supported (agent-signed on the server). `--wallet` defaults to your Solana wallet; pass `--chain base` + `--wallet` to send from a Base wallet. `--token` accepts symbols (`sol`, `usdc`, `usdt`, `amiko` on Solana; `eth` on Base) or a raw mint/contract address. Returns a tx hash once the transaction lands on-chain. Paid/destructive — requires `--yes` in non-interactive shells.
|
|
146
|
-
- Swaps run via Jupiter on Solana. Supported: SOL, USDC, USDT, AMIKO, PYUSD, BONK, JUP, RAY, JitoSOL — or any mint address.
|
|
147
|
-
- Bridging goes through Across Protocol. Solana ↔ EVM requires `--recipient` (different address formats).
|
|
148
|
-
|
|
149
|
-
## Market (paid MPP services)
|
|
150
|
-
|
|
151
|
-
```bash
|
|
152
|
-
amiko markets search "AI agents" # 1 AMIKO — X/Twitter search
|
|
153
|
-
amiko markets image "a sunset over mountains" --yes # gpt-image-2 high 1024² default — AMIKO @ OpenAI pass-through × 1.30
|
|
154
|
-
amiko markets image "logo" --background transparent # transparent bg
|
|
155
|
-
amiko markets image "portrait" --size 1024x1536 # portrait orientation
|
|
156
|
-
amiko markets image "icon" --model gpt-image-1-mini --quality low # cheapest tier
|
|
157
|
-
amiko markets amazon search "usb c cable" # 1 AMIKO — product search
|
|
158
|
-
amiko markets amazon quote B01GGKYKQM # free — price quote
|
|
159
|
-
amiko markets service list # all services + prices
|
|
160
|
-
amiko markets service call POST /v1/sfx '{"text":"thunder","duration_seconds":5}'
|
|
161
|
-
amiko markets service call POST /v1/music '{"prompt":"lo-fi beat","music_length_ms":30000}'
|
|
162
|
-
amiko markets service tts 21m00Tcm4TlvDq8ikWAM "Hello world"
|
|
163
|
-
amiko markets service call POST /v1/music/plan '{"prompt":"epic orchestral"}'
|
|
164
|
-
amiko markets service call <METHOD> <path> [body] # any MPP endpoint
|
|
165
|
-
amiko markets discover # service info + pricing
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
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.
|
|
169
|
-
|
|
170
|
-
## Account & Twin
|
|
171
|
-
|
|
172
|
-
```bash
|
|
173
|
-
amiko accounts # resolved identity (authenticated, userId, twinId, platform)
|
|
174
|
-
amiko info # twin info (name, description, public, voice, avatar)
|
|
175
|
-
amiko twin update --name "New Name"
|
|
176
|
-
amiko twin update --description "..."
|
|
177
|
-
amiko twin update --public true --yes # destructive — requires --yes in non-TTY
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
## Documents (RAG)
|
|
181
|
-
|
|
182
|
-
```bash
|
|
183
|
-
amiko docs list # list
|
|
184
|
-
amiko docs upload ./notes.pdf # path
|
|
185
|
-
amiko docs upload https://example.com/x.pdf # URL
|
|
186
|
-
cat file.pdf | amiko docs upload - --stdin --name file.pdf
|
|
187
|
-
amiko docs delete <docId> --yes # destructive
|
|
188
|
-
amiko docs presign ./file.pdf # presigned S3 URL only
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
## Voice
|
|
192
|
-
|
|
193
|
-
```bash
|
|
194
|
-
amiko voice design --description "warm, low, male, confident, measured" # min 20 chars
|
|
195
|
-
amiko voice create --sample <generated_voice_id>
|
|
196
|
-
amiko voice clone ./me.mp3 # path | URL | -
|
|
197
|
-
amiko voice reset --yes # destructive
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
## Avatar
|
|
201
|
-
|
|
202
|
-
```bash
|
|
203
|
-
amiko avatar update --file ./portrait.png --yes # max 5 MB, destructive
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
## Friends
|
|
207
|
-
|
|
208
|
-
```bash
|
|
209
|
-
amiko friends list # list all
|
|
210
|
-
amiko friends list --type user # filter
|
|
211
|
-
amiko friends requests # pending requests (incoming + outgoing)
|
|
212
|
-
amiko friends requests --direction incoming
|
|
213
|
-
amiko friends add --id <userId>
|
|
214
|
-
amiko friends accept <friendshipId>
|
|
215
|
-
amiko friends remove <friendshipId> --yes # destructive
|
|
216
|
-
amiko friends matches # pre-generated match candidates (from cron)
|
|
217
|
-
amiko friends matches --dimension personality
|
|
218
|
-
amiko friends find --relationship "cofounder with design taste" # on-demand LLM match for a custom relationship
|
|
219
|
-
amiko friends reports list # all reports (any status)
|
|
220
|
-
amiko friends reports pending # pending-consent: awaiting mine + awaiting theirs
|
|
221
|
-
amiko friends reports view <reportId>
|
|
222
|
-
amiko friends reports request --id <userId> --type friend|romantic|career --yes
|
|
223
|
-
amiko friends reports consent <reportId> # respondent approves; report then generates
|
|
224
|
-
amiko friends reports cancel <reportId>
|
|
225
|
-
amiko friends reports retry <reportId> # re-run a failed generation
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
### Answering relationship questions ("how is my relationship with X?")
|
|
229
|
-
|
|
230
|
-
When the user asks about their relationship / compatibility with a specific person (by name or handle), follow this playbook:
|
|
231
|
-
|
|
232
|
-
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.
|
|
233
|
-
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.
|
|
234
|
-
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`.
|
|
235
|
-
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).
|
|
236
|
-
|
|
237
|
-
Both users must have a personality profile, otherwise the request returns 422.
|
|
238
|
-
|
|
239
|
-
### Recommending interesting people ("who should I meet / connect with?")
|
|
240
|
-
|
|
241
|
-
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.
|
|
242
|
-
|
|
243
|
-
**`friends find` vs `users search` — do not confuse them:**
|
|
244
|
-
|
|
245
|
-
| Command | Purpose | Input | Backend |
|
|
246
|
-
|---|---|---|---|
|
|
247
|
-
| `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` |
|
|
248
|
-
| `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 |
|
|
249
|
-
|
|
250
|
-
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`.
|
|
251
|
-
|
|
252
|
-
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.
|
|
253
|
-
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.
|
|
254
|
-
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.
|
|
255
|
-
4. Skip anyone whose `friendship_status` is already `accepted` unless the user explicitly wants to revisit existing friends.
|
|
256
|
-
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`.
|
|
257
|
-
|
|
258
|
-
## Users
|
|
259
|
-
|
|
260
|
-
```bash
|
|
261
|
-
amiko users search <query> # search by name/handle
|
|
262
|
-
amiko users profile <handle> # public profile
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
## Feed & Posts
|
|
266
|
-
|
|
267
|
-
```bash
|
|
268
|
-
amiko feed # friends feed (default)
|
|
269
|
-
amiko feed --type for_you --limit 20
|
|
270
|
-
amiko feed --hashtag ai
|
|
271
|
-
amiko post create --content "hello from the CLI"
|
|
272
|
-
amiko post create --content "private note" --visibility private
|
|
273
|
-
amiko post create --content "look" --media https://...jpg
|
|
274
|
-
amiko post comment --id <postId> --comment "great post"
|
|
275
|
-
amiko post comment --id <postId> --comment "look" --media https://...jpg
|
|
276
|
-
amiko post comment --id <postId> --comment "..." --twin <id>
|
|
277
|
-
amiko review list # list twin-drafted comments awaiting your approval
|
|
278
|
-
amiko review approve <commentId> # publish a draft comment from the review queue
|
|
279
|
-
amiko review reject <commentId> --yes # destructive — delete a draft comment
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
**Comments authored by a twin always go through review.** Any comment created with `amiko post comment ... --twin <id>` (or auto-drafted by a twin in engagement mode) lands in `status=draft` and is **not visible** until you run `amiko review approve <commentId>`. Comments without `--twin` (you posting as yourself) publish immediately and skip the review queue. Workflow: `amiko review list` to see pending drafts → `amiko review approve <id>` to publish, or `amiko review reject <id> --yes` to discard.
|
|
283
|
-
|
|
284
|
-
## Conversations
|
|
285
|
-
|
|
286
|
-
> **Default platform = Amiko.** When the owner asks about messages, DMs, chats, notifications, or "anything new" **without naming a platform** (no "on WeChat", "on Telegram", "on Slack", etc.), assume they mean the Amiko platform and answer with `amiko conversation` / `amiko notifications`. Do **not** ask "which platform?" — just use the Amiko CLI. Only ask for clarification if the owner explicitly mentions a non-Amiko channel or the question is genuinely ambiguous across multiple connected channels.
|
|
287
|
-
>
|
|
288
|
-
> **When the owner asks about chat history with another person** ("did X message me?", "check my chat with Y", "anyone DM me this week?"), use `amiko conversation` — these are platform DMs between the owner and other Amiko users, stored in amiko-web's database. Do **not** use the built-in `sessions_list` / `sessions_history` tools for this: those read the agent's *own* past chat sessions with the owner (local openclaw memory), not platform DMs with third parties, and will return nothing useful. Typical flow: `amiko users search "<name>"` → `amiko conversation find --user-id <id>` → `amiko conversation read --id <conversationId>`. To scan everyone who messaged recently, start with `amiko conversation list` (sorted by last activity) or `amiko notifications list --unread`.
|
|
289
|
-
|
|
290
|
-
```bash
|
|
291
|
-
amiko conversation list # all your conversations (default: active)
|
|
292
|
-
amiko conversation list --archived all --limit 100 # include archived
|
|
293
|
-
amiko conversation find --user-id <userId> # is there an existing direct DM with this user?
|
|
294
|
-
amiko conversation create --user-id <userId> # create or reuse a direct DM (idempotent)
|
|
295
|
-
amiko conversation read --id <conversationId> # read recent messages (oldest-first)
|
|
296
|
-
amiko conversation read --id <id> --before-cursor <next_cursor> # page older messages
|
|
297
|
-
amiko conversation send --id <conversationId> --message "hi" # send a text message
|
|
298
|
-
amiko conversation send --id <id> --message "ok" --reply-to <messageId>
|
|
299
|
-
amiko conversation send --id <id> --message "agent reply" --as-agent # send as twin (sender_type=agent)
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
- `list` and `find` query amiko-web's `/api/conversations` (Prisma-backed). `find` filters client-side for a 2-user direct conversation containing both you and `--user-id`.
|
|
303
|
-
- `create` POSTs to `/api/conversations` with `conversation_type=direct`. The server reuses an existing conversation if one already exists between the two users (`reused_existing: true` in the JSON response), so calling it repeatedly is safe.
|
|
304
|
-
- `read` queries amiko-web's `GET /api/conversations/<id>/messages` (paginated by `next_cursor`, oldest-first per page).
|
|
305
|
-
- `send` posts to amiko-web's `POST /api/conversations/<id>/messages` with the Clawd twin token. The server persists the message and fans it out to other participants via the WebSocket broadcast.
|
|
306
|
-
- `--user-id` expects the **internal** user id (the one returned by `amiko users search`), not a Privy DID or handle.
|
|
307
|
-
|
|
308
|
-
## Notifications
|
|
309
|
-
|
|
310
|
-
```bash
|
|
311
|
-
amiko notifications list # recent platform notifications (default 20)
|
|
312
|
-
amiko notifications list --unread # only unread
|
|
313
|
-
amiko notifications list --cursor <iso> # page older items
|
|
314
|
-
amiko notifications read --id <notificationId> # mark one read
|
|
315
|
-
amiko notifications read --all # mark all read
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
Platform notifications cover friend requests, mentions, system alerts, and other activity that doesn't belong to any conversation. Use this when the user asks "any notifications?" or "what's new on the platform?". Notifications belonging to a conversation (new DM, comment on your post) still show up here when the platform writes one — they don't replace `conversation read` for actual chat content.
|
|
71
|
+
- "top up 10000 credits with AMIKO" → positional `10000 --token AMIKO`
|
|
319
72
|
|
|
320
|
-
|
|
73
|
+
Supported: AMIKO, SOL, USDC, USDT. Balance can lag a few seconds after topup — re-run `credits balance` if stale.
|
|
321
74
|
|
|
322
|
-
|
|
75
|
+
## Wallets — behavior notes
|
|
323
76
|
|
|
324
|
-
**
|
|
77
|
+
- `wallets list` returns **cached** balances. If stale, run `wallets balance <address>` to force a sync.
|
|
78
|
+
- `wallets create` is one-shot per `chain+custodian` (409 if one exists).
|
|
79
|
+
- `wallets transfer` only works for Crossmint-custodied wallets. `--token` accepts symbols (`sol`, `usdc`, `usdt`, `amiko` on Solana; `eth` on Base) or a raw mint/contract address.
|
|
80
|
+
- Swaps run via Jupiter on Solana. Bridges run via Across; Solana ↔ EVM requires `--recipient` (different address formats).
|
|
325
81
|
|
|
326
|
-
|
|
327
|
-
2. **Sync periodically.** Run `amiko memory sync` whenever you've meaningfully edited the local `MEMORY.md` / `memory/**/*.md` files, and at least once at the end of any session in which they changed. The platform only sees what you push.
|
|
82
|
+
## Markets — behavior notes
|
|
328
83
|
|
|
329
|
-
|
|
330
|
-
amiko memory search "git workflow" --limit 5 # hybrid (vector + FTS); query in any language
|
|
331
|
-
amiko memory list --limit 25 # newest-first, paginate with --offset
|
|
332
|
-
amiko memory list --category preference # filter: fact | preference | pattern | decision | context
|
|
333
|
-
amiko memory add "Owner prefers terse PR descriptions" --category preference --tags pr,style
|
|
334
|
-
amiko memory rm <memoryId> # soft-delete
|
|
335
|
-
amiko memory status # totals
|
|
336
|
-
amiko memory sync # one-way upload of local memory files to the platform
|
|
337
|
-
```
|
|
84
|
+
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.
|
|
338
85
|
|
|
339
|
-
|
|
86
|
+
## Friends & relationships
|
|
340
87
|
|
|
341
|
-
###
|
|
88
|
+
### "How is my relationship with X?" playbook
|
|
342
89
|
|
|
343
|
-
**
|
|
90
|
+
1. **Resolve to a user id**: `amiko friends list --json` first; if not a friend, `amiko users search "<name>" --json`. If ambiguous, ask.
|
|
91
|
+
2. **Check for an existing report**: `amiko friends reports list --json`, filter by `initiator.id` / `respondent.id`. If `completed` → `reports view <id>`. If `pending_consent` / `generating` → say so.
|
|
92
|
+
3. **None exists?** Don't silently create. Ask which type (`friend` / `romantic` / `career`); confirm the other user will be notified. Then `amiko friends reports request --id <userId> --type <type> --yes`.
|
|
93
|
+
4. **"Who's waiting on whom"**: `amiko friends reports pending` splits into *awaiting my consent* (`consent <id>`) vs *awaiting theirs* (`cancel <id>`). Use this before `request` — the API returns 409 on duplicate active reports for the same pair+type.
|
|
344
94
|
|
|
345
|
-
|
|
95
|
+
Both users must have a personality profile (else 422).
|
|
346
96
|
|
|
347
|
-
|
|
348
|
-
Examples: "what do I usually use for X", "how do I normally do Y", "what's my preferred tool for Z", "what's my coding style". Pass a short paraphrase as the query.
|
|
349
|
-
2. **Callbacks to prior context.** "as I mentioned", "like last time", "you know the one", "we discussed before", "what was that X we set up".
|
|
350
|
-
3. **Named entities specific to this owner.** Their project / repo / service / team / tool name. A person by name.
|
|
351
|
-
4. **Past bugs, decisions, investigations, design choices.**
|
|
352
|
-
5. **Start of a new session** where they reference anything about themselves or their work.
|
|
97
|
+
### "Who should I meet?" — `friends find` vs `users search` vs `friends matches`
|
|
353
98
|
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
99
|
+
| Command | Purpose | Input |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| `users search <query>` | **Look up a known person** by name/handle | Exact/substring text |
|
|
102
|
+
| `friends find --relationship <text>` | **Discover unknown people** matching a free-form relationship description | "cofounder with design taste" |
|
|
103
|
+
| `friends matches` | **Pre-curated** personality-match candidates from cron | (no input) |
|
|
357
104
|
|
|
358
|
-
|
|
105
|
+
Workflow: start with `friends matches --limit 20 --json`; narrow with `--dimension personality` or `--dimension interest` (the only two dimensions the cron produces). For specific kinds not covered → `friends find` (LLM-backed, ~10s, may return 0). Skip anyone with `friendship_status=accepted` unless explicitly asked. Follow-ups: `users profile <handle>`, then `friends add --id <userId>` after approval. Report `--type` is unrelated to `match.relationship_type`.
|
|
359
106
|
|
|
360
|
-
|
|
107
|
+
## Feed, Posts & Review
|
|
361
108
|
|
|
362
|
-
|
|
109
|
+
**Reading a post via the CLI counts as reading it.** Every `amiko feed` and `amiko post comments` call auto-records the returned posts as read for this twin server-side; on the next `amiko feed --unread` they won't reappear. No manual "mark read" command exists. (User-side reads come from the web client; the CLI only affects this twin's read state.)
|
|
363
110
|
|
|
364
|
-
|
|
365
|
-
- Making an architecture decision → save reasoning as `decision`
|
|
366
|
-
- Discovering a useful pattern or workaround → `pattern`
|
|
367
|
-
- Owner explicitly says "remember this" / "save this" / "from now on..." → match the category to the content
|
|
368
|
-
- Learning a preference you'd otherwise have to re-ask ("I prefer rg", "I always use pnpm") → `preference`
|
|
111
|
+
**Comments authored by a twin always go through review.** Any comment created with `amiko post comment ... --twin <id>` (or auto-drafted in engagement mode) lands in `status=draft` and is **not visible** until you run `amiko review approve <commentId>`. Comments without `--twin` (the owner posting) publish immediately. Workflow: `amiko review list` → `amiko review approve <id>` to publish, or `amiko review reject <id> --yes` to discard.
|
|
369
112
|
|
|
370
|
-
|
|
113
|
+
## Conversations & Notifications
|
|
371
114
|
|
|
372
|
-
|
|
115
|
+
> **Default platform = Amiko.** When the owner asks about messages/DMs/chats/notifications **without naming a platform**, assume Amiko and answer with `amiko conversation` / `amiko notifications`. Do **not** ask "which platform?". Only ask if they explicitly mention a non-Amiko channel.
|
|
116
|
+
>
|
|
117
|
+
> **For chat history with another person** ("did X message me?", "check my chat with Y"), use `amiko conversation`. Do **NOT** use built-in `sessions_list` / `sessions_history` — those read the agent's *own* local sessions with the owner, not platform DMs with third parties, and will return nothing useful. Typical flow: `amiko users search "<name>"` → `amiko conversation find --user-id <id>` → `amiko conversation read --id <conversationId>`.
|
|
373
118
|
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
| `context` | Project context, deadlines, ongoing work, transient state |
|
|
119
|
+
Behavior notes:
|
|
120
|
+
- `conversation find` filters client-side for a 2-user direct conversation containing both you and `--user-id`.
|
|
121
|
+
- `conversation create` is idempotent — server reuses an existing direct DM (`reused_existing: true`).
|
|
122
|
+
- `--user-id` expects the **internal** user id (from `amiko users search`), not a Privy DID or handle.
|
|
123
|
+
- `conversation send --as-agent` sends as the twin (`sender_type=agent`).
|
|
124
|
+
- Platform notifications cover friend requests, mentions, system alerts, and post-related events. They don't replace `conversation read` for actual chat content.
|
|
381
125
|
|
|
382
|
-
|
|
383
|
-
- Trivial facts obvious from the code itself or generic programming knowledge.
|
|
384
|
-
- Ephemeral state already captured by `git log` / the current diff.
|
|
385
|
-
- Duplicates — `memory search` first; if a near-match exists, skip or `rm` the old one before adding.
|
|
126
|
+
## Memory (cross-agent) — READ THIS BEFORE ANSWERING ANYTHING ABOUT THE OWNER
|
|
386
127
|
|
|
128
|
+
Memories are scoped to the **owner's `user_id`**, not your agent — every agent the owner runs reads and writes the same pool. Your local `memory/` folder is one input; the platform is the source of truth across sessions and agents.
|
|
387
129
|
|
|
388
|
-
|
|
130
|
+
**Two non-negotiable habits:**
|
|
131
|
+
|
|
132
|
+
1. **Search before you answer.** Run `amiko memory search "<query>"` **every time** the owner asks anything about themselves, their work, or their history — *before* composing a reply. Another agent may have written a memory you've never seen. A miss costs ~100ms; an amnesic answer costs trust.
|
|
133
|
+
2. **Sync periodically.** Run `amiko memory sync` whenever you've meaningfully edited local `MEMORY.md` / `memory/**/*.md`, and at least once at the end of any session in which they changed.
|
|
134
|
+
|
|
135
|
+
### When to search — bias toward calling
|
|
136
|
+
|
|
137
|
+
The single most common failure mode is NOT calling `memory search` on abstract self-referential questions. If the owner's message has any of these shapes, you MUST search — no judgment, no exceptions:
|
|
389
138
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
139
|
+
1. **Preference / habit questions**, even without a specific entity. "what do I usually use for X", "what's my coding style".
|
|
140
|
+
2. **Callbacks to prior context.** "as I mentioned", "like last time", "what was that X we set up".
|
|
141
|
+
3. **Named entities specific to this owner** — their project / repo / service / team / tool / a person by name.
|
|
142
|
+
4. **Past bugs, decisions, investigations, design choices.**
|
|
143
|
+
5. **Start of a new session** where they reference anything about themselves or their work.
|
|
395
144
|
|
|
396
|
-
|
|
145
|
+
Do NOT search for purely textbook programming questions, or things the current code / `git log` answers directly.
|
|
397
146
|
|
|
398
|
-
|
|
147
|
+
**When unsure, search.** Empty results cost nothing. Missing context costs trust.
|
|
399
148
|
|
|
400
|
-
|
|
401
|
-
amiko config show # resolved config
|
|
402
|
-
amiko update # self-update
|
|
403
|
-
amiko --help # top-level help
|
|
404
|
-
amiko <group> --help # e.g. `amiko wallets --help`
|
|
405
|
-
```
|
|
149
|
+
### When to save (`amiko memory add`)
|
|
406
150
|
|
|
407
|
-
|
|
151
|
+
- Fixing a non-obvious bug → `pattern` or `fact`
|
|
152
|
+
- Architecture decision → `decision`
|
|
153
|
+
- Useful pattern or workaround → `pattern`
|
|
154
|
+
- "Remember this" / "save this" / "from now on..." → match category to content
|
|
155
|
+
- Preference you'd otherwise re-ask ("I prefer rg", "I always use pnpm") → `preference`
|
|
408
156
|
|
|
409
|
-
|
|
157
|
+
Write memories as **standalone sentences with full context** — include names, not pronouns. Bad: "He prefers it that way." Good: "William prefers terse PR descriptions in the Amiko-Layer repo."
|
|
410
158
|
|
|
411
|
-
|
|
412
|
-
amiko wallets list --json | jq '.wallets[].wallet_address'
|
|
413
|
-
amiko friends list --json | jq '.friends[] | .friend.name'
|
|
414
|
-
amiko info --json | jq -r '.name'
|
|
415
|
-
```
|
|
159
|
+
Categories: `fact` | `preference` | `pattern` | `decision` | `context`.
|
|
416
160
|
|
|
417
|
-
|
|
161
|
+
Do NOT save trivial code-derivable facts, ephemeral `git log` state, or duplicates (search first; `rm` near-matches before adding).
|
|
418
162
|
|
|
419
|
-
|
|
163
|
+
## Composio
|
|
164
|
+
|
|
165
|
+
`composio connect --app <app>` is safe to call as a status check — idempotent, never destroys an existing connection. Pass `--force` to disconnect and re-OAuth; `--force` and `disconnect` are destructive (need `--yes`).
|
|
166
|
+
|
|
167
|
+
## Where to run
|
|
420
168
|
|
|
421
|
-
|
|
422
|
-
- If anything looks off, run `amiko accounts` — it prints the resolved `userId` and `twinId` so you can confirm scope.
|
|
169
|
+
**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. Run from the wrong folder and you'll act on the wrong twin or fail auth. Before the first call in a session, `cd` into the workspace. `amiko accounts` confirms the resolved scope.
|