@notatemd/cli 4.3.0

package/README.md

@@ -0,0 +1,264 @@
+# @notatemd/cli
+
+Command-line interface for [Notate](https://notate.md). 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.
+
+- [Install](#install)
+- [Getting started](#getting-started)
+- [Concepts](#concepts)
+- [Command reference](#command-reference)
+  - [Account](#account)
+  - [Notes](#notes)
+  - [Folders](#folders)
+  - [Workspaces](#workspaces)
+  - [Tags](#tags)
+  - [AI](#ai)
+  - [Transcribe](#transcribe)
+  - [Stats](#stats)
+  - [Config](#config)
+  - [Completion](#completion)
+- [End-to-end encryption](#end-to-end-encryption)
+- [Scripting](#scripting)
+- [Configuration and stored data](#configuration-and-stored-data)
+
+## Install
+
+Requires Node.js 20 or newer.
+
+```bash
+npm install -g @notatemd/cli
+notate --help
+```
+
+Or run it without installing:
+
+```bash
+npx @notatemd/cli --help
+```
+
+## Getting started
+
+The CLI talks to the Notate API (`https://api.notate.md`) by default. Log
+in with your Notate account, then start capturing:
+
+```bash
+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
+
+```bash
+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
+
+```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]
+
+# 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
+
+```bash
+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
+
+```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>] [--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
+
+```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>]
+```
+
+### AI
+
+```bash
+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
+
+```bash
+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
+
+```bash
+notate stats [--workspace <name|id>] [--json]
+```
+
+### Config
+
+```bash
+notate config set <key> <value>
+notate config get <key>
+notate config list
+notate config reset
+```
+
+Keys: `server`, `workspace`, `defaultMode`, `defaultSort`, `pageSize`. For
+example, point the CLI at a local dev server:
+
+```bash
+notate config set server http://localhost:3004
+```
+
+### Completion
+
+```bash
+notate completion bash   # or zsh, fish
+```
+
+Print a shell completion script. Add it to your shell config, for example:
+
+```bash
+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:
+
+  ```bash
+  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:
+
+  ```bash
+  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.