@heyditto/cli 1.5.0 → 1.7.0

package/README.md

@@ -4,7 +4,7 @@
 
 ```bash
 npm install -g @heyditto/cli
-heyditto init --agent --agent-caller "NAME_OF_AGENT" --json   # the name is set once, here
+heyditto init --name "NAME_OF_AGENT" --json   # the name is set once, here
 
 heyditto save "I prefer TypeScript over JS for new projects"
 heyditto search "language preferences"
@@ -45,7 +45,7 @@ You can also reorder your `PATH` so the npm global bin comes before `/usr/bin`,
 Agents can self-provision without a browser, email, or OTP:
 
 ```bash
-heyditto init --agent --json
+heyditto init --json
 ```
 
 The command creates a free claimable agent account, stores the key in
@@ -56,16 +56,16 @@ that link. The claim token is carried in the query string (`?t=...`).
 
 ### Name the agent at init
 
-Decide the agent's name **before** you run `init` and pass it with `--agent-caller`:
+Decide the agent's name **before** you run `init` and pass it with `--name`:
 
 ```bash
-heyditto init --agent --agent-caller "NAME_OF_AGENT" --json
+heyditto init --name "NAME_OF_AGENT" --json
 ```
 
 The caller name is set **once, at account creation**, and it labels everything
 the agent saves: after a human claims the account, the agent's memories show up
 in the owner's graph as an *external agent thread* titled by this name. If you
-init without `--agent-caller`, the name defaults to `agent` and every memory is
+init without `--name`, the name defaults to `agent` and every memory is
 labeled `agent` — generic and hard to tell apart from other agents.
 
 So: use the agent's own name, or a name the user has already chosen, and set it
@@ -88,19 +88,43 @@ heyditto save <content> [--source <s>] [--source-context <c>]
 heyditto search <query>... [--include-public] [--filter-username <u>]
 heyditto fetch <id>... [--memory-format full|outline|blocks]
 heyditto list [--username <u>] [--limit <n>] [--offset <n>] [--source <s>]
+heyditto my-memories [--limit <n>] [--offset <n>] [--source <s>]
 heyditto update <id> [--content <text>|--content-file <path>] [--title <t>]
              [--source-context <c>] [--edits-json <json>|--edits-file <path>]
              [--base-revision <n>]
 heyditto publish <id> [--title <t>] [--privacy-mode <mode>]
 heyditto unpublish (--memory-id <id>|--share-id <id>|<id>)
+heyditto delete <memory-id> --confirm
 heyditto subjects <query> [--top-k <n>]
+heyditto subject-edges <subject-id> [--limit <n>] [--min-weight <n>] [--kg <alias>]
 heyditto memories <subject-id>... [--query <q>]
 heyditto network <pair-id> [--limit <n>]
-heyditto graphs create <name> | list | add <@username> | remove <@username> | subscribers
-heyditto init --agent [--agent-caller <name>] [--json]
-heyditto status
+heyditto friends
+heyditto knowledge-graphs
+heyditto graph-sharing (--enable|--disable) [--title <t>] [--description <d>]
+heyditto graphs create <name>
+heyditto graphs list
+heyditto graphs available
+heyditto graphs add <@username>
+heyditto graphs remove <@username>
+heyditto graphs subscribers
+heyditto graphs sharing (--enable|--disable) [--title <t>] [--description <d>]
+heyditto init [--name <name>] [--subscribe <@graph>]... [<@graph>...] [--json]
+heyditto login [<key>] [--paste] [--stdin]
+heyditto logout
+heyditto status [--output <format>]
 heyditto config
-heyditto help
+heyditto help [command]
+```
+
+### Help
+
+Use `-h` or `--help` globally or after any command:
+
+```bash
+heyditto --help
+heyditto search --help
+heyditto graphs add --help
 ```
 
 ### `save`
@@ -142,8 +166,13 @@ List saved memories, or public DittoHub publishes for a username.
 ```bash
 heyditto list --limit 10
 heyditto list --username peyton --limit 10 --output json
+heyditto my-memories --source cli --limit 10 --output json
 ```
 
+`my-memories` is the CLI wrapper for `list_my_memories`. It only lists your
+saved memories, while `list --username <u>` can switch to public DittoHub
+publishes for another user.
+
 ### `update`
 
 Edit a saved memory in place. Replace the full body with `--content` or
@@ -154,10 +183,7 @@ Block edits require the current revision returned by `save` or a previous
 ```bash
 heyditto update <memory-id> --content-file revised.md --output json
 heyditto fetch <memory-id> --memory-format outline --output json
-heyditto update <memory-id> \
-  --edits-json '[{"op":"replace_text","blockId":"2","find":"old","replace":"new","expectedCount":1}]' \
-  --base-revision 3 \
-  --output json
+heyditto update <memory-id> --edits-file edits.json --base-revision 3 --output json
 ```
 
 ### `publish` / `unpublish`
@@ -170,6 +196,15 @@ heyditto publish <memory-id> --title "Launch notes" --privacy-mode scan_and_bloc
 heyditto unpublish --share-id abc123def4 --output json
 ```
 
+### `delete`
+
+Permanently delete a saved memory. This is destructive, so the CLI requires
+`--confirm`.
+
+```bash
+heyditto delete <memory-id> --confirm --output json
+```
+
 ### `subjects`
 
 Search the subject (topic) graph. Returns subject ids you can pass to `memories` or `network`.
@@ -177,8 +212,11 @@ Search the subject (topic) graph. Returns subject ids you can pass to `memories`
 ```bash
 heyditto subjects "memory architecture"
 heyditto subjects "performance" --top-k 5
+heyditto subject-edges <subject-id> --limit 10 --min-weight 0.5 --output json
 ```
 
+`subject-edges` is the CLI wrapper for `get_subject_edges`.
+
 ### `memories`
 
 Fetch memory previews scoped to specific subjects.
@@ -196,6 +234,14 @@ Traverse a memory's network (related memories via shared subjects).
 heyditto network <pair-id> --limit 30
 ```
 
+### `friends`
+
+List Ditto friends for commands that need usernames.
+
+```bash
+heyditto friends --output json
+```
+
 ### `graphs`
 
 Manage the public knowledge graphs you're subscribed to. Subscribed graphs are
@@ -206,35 +252,46 @@ your own graph or an app's graph, since those aren't subscriptions.
 ```bash
 heyditto graphs create feedback-triager  # create a NEW dedicated graph you own (mint its CI key in the Ditto UI)
 heyditto graphs list              # graphs you're subscribed to
+heyditto graphs available         # readable knowledge graphs, including main/app graphs
 heyditto graphs add @minos        # subscribe to @minos's public graph
 heyditto graphs remove @minos     # unsubscribe
 heyditto graphs subscribers       # who's subscribed to your graph
+heyditto graphs sharing --disable # disable public subscriptions to your graph
+```
+
+Top-level aliases are also available:
+
+```bash
+heyditto knowledge-graphs --output json
+heyditto graph-sharing --enable --title "Support Graph" --description "Public support notes"
 ```
 
 ### `status`
 
 Print whether `DITTO_API_KEY` is set and the configured MCP endpoint resolves.
 
-### `init --agent`
+### `init`
 
 Create a free claimable agent account and save its key locally. Use `--json` for
 machine-readable output that includes `apiKeyStored`, `userID`, and `claimURL`.
 Share `claimURL` with the human owner. The CLI stores the generated key locally
 without printing it. The claim URL uses a `?t=...` query parameter.
 
-Pass `--agent-caller <name>` to set the agent's name. This is set once at init,
+Pass `--name <name>` to set the agent's name. This is set once at init,
 defaults to `agent`, labels every memory the agent saves, and (after the account
 is claimed) becomes the title of the agent's external thread in the owner's
 graph. Choose it up front — renaming after init isn't yet supported. See
 [Name the agent at init](#name-the-agent-at-init).
 
+`--agent-caller <name>` is still accepted as a backward-compatible alias.
+
 ### `config`
 
 Print a Claude Desktop / Cursor / generic-MCP-client config snippet for the Ditto memory server.
 
 ## Environment
 
-- `DITTO_API_KEY` (optional) — MCP API key override. Agents can instead run `heyditto init --agent --json` for no-human setup.
+- `DITTO_API_KEY` (optional) — MCP API key override. Agents can instead run `heyditto init --json` for no-human setup.
 - `DITTO_API_BASE` (optional) — API base URL. Defaults to `https://api.heyditto.ai`. Useful for local dev (`http://localhost:3400`).
 
 ## Output