Dots runtime CLI

Alpha release: @wrldbld/[email protected]. Requires Node 20+. Install with npm install -g @wrldbld/[email protected] or run npx @wrldbld/[email protected] --help. Source builds use Bun.

bun run --cwd packages/dots-cli build
node packages/dots-cli/dist/cli.mjs --help
node packages/dots-cli/dist/cli.mjs login --scope 'openid profile context:read context:write notes:share offline_access'
node packages/dots-cli/dist/cli.mjs whoami --json

Build a distributable with npm pack ./packages/dots-cli --pack-destination ./artifacts/mini-auth. Install that exact local tarball to use dots on PATH. The bundle contains dots-core; it has no runtime npm dependency. Keep the existing wrldbld installer for scaffolding projects.

dots login registers a public device client if --client-id is absent. It prints a browser approval URL/code to stderr, then saves a private session. Existing clients must allow the requested scopes. --mcp requests both API and MCP resources; it adds no scopes. Reconnect with context:read:all only for consented cross-app retrieval. New sharing/audience behavior requires the accompanying server release.

dots context search 'project brief'
dots notes create --title 'Brief' --file brief.txt
dots share NOTE_ID --to @alex --permissions note:read --expires 2026-09-18T23:59:00Z
dots grants accept GRANT_ID
dots notes read NOTE_ID
dots grants revoke GRANT_ID

For an agent acting for you, share to your own username with --client AGENT_CLIENT_ID --permissions note:read,note:draft --max-writes 3. Accept from that client. Submit with dots notes draft NOTE_ID --file reply.txt --request-id UUID. Retry with the same UUID and identical content; drafts never replace the source note.

--json writes compact JSON to stdout. Errors are JSON on stderr with exit code 1; no bearer or refresh tokens are printed. Session storage defaults to ~/.config/dots/session.json (directory 0700, file 0600). Set DOTS_SESSION_FILE to a file in a private directory for separate people/apps; process locks protect rotating refresh tokens. Use OS keychain-backed storage when embedding dots-core in desktop/native products.

Register your app once (no sign-in needed):

dots app register --name "My app" --redirect-uri https://my-app.example/dots/callback --scope "openid profile"
dots app register --name "My bot" --device

Repeat --redirect-uri for multiple callbacks. Public JSON on stdout contains clientId, issuer, scope and missingScopes; save and reuse the client ID in your app or pass it to dots login --client-id ID. Exit code 2 means a client was created but scopes were omitted. Do not retry registration to gain permissions. Dynamic clients have no dashboard owner; create an owned client at /dev/clients when restricted scopes or ongoing management are needed. Device-only registration requires the accompanying server update and no longer uses a fake callback URL.