# Ditto CLI

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

---

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

```bash
npm install -g @heyditto/cli
ditto --version
```

The CLI requires Node.js and npm. If either command is missing, install Node 20 or newer, then reopen your shell so npm's global bin directory is on `PATH`.

## Authenticate

Create an agent key from the app connect page for your integration:

- [app.heyditto.ai/connect/openclaw](https://app.heyditto.ai/connect/openclaw)
- [app.heyditto.ai/connect/hermes](https://app.heyditto.ai/connect/hermes)

Then save it locally:

```bash
ditto login <paste-key>
```

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

Prefer environment variables? This works too:

```bash
export DITTO_API_KEY="ditto_mcp_..."
```

`DITTO_API_KEY` takes priority over the saved config file.

## Verify

Check the CLI can reach Ditto:

```bash
ditto status
```

Expected shape:

```text
@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:

```bash
ditto subjects "test" --output json
```

## Commands Agents Use

- `ditto search` finds relevant memories semantically.
- `ditto fetch` retrieves specific memories.
- `ditto save` stores durable preferences, decisions, and facts.
- `ditto subjects` searches subjects.
- `ditto memories` previews memories scoped to a subject.
- `ditto network` returns related memories and subject context.
- `ditto status` verifies auth and endpoint access.

## Troubleshooting

| Symptom                                                      | Fix                                                                                                                          |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `ditto: command not found`                                   | Install with `npm install -g @heyditto/cli`, then reopen your shell so npm's global bin directory is on `PATH`.              |
| `error: no Ditto API key configured`                         | Create a key from your integration's app connect page, then run `ditto login <key>`.                                         |
| `ditto status` shows `source: env` but you expected `config` | `DITTO_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 previously                       | Run `ditto status`. If the key was revoked, rotate it with `ditto logout` followed by `ditto login <new-key>`.               |

## Reference Links

- [Ditto CLI on npm](https://www.npmjs.com/package/@heyditto/cli)
- [OpenClaw setup](/docs/openclaw)
- [Hermes Agent setup](/docs/hermes-agent)