# Command reference

> Every Notate CLI command and its options, by group.

Source: https://notate.md/docs/cli/commands/

Category: CLI

Updated: 2026-08-21

---

This is the full command surface. Run `notate <command> --help` for the authoritative option list on any command.

## Concepts

A few ideas apply across most commands:

- **Workspaces** group your folders and notes. `notate workspaces use <name|id>` pins an active workspace so you can omit `--workspace`. Any note or folder command also takes `--workspace <name|id>` to override it for one call.
- **Folders** hold notes and can nest. A top-level folder is a root. New notes land in the workspace's default folder, or the first root if no default is set.
- **Name vs id.** Note and folder commands take a title or name, but names are not unique, so most also accept `--id <id>` to target one item exactly. In an interactive terminal, an ambiguous name shows a picker.
- **`--json`** is available on most commands for scripting.
- **Confirmation.** Destructive commands prompt first; pass `--confirm` (or `--quiet`) to run non-interactively.

## Account

```bash
notate login [--email <email>] [--server <url>] [--json] [--quiet]
notate logout
notate whoami [--json]
```

## Notes

```bash
# create (defaults into the workspace's default folder)
notate notes create <title> [--content <text> | --stdin | --file <path>]
                            [--folder <name>] [--tags <csv>] [--workspace <name|id>] [--json]

# read
notate notes list   [--folder <name>] [--tag <name>] [--favorite]
                    [--sort title|createdAt|updatedAt] [--limit <n>] [--workspace <name|id>] [--json]
notate notes get    [title] [--id <id>] [--workspace <name|id>] [--json]
notate notes search <query> [--mode keyword|semantic|hybrid] [--folder <name>] [--tag <name>]
                            [--limit <n>] [--workspace <name|id>] [--json]
                            # <query> accepts tag: title: folder: path: created: updated: is: has:

# update
notate notes edit   [title] [--content <text> | --stdin | --file <path> | --append <text>]
                    [--id <id>] [--workspace <name|id>] [--json]
notate notes move   [title] [--to <folder> | --to-default] [--id <id>] [--workspace <name|id>] [--json]
notate notes tag    [title] [--add <csv>] [--remove <csv>] [--set <csv>] [--id <id>] [--workspace <name|id>]
notate notes favorite [title] [--off] [--id <id>] [--workspace <name|id>]

# version history
notate notes versions [title] [--restore <version-id>] [--id <id>] [--workspace <name|id>] [--json]

# trash lifecycle
notate notes delete  [title] [--id <id>] [--confirm] [--workspace <name|id>] [--quiet]
notate notes trash   [--workspace <name|id>] [--json]            # list trashed notes
notate notes trash delete [title] [--id <id>] [--workspace <name|id>]
notate notes trash empty  [--workspace <name|id>] [--confirm]
notate notes restore [title] [--id <id>] [--workspace <name|id>]

# import / export
notate notes import <path> [--folder <name>] [--tags <csv>] [--recursive] [--dry-run] [--workspace <name|id>]
notate notes export [title] [-o <path>] [--format md|json] [--id <id>]
                    [--folder <name> | --all] [--workspace <name|id>]
```

A few notes:

- `notes versions` lists a note's history; add `--restore <version-id>` (an id from the list) to revert to that version.
- `notes search` supports keyword, semantic, and hybrid modes. It is unavailable on encrypted accounts (see [Configuration](https://notate.md/docs/cli/configuration/)).
- `notes search` takes the same [operators as search in the app](https://notate.md/docs/organizing/search/#narrowing-a-search), so `notate notes search 'tag:work updated:>2026-01-15'` works. Quote the whole query in your shell, since `>` and `-` mean something to it before they reach Notate.
- `notes import` reads a single `.md` file or a directory of them; `--recursive` walks subdirectories, `--dry-run` previews without writing.
- `notes export` writes one note to a file, or a whole `--folder` or `--all` to a directory.

## Folders

```bash
notate folders list   [--workspace <name|id>] [--json]         # tree with note counts
notate folders create <name> [--parent <name>] [--workspace <name|id>]
notate folders rename <name> <newName> [--workspace <name|id>]
notate folders move   <name> [--to <parent> | --to-root] [--id <id>] [--workspace <name|id>]
notate folders favorite <name> [--off] [--workspace <name|id>]
notate folders delete <name> [--recursive] [--confirm] [--workspace <name|id>]
notate folders restore <name> [--workspace <name|id>]
notate folders trash  [--workspace <name|id>]                  # list trashed folders
notate folders trash delete <name> [--workspace <name|id>] [--confirm]
```

## Workspaces

```bash
notate workspaces list                          # active one is marked with a star
notate workspaces use <name|id> [--quiet]       # pin the active workspace
notate workspaces create <name> [--color <color>] [--icon <icon>]
notate workspaces rename <name> <newName>
notate workspaces delete <name> [--confirm]     # folders and notes are kept, just unscoped
notate workspaces set-default-folder <folder> [--workspace <name|id>]
notate workspaces add-folder <folder> [--workspace <name|id>]      # link a root into another workspace
notate workspaces remove-folder <folder> [--workspace <name|id>]   # unlink (does not delete)
```

A root folder can belong to more than one workspace. `add-folder` and `remove-folder` manage that membership without moving or deleting the folder.

## Tags

```bash
notate tags list   [--workspace <name|id>]                    # tags with usage counts
notate tags rename <oldName> <newName> [--workspace <name|id>]
notate tags delete <name> [--confirm] [--workspace <name|id>]
```

The `tags` commands are unavailable on encrypted accounts, since the server can't read your encrypted tags.

## AI

```bash
notate ask <question> [--quiet-tools]                         # streams the answer over your notes
notate summarize [title] [--id <id>] [--workspace <name|id>] [--json]
notate gentags   [title] [--apply] [--id <id>] [--workspace <name|id>] [--json]
notate rewrite   [text] [--action <action>] [--stdin]         # transform text, print to stdout
```

`rewrite` actions: `rewrite` (default), `concise`, `fix-grammar`, `to-list`, `expand`, `summarize`.

These need AI on your account: the AI plan, or the Sync plan with [your own Anthropic key](https://notate.md/docs/ai/bring-your-own-keys/). Because the CLI talks to the same server the apps do, a key you save once in Settings works here too — there is nothing to configure on the command line. `transcribe` needs an OpenAI key rather than an Anthropic one.

All AI commands are unavailable while end-to-end encryption is on, whether the key is yours or ours.

## Transcribe

```bash
notate transcribe <file> [--mode meeting|lecture|memo|verbatim] [--folder <name>]
                         [--tags <csv>] [--title <title>] [--workspace <name|id>]
```

Uploads an audio file and saves a structured note from the transcript. Mode defaults to `memo`.

## Stats and completion

```bash
notate stats [--workspace <name|id>] [--json]
notate completion bash|zsh|fish        # print a shell completion script
```

Next: [scripting and automation](https://notate.md/docs/cli/scripting/).