stella-cli

name	stella-cli
description	Drive the stella command-line client (@stll/cli), a legal-workspace CLI whose command surface is generated from the stella MCP tool registry. Covers install, OAuth login, the full command tree grouped by domain, JSON output for scripting, the --input escape hatch for deep payloads, cursor pagination, destructive-op confirmation, and exit codes.
metadata	{"type":"reference","library":"@stll/cli"}

stella CLI

@stll/cli is the command-line client for stella, an open-source legal workspace. Curated tools use stella <domain> <action>; generated capability commands use stella capability <domain> <action>. Both surfaces are generated from the stella MCP tool registry, so they mirror exactly the tools a stella server exposes. Every command works for humans, scripts, and agents alike.

Install

npm i -g @stll/cli

Authenticate

stella auth login

Login runs an OAuth 2.1 authorization-code flow with PKCE against the stella server, using a loopback listener (http://127.0.0.1/callback, ephemeral port) to capture the code. Credentials are stored per server origin, so one machine can hold sessions for several servers at once. Point at a non-default server with --server <url>; scope the session with --scopes (default scopes: openid profile email stella:read stella:search). stella auth whoami shows the active session; stella auth logout clears it.

Conventions every agent must know

• Output format: table is the default only on a TTY; piped/non-TTY output defaults to JSON. Force it with --output json|table (or --json / --table). Always pass --output json when scripting or parsing.
• Deep payloads: any command accepts --input '<json>' for the whole tool argument object, --input @file to read JSON from a file, or --input - to read JSON from stdin. Individual string flags also take gh-style @file / @- sugar (use @@ to pass a literal leading @).
• Array flags are repeatable: pass the flag once per value.
• Pagination: list commands take --cursor <c> and --limit <n>; --all follows cursors up to bounded ceilings. The nextCursor resume hint is written to stderr (more: --cursor <c>) so piped JSON on stdout stays clean.
• Destructive commands (delete/remove) prompt for confirmation on a TTY and require --yes when there is no TTY to confirm on. The CLI owns the server's confirm gate: it injects confirm: true only after you confirm (or pass --yes), so there is no separate --confirm flag to pass.
• Errors print error: <message> (and hint: <next step> when the server supplies one) to stderr as plain text, never to stdout, so a scripted stdout stays clean even with --output json. Every tool error carries a stable machine code that maps to the process exit code (see below): branch on the exit code, and read the error:/hint: lines for the human-readable message.
• MCP resources: stella reference list enumerates static server resources; stella reference show <name> prints one.

Exit codes

Code	Meaning
0	success
1	unexpected internal error
2	usage or input validation error
3	authentication required or failed (run stella auth login)
4	server or tool error
5	feature disabled for this organization
6	resource not found
7	confirmation aborted (a destructive op was declined)
8	permission denied (member role lacks the required permission)
9	usage entitlement exceeded
10	conflict with current state (duplicate or concurrent change)

The exit code lines up with the tool-error code: validation_error -> 2, missing_scope -> 3, feature_disabled -> 5, not_found -> 6, confirmation_required -> 7, and rate_limited / upstream_unavailable / unknown_tool / internal_error -> 4. A legacy server that tags only a bare feature_disabled code (no envelope) still maps to 5; anything else falls to 4.

Capability commands (full surface)

Beyond the curated commands above, the CLI generates 313 capability commands from the server's capability catalog: every safe handler that is not a curated tool, reached through the generic invoke_capability path. Every generated command lives at stella capability <domain> <action>; multi-segment capability actions are flattened with hyphens into <action>.

• Discover: stella capability list [--domain <d>] [--access read|write] enumerates them (paginated); stella capability describe <id> prints one capability's full input schema, scope, and flags.
• Invoke by id (forward-compatible with any server): stella capability invoke <id> --input '<json>', where the JSON is { body?, params?, query? }.
• Flags: each capability command derives flags from its input schema; workspace-scoped capabilities take a required --workspace <id>. Deep or ambiguous payloads use --input (the whole { body?, params?, query? }).
• Dry run: --dry-run validates the input server-side and returns without executing (maps to validateOnly).
• Destructive capabilities prompt on a TTY and need --yes off a TTY; the server's per-capability confirm gate is satisfied automatically once confirmed.
• Exit codes are identical to the curated commands (see above).

Filing feedback

stella feedback send files a bug, feature request, or docs issue with the maintainers. Content is sanitized server-side (emails, ids, secrets, URLs, and IPs are redacted); never include tenant data, client or matter names, ids, or secrets: describe the problem, reproduction steps, and expected vs actual result. Pass --kind, --title, and --body.

• github (preferred): returns a prefilled new-issue URL and a gh command the human opens and submits under their own GitHub account. The CLI never publishes anything itself.

Command tree

Generated from the MCP tool registry; Access is the OAuth scope the command requires (request it at stella auth login --scopes).

Domain	Command	Access	Notes
audit-log	stella audit-log list	admin_read	paginated
capability	stella capability describe	read
capability	stella capability invoke	read
capability	stella capability list	read	paginated
case-law	stella case-law read	read	paginated; windowed text
case-law	stella case-law search	search	paginated
clause	stella clause delete	knowledge_write	destructive (needs --yes off a TTY)
clause	stella clause list	read	paginated
clause	stella clause save	knowledge_write
contact	stella contact delete	matters_write	destructive (needs --yes off a TTY)
contact	stella contact list	read	paginated
contact	stella contact lookup-registry	read
contact	stella contact read	read
contact	stella contact save	matters_write
document	stella document delete	documents_write	destructive (needs --yes off a TTY)
document	stella document field set	documents_write
document	stella document list	read	paginated