@notatemd/cli

Command-line interface for Notate. A pure REST client for the Notate API: quick capture, scripting, automation, and AI queries from the terminal, no web or desktop app required. Installs the notate command.

Full documentation also available here

• Install
• Getting started
• Concepts
• Command reference
  • Account
  • Notes
  • Folders
  • Workspaces
  • Tags
  • AI
  • Transcribe
  • Stats
  • Completion
• End-to-end encryption
• Scripting
• Configuration and stored data

Install

Requires Node.js 20 or newer.

npm install -g @notatemd/cli
notate --help

Or run it without installing:

npx @notatemd/cli --help

Getting started

Log in with your Notate account, then start capturing:

notate login                                   # authenticate (prompts for password)
notate whoami                                  # confirm the logged-in account
notate workspaces use "My Workspace"           # pick a default workspace
notate notes create "My Note" --content "# Hello"
notate notes list
notate ask "What notes have I favorited?"      # AI over your notes

Run notate <command> --help for the full, authoritative option list on any command.

Concepts

• Workspaces group your folders and notes. notate workspaces use <name|id> pins an active workspace so you can omit --workspace on every command. Any command that operates on notes/folders accepts --workspace <name|id> to override the active one for a single call.
• Folders hold notes and can nest. A top-level folder is a "root." New notes land in the workspace's default folder (set with notate workspaces set-default-folder), or the first root if no default is set.
• Addressing by name vs id. Note and folder commands take a title/name as their argument. Names are not guaranteed unique, so most commands also accept --id <id> to target a specific item unambiguously. When a name matches more than one item in an interactive terminal, the CLI shows a picker.
• --json is available on most read/write commands for scripting. Without it, output is human-readable tables and text.
• Confirmation. Destructive commands prompt before acting; pass --confirm (or --quiet) to run non-interactively.

Command reference

Account

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

login prompts for your password (and email if --email is omitted). --server overrides the API URL for that login; otherwise the configured server is used.

Notes

# 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]

# 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>] [--json]
notate notes favorite [title] [--off] [--id <id>] [--workspace <name|id>] [--json]

# versions
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>] [--json]

# 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>] [--quiet]

Notes:

• notes versions [title] lists a note's history; add --restore <version-id> (an id from the list) to revert the note to that version.
• notes search supports keyword, semantic (embeddings), and hybrid modes. Search is unavailable on encrypted accounts (see below).
• 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 -o <file>, or a whole --folder/--all to -o <directory>.

Folders

notate folders list   [--workspace <name|id>] [--json]         # tree with note counts
notate folders create <name> [--parent <name>] [--workspace <name|id>] [--json]
notate folders rename <name> <newName> [--workspace <name|id>]
notate folders move   <name> [--to <parent> | --to-root] [--id <id>] [--workspace <name|id>] [--json]
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

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>] [--json]
notate workspaces rename <name> <newName>
notate workspaces delete <name> [--confirm]     # folders/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 folder (root) can belong to more than one workspace; add-folder / remove-folder manage that membership without moving or deleting the folder.

Tags

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>]

AI

notate ask <question> [--quiet-tools]                         # streams the answer over your notes
notate summarize [title] [--id <id>] [--workspace <name|id>] [--json]   # generate + save a summary
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. All AI commands are unavailable while end-to-end encryption is on.

Transcribe

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

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

Stats

notate stats [--workspace <name|id>] [--json]

Completion

notate completion bash   # or zsh, fish

Print a shell completion script. Add it to your shell config, for example:

notate completion zsh >> ~/.zshrc      # then reload your shell

End-to-end encryption

If your account has end-to-end encryption enabled, the CLI encrypts note fields (title, content, summary, transcript, tags) client-side before they leave your machine, and decrypts them on read. The encryption key is unlocked at login and cached in your OS keychain.

Because the server can't read encrypted content, these features are unavailable on encrypted accounts: notes search, ask, summarize, gentags, rewrite, and server-side tag aggregation in stats. The CLI checks your live encryption state per command, so it will never write plaintext to an encrypted account.

Scripting

• Add --json to most commands for machine-readable output.

• notes create/edit read content from --stdin or --file, so you can pipe:

  echo "# Log\n$(date)" | notate notes create "Daily log" --stdin
  git log --oneline -10 | notate notes create "Recent commits" --stdin --folder Dev

• notes get prints raw markdown to stdout, so it composes with other tools:

  notate notes get "Spec" | wc -w

Configuration and stored data

• Config (server URL, active workspace, display preferences) is stored in a JSON file in your OS config directory. View it with notate config list.
• Credentials (access/refresh tokens and, for encrypted accounts, the content key) are stored in your OS keychain, not on disk in plaintext.
• notate logout clears the stored credentials for the current server.