npm package: @loro-dev/loro-cli
Description: CLI for operating the Loro Streams platform.
Author: Loro Team
Latest version: 0.3.1

# @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

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

Or run without installation:

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

For local development:

```bash
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:

```bash
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](./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:

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

## Publish checklist

```bash
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.