> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elanotes.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> notes is a first-class API client through @elanotes/sdk.

`notes` (`packages/cli`) is the reference client. `--remote` uses
[`@elanotes/sdk`](/sdk-ts). Local `--vault` keeps today's read verbs.
Local-mode writes are not promised — those verbs print a hint naming
`--remote`.

## Install / run

```bash theme={null}
pnpm --filter @elanotes/cli build
pnpm notes -- --help
```

`pnpm notes` runs `packages/cli/dist/cli.js`. The `--` after `notes`
keeps pnpm from eating flags. Default `API_URL` is
`http://127.0.0.1:4000`. Optional bearer: `ELA_API_TOKEN`.

Production:

```bash theme={null}
API_URL=https://api.elanotes.com ELA_API_TOKEN=… pnpm notes -- search Paddle --remote
```

## Remote verbs

Every verb accepts `--json` (handles, versions, coverage — never full
bodies except `read` / `raw`). Writes send an `Idempotency-Key` unless
you pass `--idempotency-key`. Failures print `message` then `hint`.

| Verb                                                  | What it calls                            |
| ----------------------------------------------------- | ---------------------------------------- |
| `search` / `grep` / `read` / `raw` / `links`          | Search and read                          |
| `list [--filter --order-by --page-size --page-token]` | `GET /v1/notes`                          |
| `create` / `write`                                    | `POST /v1/notes`                         |
| `edit`                                                | `POST /v1/notes/{note}:edit`             |
| `patch --set … --update-mask …`                       | `PATCH /v1/notes/{note}`                 |
| `move` / `rename` / `delete`                          | Canonical `:move` / `:rename` / `DELETE` |
| `folders {list\|create\|rename\|delete}`              | Folder routes                            |
| `tags`                                                | `GET /v1/tags`                           |
| `revisions` / `rollback`                              | `:listRevisions` / `:rollback`           |
| `review {list\|approve\|reject}`                      | Writes + `:approve` / `:reject`          |
| `attach`                                              | Multipart upload                         |
| `query`                                               | `POST /v1/query`                         |

## Round trip

```bash theme={null}
pnpm notes -- create inbox/cli-demo.md --remote --json --content $'# Demo\n\nhello\n'
pnpm notes -- edit cli-demo --remote --json --old hello --new hello-edited --version <version_id>
pnpm notes -- revisions cli-demo --remote --json
pnpm notes -- rollback cli-demo <revision_id> --remote --json
```

A stale `--version` prints the `VERSION_MOVED` `hint` and exits non-zero.
Exit codes map from `reason` (2 usage, 3 auth, 4 not found, 5 conflict,
6 validation, 7 rate/budget, 8 forbidden, 1 other).