stella/stella/stella-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 --server <url>

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. The first login needs --server <url> (or STELLA_SERVER_URL); it then becomes the default, and every command accepts --server <url> to target another one. A default login requests the working set of scopes (everything but organization administration writes and one-off setup); pass --scopes to request an explicit set. The default scopes are openid profile email offline_access stella:read stella:search stella:templates stella:documents_write stella:matters_write stella:contacts_write stella:chat stella:knowledge_write stella:billing_write stella:admin_read stella:skills stella:feedback stella:organization_create. 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 @).

• Reading a command's contract: --schema prints that command's input JSON

schema (the same schema the MCP tool validates against) and exits 0, without calling the server.

• Sending a local document: a command whose tool takes a document also takes

--file <path>; the CLI reads the file and sends it in the tool's own base64 field, the call an MCP host would make with the file attached. --help states the size ceiling, which is the one that field's schema declares. A larger file is refused: send it from a host that can attach it to the tool's file reference, never by re-exporting the document to fit.

• 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.

• Finding and reading text: stella search matters --query '<q>' returns

matching documents with their entity ids, and stella document content --entity-id <id> prints one document's text (windowed, so follow --cursor).

• MCP resources: stella reference list enumerates static server resources;

stella reference show <name> prints one.

• Uploading a file: stella upload --file <file> --matter-id <matter-id> uploads a local file as a new document; add --entity-id <id> to upload it as a new version of an existing document instead — a CLI-native path (the CLI reads the file itself), separate from the MCP upload_document_version/open_document_version_upload tools (which take a host-supplied file reference and are excluded from the CLI).

Command tree

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

Command flags

Required: --flag — description (type). Optional: one optional: --a, --b (enum1|enum2) line, names only (--help has full descriptions). Global flags (output/cursor/limit/all/yes/input; see Conventions above) are omitted here. Input union keys are required unless marked ?.