CLI overview & auth

notewright is the CLI for a deployed Notewright instance. It connects to an instance over its HTTP API with a shared secret, then drives and inspects every agent operation. The same bin also provides the local doctor preflight.

Running the CLI

The CLI ships in @notewright/core with a notewright bin. Run it either way:

# Install it once, then call it by name:
bun install -g @notewright/core
notewright <command>

# ...or run it on demand without installing:
bunx @notewright/core <command>

Examples use the bare notewright form

Throughout these docs, commands are written as notewright <command>, which assumes a global install (bun install -g @notewright/core). If you have not installed it globally, prefix each command with bunx @notewright/core, for example bunx @notewright/core status.

The CLI runs under Bun, so always invoke it with bunx or a bun install -g install. Scaffolded apps also expose bun run doctor, which runs the local doctor preflight.

Linking an instance

Most commands target a deployed instance. Link one once, then it becomes the current target:

notewright login https://my-instance.example.com
# prompts for the shared secret (or pass --secret), validates it against /health,
# then stores it

Command	What it does
notewright login <url>	Link an instance and store its secret (validated against /health).
notewright logout [host]	Remove a linked instance and its stored secret (defaults to current).
notewright use <host>	Switch the current instance.
notewright instances	List linked instances and show which is current.

How a connection is resolved

For every remote command, the target is resolved in this order:

1. --url with a secret. An explicit --url plus --secret (or NOTEWRIGHT_SECRET) bypasses the linked config entirely.
2. NOTEWRIGHT_URL + NOTEWRIGHT_SECRET. The CI escape hatch: no linked instance and no keychain needed.
3. Linked instance + keychain. --instance <host> (or the current instance) plus the secret stored in the keychain.

# CI escape hatch: no keychain, no linked instance
NOTEWRIGHT_DISABLE_KEYCHAIN=1 \
NOTEWRIGHT_URL="https://my-instance.example.com" \
NOTEWRIGHT_SECRET="secret" \
  notewright status --json

Where config and secrets live

• Config file (linked instances and the current target): ~/.config/notewright/config.json on Linux/Windows; macOS uses ~/Library/Preferences/notewright/config.json. Override the directory with NOTEWRIGHT_CONFIG_DIR (used by tests).
• Secrets are stored in the OS keychain, keyed by the instance host. On platforms without a native keychain binding, the CLI falls back to a plain JSON file alongside config.json. Set NOTEWRIGHT_DISABLE_KEYCHAIN=1 to force the file fallback (used in CI).

Global flags

These flags apply to every remote command:

Flag	Purpose
--url <url>	Target instance base URL, bypassing the linked config.
--instance <host>	Linked instance host to target (defaults to current).
--secret <secret>	Shared secret (else NOTEWRIGHT_SECRET or the keychain).
--json	Emit a structured JSON envelope instead of human-readable output.

JSON output

On success, --json prints the instance’s raw JSON response for that command. Most commands include an ok: true field (for example status and start), but some return a command-specific shape instead. For example, follow-ups run --json emits { "enqueued": true, "meetingId": "...", "transcriptVersion": "..." } with no ok field. On failure, every command emits { "error": { "code", "message" } } and exits non-zero. In scripts and CI, branch on the exit code (or the presence of error) rather than assuming an ok field.

See the Command reference for every command and the HTTP API reference for the endpoints behind them.