@heyamiko/amiko-cli 0.14.0-beta.23 → 0.14.0-beta.24

package/README.md

@@ -1,4 +1,4 @@
-# @heyamiko/amiko-cli (v0.14.0-beta.15)
+# @heyamiko/amiko-cli (v0.14.0-beta.24)
 
 Manage wallets, credits, swaps, MPP marketplace services, and your Amiko twin (identity, documents, voice, avatar, friends, feed) from the terminal. Works for both human users and AI agents running on OpenClaw.
 
@@ -581,6 +581,9 @@ amiko friends requests                  # pending requests (incoming + outgoing)
 amiko friends add --id <userId>
 amiko friends accept <friendshipId>
 amiko friends remove <friendshipId> --yes
+amiko friends nickname                  # every private nickname you've set
+amiko friends nickname set Sophie "Soph" --yes    # set/change (name, @handle, user id, or friendship id)
+amiko friends nickname remove Sophie --yes        # clear it
 amiko friends matches                   # personality match candidates
 amiko friends reports list              # friend matching reports
 amiko friends reports view <reportId>
@@ -604,7 +607,7 @@ amiko post comment --id <postId> --comment "nice!" --media https://...jpg
 
 Every new command accepts `--json` for structured output and `--twin <id>` where a target twin is needed.
 
-**Destructive or identity-changing commands** (`docs delete`, `friends remove`, `voice reset`, `avatar update`, `twin update --public`) prompt for confirmation in a TTY and require `--yes` in non-interactive shells.
+**Destructive or identity-changing commands** (`docs delete`, `friends remove`, `friends nickname set/remove`, `voice reset`, `avatar update`, `twin update --public`) prompt for confirmation in a TTY and require `--yes` in non-interactive shells.
 
 ## API Endpoints
 
@@ -622,6 +625,10 @@ npm publish
 
 ## Changelog
 
+### 0.14.0-beta.24
+
+- **Private friend nicknames: `amiko friends nickname`.** Manage the owner's private nicknames for friends against amiko-web `/api/friends/{friendshipId}/nickname`: bare `nickname` (or `nickname list`) pages the whole friends list and shows every nickname set, `set <friend> "<nickname>"` adds or changes one (max 50 characters, validated client-side before any request), `remove <friend>` clears it (soft no-op when none is set). `<friend>` resolves against accepted user friends only — by name, `@handle`, user id, friendship id, or the current nickname — with ambiguity reported, never guessed. Mutations are `--yes`-gated (private resource, plain confirm); `amiko friends list` now also renders a NICKNAME column. **Requires the companion amiko-web deploy (`feat/friend-nicknames`)** — on an older server, reads work but `set`/`remove` return 403 (the CLI prints the deploy hint).
+
 ### 0.14.0-beta.23
 
 - **Chat lists: `amiko chat lists`.** View and manage the owner's private conversation folders against amiko-web `/api/chat-lists`: bare `lists` renders every list with conversation names resolved, plus `create` / `rename` / `add` / `remove` / `delete` subcommands (all `--yes`-gated). The server stores a wholesale `conversation_ids` array, so `add`/`remove` read the current array, mutate locally, and PATCH it back — existing entries always survive an `add`. `--conversation` targets resolve like `chat send` (id / user id / `@handle` / group title / name) but map people to their **existing** DM only — list organization never creates a conversation.

package/dist/index.js

@@ -30449,6 +30449,196 @@ async function mppFriendReportGenerate(auth, body, opts = {}) {
   }
 }
 
+// src/lib/nickname.ts
+var NICKNAME_MAX_CODE_POINTS = 50;
+var CONTROL_CHARS = /\p{Cc}/u;
+function validateNickname(input) {
+  if (CONTROL_CHARS.test(input)) {
+    return {
+      ok: false,
+      error: "invalid_characters",
+      message: "Nickname contains unsupported characters (control characters are not allowed)."
+    };
+  }
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return { ok: false, error: "empty", message: "Nickname is empty." };
+  }
+  if ([...trimmed].length > NICKNAME_MAX_CODE_POINTS) {
+    return {
+      ok: false,
+      error: "too_long",
+      message: `Nickname is too long (max ${NICKNAME_MAX_CODE_POINTS} characters).`
+    };
+  }
+  return { ok: true, value: trimmed };
+}
+
+// src/commands/friends-nickname.ts
+function exitWithError3(e5, fallback2) {
+  console.error(error(e5 instanceof Error ? e5.message : fallback2));
+  process.exit(1);
+}
+function friendLabel(f) {
+  const name = f.friend.name ?? f.friend.id;
+  return f.friend.handle ? `${name} (@${f.friend.handle})` : name;
+}
+async function fetchUserFriends(auth) {
+  const limit = 100;
+  const all = [];
+  for (let offset = 0;offset < 1e4; offset += limit) {
+    const data = await amikoWebFetch(auth, "/api/friends", {
+      query: { type: "user", limit, offset },
+      timeoutMs: 20000
+    });
+    const page = data.friends ?? [];
+    all.push(...page);
+    if (page.length < limit || data.pagination?.has_more === false)
+      break;
+  }
+  return all;
+}
+async function resolveFriend(auth, target) {
+  const t = target.trim();
+  if (!t) {
+    throw new Error("No friend given. Pass a name, @handle, user id, or friendship id.");
+  }
+  const all = await fetchUserFriends(auth);
+  const asId = normalizeUserId(t);
+  const byId = all.find((f) => f.friendship_id === asId || f.friend.id === asId);
+  if (byId)
+    return byId;
+  if (t.startsWith("@")) {
+    const handle = t.slice(1).toLowerCase();
+    const byHandle = all.filter((f) => f.friend.handle?.toLowerCase() === handle);
+    if (byHandle.length === 1)
+      return byHandle[0];
+    throw new Error(`No friend ${t}. Nicknames only work for accepted friends — run \`amiko friends list\`.`);
+  }
+  const lower = t.toLowerCase();
+  const exact = all.filter((f) => f.friend.name?.toLowerCase() === lower || f.friend.handle?.toLowerCase() === lower || f.nickname?.toLowerCase() === lower);
+  const matches = exact.length ? exact : all.filter((f) => f.friend.name?.toLowerCase().includes(lower) || f.friend.handle?.toLowerCase().includes(lower) || f.nickname?.toLowerCase().includes(lower));
+  if (matches.length === 0) {
+    throw new Error(`No friend matching "${t}". Nicknames only work for accepted friends — run \`amiko friends list\`.`);
+  }
+  if (matches.length > 1) {
+    const names = matches.map((f) => `${friendLabel(f)} (${f.friend.id})`).join(", ");
+    throw new Error(`"${t}" is ambiguous — matches: ${names}. Use the friend's @handle or user id.`);
+  }
+  return matches[0];
+}
+async function resolveFriendOrExit(auth, target) {
+  try {
+    return await resolveFriend(auth, target);
+  } catch (e5) {
+    exitWithError3(e5, "Could not resolve the friend");
+  }
+}
+async function patchNickname(auth, friendshipId, nickname, spinner) {
+  try {
+    const data = await amikoWebFetch(auth, `/api/friends/${encodeURIComponent(friendshipId)}/nickname`, { method: "PATCH", body: { nickname }, timeoutMs: 20000 });
+    spinner?.stop();
+    return data;
+  } catch (e5) {
+    spinner?.stop();
+    if (e5.status === 403) {
+      console.error(error(e5 instanceof Error ? e5.message : "Forbidden"));
+      console.error(dim("Tip: nickname writes need an amiko-web deploy that allows twin tokens to manage nicknames (feat/friend-nicknames)."));
+      process.exit(1);
+    }
+    exitWithError3(e5, "Failed to update the nickname");
+  }
+}
+async function runList(opts) {
+  const auth = authOrExit();
+  const spinner = opts.json ? null : ora("Loading nicknames...").start();
+  let all;
+  try {
+    all = await fetchUserFriends(auth);
+  } catch (e5) {
+    spinner?.stop();
+    exitWithError3(e5, "Failed to load friends");
+  }
+  spinner?.stop();
+  const named = all.filter((f) => !!f.nickname);
+  renderOutput({
+    nicknames: named.map((f) => ({
+      nickname: f.nickname ?? null,
+      user_id: f.friend.id,
+      name: f.friend.name ?? null,
+      handle: f.friend.handle ?? null,
+      friendship_id: f.friendship_id
+    }))
+  }, () => {
+    if (named.length === 0) {
+      console.log(dim("No nicknames set."));
+      console.log(dim('Set one with `amiko friends nickname set <friend> "<nickname>"`.'));
+      return;
+    }
+    console.log(heading(`Nicknames (${named.length})`));
+    const rows = [
+      [
+        dim("NICKNAME"),
+        dim("NAME"),
+        dim("HANDLE"),
+        dim("USER ID"),
+        dim("FRIENDSHIP")
+      ],
+      ...named.map((f) => [
+        f.nickname ?? "-",
+        f.friend.name ?? "-",
+        f.friend.handle ?? "-",
+        f.friend.id,
+        f.friendship_id
+      ])
+    ];
+    console.log(table(rows));
+  }, { json: opts.json });
+}
+function registerFriendsNicknameCommand(nickname) {
+  nickname.option("--json", "Output as JSON").action(runList);
+  nickname.command("list").description("List every nickname you've set").option("--json", "Output as JSON").action((_opts, cmd) => runList(cmd.optsWithGlobals()));
+  nickname.command("set <friend> <nickname>").description("Set or change your private nickname for a friend (name, @handle, user id, or friendship id)").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--json", "Output as JSON").action(async (target, rawNickname, _opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const checked = validateNickname(rawNickname);
+    if (!checked.ok) {
+      console.error(error(checked.message));
+      if (checked.error === "empty") {
+        console.error(dim(`Tip: to clear a nickname, run \`amiko friends nickname remove ${JSON.stringify(target)}\`.`));
+      }
+      process.exit(1);
+    }
+    const auth = authOrExit();
+    const friend = await resolveFriendOrExit(auth, target);
+    await confirmDestructive({
+      action: friend.nickname ? `Change your private nickname for ${friendLabel(friend)} from "${friend.nickname}" to "${checked.value}"` : `Set your private nickname for ${friendLabel(friend)} to "${checked.value}"`,
+      detail: "Nicknames are private — only you ever see them, in every Amiko app.",
+      yes: opts.yes,
+      commandExample: `amiko friends nickname set ${JSON.stringify(target)} ${JSON.stringify(checked.value)}`
+    });
+    const spinner = opts.json ? null : ora("Saving nickname...").start();
+    const data = await patchNickname(auth, friend.friendship_id, checked.value, spinner);
+    renderOutput(data, (d) => console.log(success(`${friendLabel(friend)} is now "${d.nickname}" to you`)), { json: opts.json });
+  });
+  nickname.command("remove <friend>").description("Remove your private nickname for a friend").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--json", "Output as JSON").action(async (target, _opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const auth = authOrExit();
+    const friend = await resolveFriendOrExit(auth, target);
+    if (!friend.nickname) {
+      renderOutput({ nickname: null }, () => console.log(dim(`No nickname set for ${friendLabel(friend)}.`)), { json: opts.json });
+      return;
+    }
+    await confirmDestructive({
+      action: `Remove your private nickname "${friend.nickname}" for ${friendLabel(friend)}`,
+      yes: opts.yes,
+      commandExample: `amiko friends nickname remove ${JSON.stringify(target)}`
+    });
+    const spinner = opts.json ? null : ora("Removing nickname...").start();
+    const data = await patchNickname(auth, friend.friendship_id, null, spinner);
+    renderOutput(data, () => console.log(success(`Nickname removed — ${friendLabel(friend)} shows their real name again`)), { json: opts.json });
+  });
+}
+
 // src/commands/friends.ts
 async function runPaidRegenerate(args) {
   let auth;
@@ -30577,6 +30767,7 @@ function registerFriendsCommand(program2) {
           [
             dim("USER ID"),
             dim("NAME"),
+            dim("NICKNAME"),
             dim("HANDLE"),
             dim("TYPE"),
             dim("FRIENDSHIP"),
@@ -30585,6 +30776,7 @@ function registerFriendsCommand(program2) {
           ...items.map((f) => [
             f.friend.id,
             f.friend.name ?? "-",
+            f.nickname ?? "-",
             f.friend.handle ?? "-",
             f.friend.type,
             f.friendship_id,
@@ -30689,6 +30881,8 @@ Accept with: amiko friends accept <friendshipId>`));
       process.exit(1);
     }
   });
+  const nickname = program2.command("nickname").description("Private nicknames for friends — set, remove, list (only you ever see them)");
+  registerFriendsNicknameCommand(nickname);
   const reports = program2.command("reports").description("Friend matching reports");
   reports.command("list").description("List friend matching reports").option("--page <n>", "Page number", "1").option("--limit <n>", "Page size (1-50)", "20").option("--json", "Output as JSON").action(async (opts) => {
     const auth = resolveAuth();
@@ -32032,7 +32226,7 @@ var twin = program2.command("twin").description("Update twin identity (name, des
 var drive = program2.command("drive").alias("docs").description("Manage twin drive — upload/download/search files, organise into folders");
 var voice = program2.command("voice").description("Manage twin voice — design, create, clone, reset");
 var avatar = program2.command("avatar").description("Manage twin avatar image");
-var friends = program2.command("friends").description("Manage friendships — list, requests, add, accept, remove, reports, matches");
+var friends = program2.command("friends").description("Manage friendships — list, requests, add, accept, remove, nicknames, reports, matches");
 var users = program2.command("users").description("Search users and view public profiles");
 var post = program2.command("post").description("Create posts and comments on the feed");
 var review = program2.command("review").description("Review queue — list, approve, or reject twin-drafted comments");

package/package.json

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

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: amiko-cli
-description: The Amiko CLI lets an agent act on the Amiko platform end-to-end — read platform notifications (friend requests, mentions, system alerts), search and write **cross-agent memories** about the owner (what other agents already know — preferences, decisions, facts), manage Solana/Base wallets (create, swap via Jupiter, bridge USDC via Across, transfer tokens to external addresses), top up and spend credits, generate media — images, video, speech, music, and SFX — via Create Studio (`amiko create`, async and charged on success), call paid MPP marketplace services (X/Twitter search, Amazon product search, TTS/STT, AI chat), manage the twin's identity and drive (files, folders, RAG), voice and avatar, and social graph (friends, posts, comments, feed). Auth is automatic when run from the agent's workspace folder; payments are platform-custodied (no keys on disk). The owner's DMs and group chats are `amiko chat` (list / read / send / mark everything read / see which chats have unread @mentions or replies to the owner (`chat list --mentions`) / organize chats into private folders (`chat lists`) / create + manage group chats AS the owner, including sending GIFs (`chat gifs` search + `chat send --gif`), sharing a group's invite/join link + QR and @all group announcements, 人对人); the agent's OWN sessions are the openhermit gateway's session_list / session_send (AS the agent) — different identities, different surfaces. Use this skill whenever the user asks about their Amiko notifications, chats/DMs, drive, memory, social graph, wallets, credits, or marketplace services — anything that would show up in their Amiko account or cost AMIKO/credits.
+description: The Amiko CLI lets an agent act on the Amiko platform end-to-end — read platform notifications (friend requests, mentions, system alerts), search and write **cross-agent memories** about the owner (what other agents already know — preferences, decisions, facts), manage Solana/Base wallets (create, swap via Jupiter, bridge USDC via Across, transfer tokens to external addresses), top up and spend credits, generate media — images, video, speech, music, and SFX — via Create Studio (`amiko create`, async and charged on success), call paid MPP marketplace services (X/Twitter search, Amazon product search, TTS/STT, AI chat), manage the twin's identity and drive (files, folders, RAG), voice and avatar, and social graph (friends, private friend nicknames, posts, comments, feed). Auth is automatic when run from the agent's workspace folder; payments are platform-custodied (no keys on disk). The owner's DMs and group chats are `amiko chat` (list / read / send / mark everything read / see which chats have unread @mentions or replies to the owner (`chat list --mentions`) / organize chats into private folders (`chat lists`) / create + manage group chats AS the owner, including sending GIFs (`chat gifs` search + `chat send --gif`), sharing a group's invite/join link + QR and @all group announcements, 人对人); the agent's OWN sessions are the openhermit gateway's session_list / session_send (AS the agent) — different identities, different surfaces. Use this skill whenever the user asks about their Amiko notifications, chats/DMs, drive, memory, social graph, wallets, credits, or marketplace services — anything that would show up in their Amiko account or cost AMIKO/credits.
 homepage: https://platform.heyamiko.com
 metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
 ---
@@ -43,6 +43,8 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
 | "mark all my chats as read" | shell → `amiko chat mark-read --all --yes` (after the owner confirms — it clears every badge and senders see read ticks) |
 | "any unread mentions or replies to me?" | shell → `amiko chat list --mentions` (chats whose unread messages @mention the owner or reply to them) |
 | "what chat lists do I have? what's in my Work list?" | shell → `amiko chat lists` |
+| "call Sophie 'Soph' from now on" | shell → `amiko friends nickname set Sophie "Soph" --yes` (after the owner confirms) |
+| "what nicknames have I given my friends?" | shell → `amiko friends nickname` |
 | "add the team group to my Work list" | shell → `amiko chat lists add "Work" --conversation "<group>" --yes` |
 | "what can amiko do?" | shell → `amiko --help` |
 | "what's my MiniMax / ElevenLabs voice id?" | shell → `amiko info` |
@@ -63,7 +65,7 @@ Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `
 
 ## 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), `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 `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`.
@@ -200,6 +202,15 @@ The drive is **shared between the user and the agent** — anything either side
 
 ## Friends & relationships
 
+### Private nicknames — `amiko friends nickname`
+
+The owner's private pet names for friends. **Only the owner ever sees a nickname** — it becomes that friend's display name across the owner's feed, chats, and profile views; the friend is never notified and never sees it. Nicknames exist only for **accepted, person-to-person** friends (not twins, not pending requests).
+
+- `amiko friends nickname` (or `... nickname list`) — every nickname the owner has set. Ungated read; `--json` for ids.
+- `amiko friends nickname set <friend> "<nickname>"` — set or change (max 50 characters). `<friend>` takes a name, `@handle`, user id, or friendship id — and also matches the **current nickname** ("rename Soph to Sophy" works). Ambiguity errors listing candidates; ask the owner, don't guess.
+- `amiko friends nickname remove <friend>` — clear it (the friend's real name shows again). Removing when none is set is a harmless no-op.
+- `set`/`remove` are `--yes`-gated. They're private — confirm the action itself; never mention cost or "other people will see this."
+
 ### "How is my relationship with X?" playbook
 
 1. **Resolve to a user id**: `amiko friends list --json` first; if not a friend, `amiko users search "<name>" --json`. If ambiguous, ask.