Ditto
Ditto
Ditto
Home Pricing Numbers DittoBench Blog Docs

Start typing to search...

Open the app

Start typing to search...

Updated June 22, 2026

Ditto CLI

Install, authenticate, verify, and troubleshoot the Ditto CLI used by CLI-first agent integrations, including agent-native signup.

The Ditto CLI gives agent skills a local command surface for Ditto memory. OpenClaw and Hermes Agent use this path instead of MCP.

Most users do not need to install the CLI by hand. Agent skills can install or configure it as part of their own setup. Use this page when you need to verify the CLI directly, rotate a key, or troubleshoot a missing command.

Install

Zero-install commands are preferred for agents and sandboxed environments:

npx -y @heyditto/cli --version
# or: bunx @heyditto/cli --version

For repeated local use, install the CLI globally and invoke it as heyditto:

npm install -g @heyditto/cli
heyditto --version
bun add -g @heyditto/cli
heyditto --version

The CLI requires Node.js and npm, or Bun for the Bun commands. If a global install succeeds but heyditto is missing, reopen your shell so the global bin directory is on PATH.

Prefer heyditto for installed usage. On macOS, ditto collides with Apple’s built-in /usr/bin/ditto file-copy utility.

Authenticate With Agent-Native Signup

Preferred flow for agents:

npx -y @heyditto/cli init --agent --agent-caller "NAME_OF_AGENT" --json
# or: bunx @heyditto/cli init --agent --agent-caller "NAME_OF_AGENT" --json

Set --agent-caller to the agent’s name (or a name the human has chosen). It is set once at init and labels the agent’s saved memories, so pick it up front — see Agent-Native Signup.

Pre-Subscribe to Foundation Graphs

Pass --subscribe to subscribe the new agent to one or more public foundation graphs (like @minos) at provisioning time, so a graph the app depends on is available the moment the agent starts:

# Repeatable and/or comma-separated; bare handles work too. '@' is optional.
npx -y @heyditto/cli init --agent --agent-caller "miner-bot" --subscribe @minos --json

The subscriptions apply to the agent’s own reads only, never the human owner’s main Ditto account. It is best-effort: a handle that isn’t found or isn’t public is reported back (failedGraphs) and skipped, and the agent is still created. The outcome is in the result as subscribedGraphs / failedGraphs. See Agent Accounts.

This command:

  • creates a free temporary claimable account,
  • stores the generated key in ~/.config/heyditto/cli/config.json without printing it,
  • returns a claimURL and local credential status for the human owner,
  • avoids asking the human to paste a key back into the agent.

Share the claimURL. Agent-native signup should not print the generated ditto_mcp_... key.

The claim token lives in the query string, ?t=..., so agents should share the full claim URL exactly as returned.

Authenticate With An Existing Key

If you already have a human-managed key:

heyditto login <paste-key>

The CLI writes the key to ~/.config/heyditto/cli/config.json with file mode 0600.

Prefer environment variables? This works too:

export DITTO_API_KEY="ditto_mcp_..."

DITTO_API_KEY takes priority over the saved config file.

Verify

Check the CLI can reach Ditto:

npx -y @heyditto/cli status

Expected shape:

@heyditto/cli 1.x.x
endpoint:  https://api.heyditto.ai/mcp
api key:   set  (source: config)
tools:     fetch_memories, get_memory_network, save_memory,
           search_memories, search_memories_in_subjects, search_subjects

Then make a real account-backed request:

npx -y @heyditto/cli subjects "test" --output json

Commands Agents Use

Use npx -y @heyditto/cli <command> for zero-install runs, or heyditto <command> after installing the CLI globally.

  • search finds relevant memories semantically.
  • fetch retrieves specific memories.
  • save stores durable preferences, decisions, and facts.
  • subjects searches subjects.
  • memories previews memories scoped to a subject.
  • network returns related memories and subject context.
  • status verifies auth and endpoint access.
  • graphs creates dedicated graphs and manages the public graphs you subscribe to.

Graphs

The graphs command does two things: create a dedicated graph you own, and manage your subscriptions to other people’s public graphs (the same subscriptions you manage in Settings → Knowledge Graphs). Subscribed graphs fold into memory search and fetch.

heyditto graphs create <name>              # provision a dedicated graph you own
heyditto graphs create <name> --app <app>  # ...owned by one of your apps
heyditto graphs list                       # public graphs you're subscribed to
heyditto graphs add @username               # subscribe to a public graph
heyditto graphs remove @username            # unsubscribe from a public graph
heyditto graphs subscribers                 # who is subscribed to your graph

graphs create provisions a new dedicated graph — a single-purpose knowledge graph you own — and returns a claim URL. Open it to mint a scoped CI/agent key and copy ready-made setup commands (the key is shown in the UI, never printed by the command). Pass --app <app_id> to create the graph owned by one of your apps (an app can own many graphs, each its own KG + keys). Subscriptions only ever cover other users’ public graphs by @username; they never touch your own graph or app graphs.

Use the same commands with npx -y @heyditto/cli graphs <subcommand> for zero-install runs. For example, subscribe an agent to a foundation graph:

npx -y @heyditto/cli graphs add @minos

See Dedicated Graphs for the full create-and-use flow, and Knowledge Graph Sharing for how visibility and subscriptions work.

Troubleshooting

SymptomFix
Global install fails with EACCESUse npx -y @heyditto/cli <command> or bunx @heyditto/cli <command> instead of writing to a global install directory.
heyditto: command not found after global installReopen your shell so npm’s or Bun’s global bin directory is on PATH, or use the zero-install npx / bunx command.
ditto runs a file-copy utility on macOSUse heyditto for installed CLI usage, or run npx -y @heyditto/cli <command> directly.
error: no Ditto API key configuredRun npx -y @heyditto/cli init --agent --json to provision a claimable agent account, or use heyditto login <key> if you already have a key.
ditto status shows source: env but you expected configDITTO_API_KEY overrides the saved config file. Run unset DITTO_API_KEY, and remove it from shell startup files if saved.
Requests fail after working previouslyRun npx -y @heyditto/cli status. If the key was revoked, rotate it with heyditto logout followed by heyditto login <new-key>.
The human cannot claim the accountMake sure you shared the full claimURL, including the ?t=... query parameter.