Command-line interface

raven, the command-line interface for the Raven backend.

Usage¶

pnpm --filter @raven/cli dev version         # run from source
pnpm --filter @raven/cli build && node cli/dist/index.mjs version

Command	Description
`raven version`	CLI version, plus the server and API version of the profile
`raven -V`	CLI version only, with no network call
`raven profile add <name> [<api-url>]`	Add a profile for a server, with no user
`raven profile list`	List profiles; `*` marks the current one
`raven profile use <name>`	Make a profile the current one
`raven profile remove <name> [--yes]`	Remove a profile, ending its session
`raven auth login [<api-url>] [--username <name>] [--password-stdin]`	Log in with a username or email and password
`raven auth logout`	End the session and delete the token; the profile stays
`raven orgs list [--page <n>] [--per-page <n>] [--all]`	List organizations; site admins also see unlisted ones
`raven orgs get <org-slug \| org-id>`	Show an organization; logged-in users also see whether they can edit it
`raven auth status`	Show the profile, server and user; exit code 3 if the session has expired

Global options, accepted by every command:

Option	Description
`--profile <name>`	Profile to use. Defaults to `RAVEN_PROFILE`, then `current`
`--json`	Print JSON on stdout, and errors as JSON on stderr
`--anonymous`	Send requests without a token

Profiles¶

A profile is a server plus an optional user, stored in config.toml in the config directory (~/.config/raven, or $XDG_CONFIG_HOME/raven; the OS default on Windows). Tokens are kept in the OS keychain, or in credentials.json (mode 0600) when no keychain is available.

current = "local"

[profiles.local]
apiUrl = "http://localhost:7001"
user = "alice"

[profiles.public]
apiUrl = "https://api.thestacks.org"

With no profile, the CLI uses https://api.thestacks.org anonymously.

Variable	Effect
`RAVEN_PROFILE`	Profile to use when `--profile` isn’t given
`RAVEN_API_URL`	Server to use; the profile’s stored token is then not sent
`RAVEN_TOKEN`	Token to send instead of the stored one
`RAVEN_CONFIG_DIR`	Config directory to use instead of the OS default

Exit codes¶

Code	Meaning
0	Success
1	Other error
2	Usage error (unknown command, bad option, etc.)
3	Authentication or permission error (401, 403)
4	Not found (404)
5	Validation error (400, 422)
6	Network error (server unreachable, timeout)
7	Server error (5xx)

Development¶

Script	Description
`pnpm dev <args>`	Run the CLI from source with tsx
`pnpm build`	Bundle to `dist/index.mjs` with tsdown
`pnpm test`	Unit tests (vitest)
`pnpm generate:api [x]`	Regenerate `src/api/openapi.json` and `src/api/v1.d.ts` from a server URL or spec file (default `http://localhost:7001`)

Commit the regenerated files whenever the v1 API changes. Each command in src/commands/ declares its auth level (none, optional, required) and the v1 routes it calls; auth-levels.test.ts checks the levels against the spec.