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"
---

<!-- GENERATED by `bun run codegen` (packages/cli/src/generate-skill.ts). Do not edit by hand. -->

# 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

```sh
npm i -g @stll/cli
```

## Authenticate

```sh
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> --workspace-id <workspace-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 send`                     | 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 list`                         | read                        | paginated                             |
| task         | `stella task save`                         | matters_write               |                                       |
| template     | `stella template fill`                     | templates                   |                                       |
| template     | `stella template list`                     | templates                   | paginated                             |
| template     | `stella template save`                     | templates                   |                                       |
| 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: --workspace-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`
  - `--workspace-id` — Workspace ID to list documents in. Deprecated input alias: matter_id. (string)
  - optional: --mode (flat|children), --parent-id
- `stella document properties list`
  - `--workspace-id` — Workspace ID to list properties for. Deprecated input alias: matter_id. (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, --workspace-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: --workspace-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`
  - `--workspace-id` — Workspace id for add_member and remove_member. Deprecated input alias: matter_id. (string)
  - `--user-id` — User id to add or remove for the member actions (string)
- `stella organization remove-member`
  - `--workspace-id` — Workspace id for add_member and remove_member. Deprecated input alias: matter_id. (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`
  - `--workspace-id` — Workspace id to run the playbook over. Deprecated input alias: matter_id. (string)
  - `--playbook-id` — Playbook id to run (string)
- `stella rate resolve`
  - `--workspace-id` — Workspace ID to resolve the rate in. Deprecated input alias: matter_id. (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: --workspace-id, --task-id, --date-from, --date-to, --status
- `stella task save`
  - optional: --task-id, --workspace-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)
  - `--workspace-id` — Workspace receiving the filled DOCX. Deprecated input alias: matter_id. (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)
  - `--workspace-id` — Workspace receiving the filled DOCX. Deprecated input alias: matter_id. (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: --workspace-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, --workspace-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 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 (`workspace_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.