@loro-dev/loro-cli

CLI for operating the Loro Streams platform.

Scope

This package provides a script-friendly command line interface for:

• authentication flows (loro auth ...)
• dashboard operations (loro dashboard ...)
• stream operations (loro stream ...)
• bucket operations (loro bucket ...)
• local SQLite-backed dev server startup (loro dev ...)
• CLI version inspection (loro version)
• AI bootstrap guide generation (loro prompt, outputs Loro Streams Agent Guide)

Design notes

• Default output is human-readable.
• --json enables machine-friendly structured output.
• Interactive TUI is intentionally avoided to stay AI-agent compatible.

Quick start

npm install -g @loro-dev/loro-cli
loro --help
loro version

Or run without installation:

npx -y @loro-dev/loro-cli --help
npx -y @loro-dev/loro-cli version

For local development:

pnpm --filter @loro-dev/loro-cli run dev -- --help
pnpm --filter @loro-dev/loro-cli run dev -- version
pnpm --filter @loro-dev/loro-cli run dev -- prompt
pnpm --filter @loro-dev/loro-cli run dev -- auth login --no-browser
pnpm --filter @loro-dev/loro-cli run dev -- dashboard api-key token --key <api-key>
pnpm --filter @loro-dev/loro-cli run dev -- dev --db-path ./data/dev.sqlite
pnpm --filter @loro-dev/loro-cli run dev -- stream append <bucket> <stream> --data "hello" --framing binary
pnpm --filter @loro-dev/loro-cli run dev -- stream read <bucket> <stream> --format jsonl
pnpm --filter @loro-dev/loro-cli run dev -- stream inspect <bucket> <stream> 0 --data-format hex
pnpm --filter @loro-dev/loro-cli run dev -- stream watch <bucket> <stream> --from now --format jsonl

Help navigation is hierarchical. You can drill down at any command depth:

• loro --help
• loro auth --help
• loro auth token --help
• loro dashboard api-key --help
• loro dashboard api-key token --help
• loro dev --help
• loro version --help
• loro stream --help
• loro stream append --help
• loro prompt backend-api --help

Local dev server

loro dev starts a local single-node Durable Streams server backed by SQLite + WAL:

loro dev --db-path ./data/dev.sqlite

Properties:

• no auth
• implicit bucket namespaces
• SQLite persistence with WAL
• snapshot/bootstrap/live support via the bundled @loro-dev/sqlite-riverrun runtime

This command only starts the local server. It does not rewrite your active CLI profile.

loro prompt uses incremental expansion:

• overview + base commands + topic directory on default run
• topic details via:
  • loro prompt durable-stream
  • loro prompt integration with CRDT
  • loro prompt permissions
• backend API task index (dashboard + gateway):
  • loro prompt backend-api
  • loro prompt backend-api --path /api/auth/api-key/token
  • loro prompt backend-api --tag ApiKey --format json
  • loro prompt backend-api --tag Gateway --format json
  • loro prompt backend-api --path /ds/{bucket}/{stream}/bootstrap --format json
  • loro prompt backend-api --full (full OpenAPI YAML dump)
  • loro prompt backend-api --full --format json (full OpenAPI JSON object)
• full legacy reference only when explicitly requested:
  • loro prompt --profile full

Recommended API-key-to-JWT workflow:

1. Read command semantics quickly: loro dashboard --help
2. Locate endpoint details: loro prompt backend-api --path /api/auth/api-key/token --format json
3. Exchange key for JWT: loro dashboard api-key token --key <api-key>
4. Use the JWT for gateway calls: loro stream ... (persist Stream-Next-Offset from responses)

Manual testing

See MANUAL_TESTING.md for end-to-end manual validation steps.

E2E failed-case tests

e2e/*.test.ts contains real backend reproduction cases and must be run with a dedicated command.

Prerequisites:

• You must be logged in first (loro auth login --host https://streams.loro.dev).
• These tests call real deploy/gateway endpoints.

Commands:

pnpm --filter @loro-dev/loro-cli run test:e2e
pnpm --filter @loro-dev/loro-cli run test:e2e:failed-cases

Publish checklist

pnpm --filter @loro-dev/loro-cli run build
pnpm --filter @loro-dev/loro-cli run typecheck
pnpm --filter @loro-dev/loro-cli run test
pnpm --filter @loro-dev/loro-cli run test:built-artifacts
pnpm --filter @loro-dev/loro-cli run test:pack

Credentials

Credentials are stored at:

• macOS/Linux: ~/.config/loro/credentials.json
• Windows: %APPDATA%/loro/credentials.json

File permissions are restricted to the current user on Unix-like systems.