notes (packages/cli) is the reference client. --remote uses
@elanotes/sdk. Local --vault keeps today’s read verbs.
Local-mode writes are not promised — those verbs print a hint naming
--remote.
Install / run
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.
Sign in
notes login shows a device code, opens the browser, and saves credentials.
notes login --token <token> saves a personal access token instead, for
agents and CI. notes logout deletes the saved file.
notes login --json emits a device_authorization event on stdout before
waiting for sign-in, with verification_uri, verification_uri_complete,
user_code, and expires_in. Use those details when no browser opens.
Additional informational output uses login_progress events on stdout;
failures remain a single JSON object on stderr.
Credentials are $XDG_CONFIG_HOME/elanotes/credentials.json when
XDG_CONFIG_HOME is set, otherwise ~/.config/elanotes/credentials.json.
The directory is mode 0700 and the file is mode 0600.
The notes CLI is included with Ela Pro. With the license check on, the plan
is read from GET /v1/account at most once a day and keeps working offline
for 72 hours after the last Pro confirmation. login, logout, help,
--version, and export always run.
Repo builds leave ELA_CLI_LICENSE=off, so tests and local recipes stay
credential-free. A release build (pnpm --filter @elanotes/cli build:release)
turns the check on and defaults API_URL to https://api.elanotes.com.
Create a personal access token in web Settings → Access tokens and set ELA_API_TOKEN. Read is included; authenticated note mutations require notes.write. Review commands and queue inspection require notes.review. Personal tokens cannot rename/delete folders or mutate replicas; there is no CLI token-minting command.
Production:
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 include reason, message, and a hint naming the next call (see Failure output).
Round trip
--version prints the VERSION_MOVED hint and exits non-zero.
Check each write receipt before continuing: queued has not changed the note. Report pending_id; inspect it only with review permission, otherwise hand it to a reviewer. Agents must not approve their own proposals. The round trip above can continue immediately only when the write is applied; rollback is also reviewer-protected.
Exit codes map from reason (2 usage, 3 auth, 4 not found, 5 conflict,
6 validation, 7 rate/budget, 8 forbidden, 1 other).
Failure output
With--json, failures emit one JSON object on stderr with reason, message,
and hint, plus available HTTP diagnostics such as statusCode and requestId.
Without --json, stderr prints [REASON] message followed by the hint.
Exit codes retain their existing meanings: usage 2, auth 3, not found 4,
conflict 5, validation 6, rate limit 7, forbidden 8, and unexpected failure 1.
Follow the named call in hint; local create/edit remain remote-only commands.