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. Scope the session with --scopes; the default scopes are openid profile email offline_access 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.
• 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.

• 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)
  • optional: --court, --country, --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/workspace ID to list documents in (string)
  • optional: --mode (flat|children), --parent-id
• stella document properties list
  • --matter-id — Matter/workspace 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 send
  • --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/workspace ID to delete (string)
• stella matter link-contact
  • --matter-id — Matter/workspace ID (string)
  • optional: --contact-id, --role (opposing_party|opposing_counsel|co_counsel|witness|expert_witness|third_party|judge|mediator|other), --workspace-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/workspace 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/workspace 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/workspace id to run the playbook over (string)
  • --playbook-id — Playbook id to run (string)
• stella rate resolve
  • --matter-id — Matter/workspace 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 list
  • optional: --matter-id, --task-id, --date-from, --date-to, --status
• stella task save
  • optional: --task-id, --matter-id, --name, --status, --priority, --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 fill
  • --template-id — Template id, as returned by list_templates (string)
  • optional: --allow-unused-values, --completion-mode (require_complete|allow_partial)
• stella template list
  • optional: --template-id
• stella template save
  • optional: --template-id, --name, --docx-base64
• stella template save-filled new-document
  • --template-id — Template id, as returned by list_templates (string)
  • --matter-id — Matter/workspace 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
• stella template save-filled new-version
  • --template-id — Template id, as returned by list_templates (string)
  • --matter-id — Matter/workspace 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
• 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

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 323 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 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-types, entities, expenses, fields, flows, invoices, legislation, lists, 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, workspaces.

• Translate a document: stella capability entities translate --workspace <workspace> --field-id <field-id> --target-lang <target-lang>.
• Start workflow extraction: stella capability workspaces workflow-start --workspace <workspace>.
• --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, workspaceId). Run stella <command> --help or stella capability describe <id> and copy the field paths it prints.

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.