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

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 content	read	paginated; windowed text
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
document	stella document properties list	read	paginated
document	stella document read	read
document	stella document save	documents_write
feedback	stella feedback prepare	feedback
invoice	stella invoice list	read	paginated
legislation	stella legislation search	read	paginated
matter	stella matter delete	matters_write	destructive (needs --yes off a TTY)
matter	stella matter link-contact	matters_write
matter	stella matter list	read	paginated
matter	stella matter save	matters_write
organization	stella organization add-member	admin_write
organization	stella organization remove-member	admin_write	destructive (needs --yes off a TTY)
organization	stella organization set-jurisdictions	onboarding
organization	stella organization update-settings	admin_write
playbook	stella playbook list	read	paginated
playbook	stella playbook run	knowledge_write
rate	stella rate resolve	read
search	stella search matters	search	paginated
task	stella task delete	matters_write	destructive (needs --yes off a TTY)
task	stella task list	read	paginated
task	stella task save	matters_write
template	stella template configure-fields	templates
template	stella template create	templates
template	stella template fill	templates
template	stella template list	templates	paginated
template	stella template save-filled new-document	documents_write + templates
template	stella template save-filled new-version	documents_write + templates
time-entry	stella time-entry delete	billing_write	destructive (needs --yes off a TTY)
time-entry	stella time-entry list	read	paginated
time-entry	stella time-entry save	billing_write
usage	stella usage get	read

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.

• stella audit-log list
  • optional: --matter-id, --action, --resource-type, --resource-id, --user-id, --from, --to
• stella capability describe
  • --capability — Capability id to describe, as returned by list_capabilities (e.g. "time-entries.create"). (string)
• stella capability invoke
  • --capability — Capability id to invoke, as returned by list_capabilities. (string)
  • optional: --validate-only
• stella capability list
  • optional: --domain, --access (all|read|write)
• stella case-law read
  • --decision-id — Case-law decision ID (string)
• stella case-law search
  • --query — Search query (string)
  • --country — Required corpus country code (string)
  • optional: --court, --language, --decision-type, --source-id, --date-from, --date-to
• stella clause delete
  • --clause-id — Clause id to delete (string)
• stella clause list
  • optional: --clause-id, --version-id, --category-id, --query, --include-categories
• stella clause save
  • optional: --clause-id, --title, --category-id, --language, --description, --usage-notes, --snapshot-version
• stella contact delete
  • --contact-id — Contact ID to delete (string)
• stella contact list
  • optional: --query, --type (person|organization)
• stella contact lookup-registry
  • --registry — Business register to query (enum: ares, brreg, companies-house, denue, edgar, gcis, krs, orsr, prh, recherche-entreprises, vies)
  • --query — Canonical identifier (e.g. company number, VAT number) or company name (string)
• stella contact read
  • --contact-id — Contact ID (string)
• stella contact save
  • optional: --contact-id, --type (person|organization), --display-name, --first-name, --last-name, --organization-name, --notes
• stella document content
  • --entity-id — Entity ID (string)
• stella document delete
  • --entity-id — Document entity ID to delete (string)
  • optional: --version-id
• stella document field set
  • --entity-id — Document entity ID whose cell to set (string)
  • --property-id — Property ID, as returned by list_properties (string)
• stella document list
  • --matter-id — Matter ID to list documents in. (string)
  • optional: --mode (flat|children), --parent-id
• stella document properties list
  • --matter-id — Matter ID to list properties for. (string)
• stella document read
  • --entity-id — Document entity ID (string)
  • optional: --version-id, --compare-with-version-id, --include-versions, --versions-cursor
• stella document save
  • optional: --entity-id, --matter-id, --name, --parent-id, --kind (document|folder), --move-to-root, --version-id, --label, --description
• stella feedback prepare
  • --kind — Feedback category: bug, feature_request, docs, or other (enum: bug, feature_request, docs, other)
  • --title — Short one-line summary of the issue; no tenant data, ids, or secrets (string)
  • --body — Markdown details: reproduction steps, expected vs actual behavior, environment. Never include tenant data, client or matter names, ids, or secrets; they are redacted server-side. (string)
  • optional: --channel (github)
• stella invoice list
  • optional: --matter-id, --invoice-id
• stella legislation search
  • optional: --query, --title, --department-code, --legal-range-code, --matter-code, --date-from, --date-to, --law-id, --block-id, --relation-type (modifies|modifiedBy|derogates|derogatedBy|all), --full-text
• stella matter delete
  • --matter-id — Matter ID to delete (string)
• stella matter link-contact
  • --matter-id — Matter ID (string)
  • optional: --contact-id, --role (opposing_party|opposing_counsel|co_counsel|witness|expert_witness|third_party|judge|mediator|other), --matter-contact-id
• stella matter list
  • optional: --matter-id, --status (active|all)
• stella matter save
  • optional: --matter-id, --name, --client-id, --reference, --billing-reference, --status (active|archived)
• stella organization add-member
  • --matter-id — Matter ID for add_member and remove_member. (string)
  • --user-id — User id to add or remove for the member actions (string)
• stella organization remove-member
  • --matter-id — Matter ID for add_member and remove_member. (string)
  • --user-id — User id to add or remove for the member actions (string)
• stella organization set-jurisdictions — no flags; pass --input with jurisdictions
• stella organization update-settings
  • optional: --matter-number-pattern, --matter-number-padding, --prompt-caching-enabled, --document-processing-mode (off|searchable-text)
• stella playbook list
  • optional: --playbook-id
• stella playbook run
  • --matter-id — Matter ID to run the playbook over. (string)
  • --playbook-id — Playbook id to run (string)
• stella rate resolve
  • --matter-id — Matter ID to resolve the rate in. (string)
  • --user-id — User ID to resolve the rate for (string)
  • --date — Date to resolve the rate on (ISO YYYY-MM-DD) (string)
• stella search matters
  • --query — Search query (string)
• stella task delete
  • --task-id — Task entity ID to delete (string)
• stella task list
  • optional: --matter-id, --task-id, --date-from, --date-to, --status
• stella task save
  • optional: --task-id, --matter-id, --name, --status (open|in_progress|in_review|done|cancelled), --priority (none|urgent|high|medium|low), --item-type (task|fact|issue|requirement|event), --list-id, --list-section-id, --list-description, --due-date, --workflow-reason, --add-assignee-user-id, --remove-assignee-user-id, --link-entity-id, --unlink-link-id
• stella template configure-fields
  • --template-id — Template to configure, as returned by create_template or list_templates (string)
• stella template create
  • optional: --template-id, --name, --docx-base64, --file.download-url, --file.file-id, --file.mime-type, --file.file-name
• stella template fill
  • --template-id — Template id, as returned by list_templates (string)
  • optional: --allow-unused-values, --completion-mode (require_complete|allow_partial), --output-mode (text|docx)
• stella template list
  • optional: --template-id
• stella template save-filled new-document
  • --template-id — Template id, as returned by list_templates (string)
  • --matter-id — Matter receiving the filled DOCX. (string)
  • --idempotency-key — Unique retry key for this save operation; reuse it only to recover the same timed-out request (string)
  • optional: --parent-id, --name, --completion-mode (require_complete|allow_partial)
• stella template save-filled new-version
  • --template-id — Template id, as returned by list_templates (string)
  • --matter-id — Matter receiving the filled DOCX. (string)
  • --idempotency-key — Unique retry key for this save operation; reuse it only to recover the same timed-out request (string)
  • --entity-id — Existing document entity id; required only for create_version (string)
  • optional: --name, --completion-mode (require_complete|allow_partial)
• stella time-entry delete
  • --time-entry-id — Time entry ID to delete or write off (string)
• stella time-entry list
  • optional: --matter-id, --time-entry-id, --entity-id, --user-id, --date-from, --date-to, --status (draft|approved|billed|written_off)
• stella time-entry save
  • optional: --time-entry-id, --matter-id, --entity-id, --date-worked, --timezone-id, --duration-minutes, --narrative, --invoice-narrative, --billable, --no-charge, --task-code, --activity-code
• stella usage get — no arguments

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 330 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; matter-scoped capabilities take a required --matter-id <id>. Deep or ambiguous payloads use --input (the whole { body?, params?, query? }).
• Dry run: write capabilities accept --dry-run, which validates the input server-side and returns without executing (maps to validate_only).
• 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).

When no curated command fits

The curated commands above cover common tasks; anything else goes through the generic capability path. Current domains: audit-logs, billing-codes, case-law, catalogue, chat, clauses, contacts, document-translations, document-types, entities, expenses, fields, flows, invoices, legislation, lists, matters, organization-settings, playbooks, properties, rates, reports, signals, skills, style-sets, tasks, template-packs, template-recipes, templates, time-entries, uploads, usage, view-templates, views, work-obligations.

• Start a document translation run: stella capability document-translations runs-create --matter-id <matter-id> --input '{"body":{"entityId":"00000000-0000-4000-8000-000000000000","fieldId":"00000000-0000-4000-8000-000000000000","targetLang":"value","engine":"deepl","output":"translated"}}'.
• Start workflow extraction: stella capability matters workflow-start --matter-id <matter-id> --input '{"body":{"serviceTier":"standard"}}'.
• --input casing is not uniform; never guess it. A curated command's --input JSON (the table and flags above) uses the MCP tool schema's own keys, snake_case (matter_id, contact_id). A capability command's --input JSON uses the handler schema's own keys, camelCase (fieldId, matterId). Run stella <command> --help or stella capability describe <id> and copy the field paths it prints.

Preparing feedback

stella feedback prepare drafts a bug, feature request, or docs issue for 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.