@sr-connect/cli 0.1.0

package/README.md

@@ -0,0 +1,554 @@
+# @sr-connect/cli
+
+A CLI to work with [ScriptRunner Connect](https://scriptrunnerconnect.com). Run it with nothing but a verb and it asks for what it needs. Run it with flags and `--agent` and it never asks, which is what scripts and AI agents want.
+
+```sh
+npx @sr-connect/cli                  # no install; lists the command groups
+npm i -g @sr-connect/cli             # then: sr-connect
+npx @sr-connect/cli cli get-readme   # prints this document from the installed copy
+```
+
+Node 22 or newer. An older runtime gets one warning line per run and most commands still work, but live log streaming does not. Every example below spells the CLI as `npx @sr-connect/cli`, which is also how it refers to itself in its own hints. For daily use install it globally: `npx` spends most of a second resolving the package before the CLI starts, and the installed `sr-connect` answers in a fraction of that.
+
+## Getting started
+
+### Log in
+
+```sh
+npx @sr-connect/cli auth login
+```
+
+Login asks three things. Which instance to talk to: `EU`, `US`, or the base URL of a self-hosted server. Your account e-mail and an API key, which you generate in the web application under your profile's API Keys page; the prompt links to the right page for the EU and US instances. And whether agents may send feedback to the ScriptRunner Connect team on their own, which you can change later with `cli settings`.
+
+The API key goes into the operating system's secure store: macOS Keychain, Windows Credential Manager, or Secret Service on Linux (GNOME Keyring, KWallet). On a machine without one, a headless Linux server for example, pass `--insecure-storage` to keep it in a file only you can read. `auth status` verifies the stored key against the instance and `auth logout` removes it.
+
+### Find your way around
+
+Commands are arranged in groups of verbs: `script` is a group, `script get` is a verb in it. Typing a group with no verb, or the root with no group, prints what lives underneath. `--help` is only needed for a verb's flags.
+
+```sh
+npx @sr-connect/cli                   # the groups
+npx @sr-connect/cli script            # the verbs in a group
+npx @sr-connect/cli script get        # runs it; anything missing is asked for
+npx @sr-connect/cli script get --help # the flags, each ending in its conditions
+```
+
+A verb run without its required values walks you through them. Team, then workspace, then environment, then the resource itself, each as a filterable list. A list with one entry is still shown, so you always see what is about to be touched. Every option in `--help` ends in a parenthesis of conditions: `required` or `optional`, whether it is asked for interactively, whether a session default or an environment variable can supply it, and anything it is exclusive with or refused alongside.
+
+Twelve groups have a short alias, shown in each group's heading under [Commands](#commands) (`el` for `event-listener`, `ac` for `api-connection`, and so on). The alias covers every verb in the group.
+
+### Session defaults
+
+After you have picked a team, a workspace and an environment, the CLI offers to remember them for the shell you are in. Say yes and the next command in that terminal asks `Use session defaults: team "…", workspace "…"?` instead of walking the lists again. Declining that question resolves for one run only. Declining the offer to remember is itself remembered, so it is not asked twice.
+
+The record lives for 12 hours and belongs to one terminal window and one instance. `cli set-session` sets it deliberately and verifies what it is about to store, so a mistyped ID is refused rather than written and blamed on the next command; `cli clear-session` forgets it, `--no-session` ignores it for one run. Deleting a workspace or environment drops it from the record. Logging out clears every terminal's defaults, keeping a workspace lock still held so it can be given back.
+
+A **workspace lock** rides the same record but is not a default, so clearing the scope keeps it: a clear that leaves one names the lock and the command that gives it back. Dropping the ID would strand the lock on the server, where it would refuse this shell's own later writes as another session.
+
+### Work from a local copy
+
+`local-workspace clone` writes a workspace to disk as a TypeScript project: one file per script under `scripts/`, one module per API connection under `scripts/api/`, the parameter types in `ev-params.ts`, the README, the test payloads, and a `workspace.json` recording where it all came from. Open it in an editor, get type checking against the real API packages, commit it to git.
+
+**The clone answers the scope questions.** Any command run at or below the directory takes its team, workspace and environment from `workspace.json`. On a terminal you are asked once, `Use the local workspace in ~/dev/x …?`. Without one the CLI prints a note and carries on, so this applies to agents as much as to people. A flag that names a different team or workspace wins, and the whole record is set aside for that run with a note, so the other two have to be passed as well. A flag naming a different environment of the same workspace keeps the record's team and workspace and replaces only the environment, which is how `-e <staging>` inside a clone of `Default` reads the other environment. `--no-local-workspace` switches the behaviour off.
+
+Commands that change something the clone contains also keep the clone current. See [Local sync](#local-sync).
+
+## For agents
+
+**Pass `--agent` on every call, or set `SR_CONNECT_CLI_AGENT=1` once.** That is the whole of it: `--agent` switches off every question on its own, so anything missing becomes exit 2 instead of a hang, and it tells the API that an agent is driving. You do not also need `--no-prompts`, which is the same prompt switch without the declaration and is there for scripts that are not agents. `--agent` does not change what stdout looks like — pair it with `--raw`, or set `SR_CONNECT_CLI_RAW=1` beside the other one.
+
+- **Ask a verb what it takes before calling it — this is the fastest thing in the CLI, and it is where the per-verb documentation lives.** Every verb takes `--explain`: on stdout the example `--input` body where the verb has one and `{}` where it does not, and on stderr a sentence per parameter plus notes on everything the parameters do not cover — outcomes, exit codes, the shape of the document it answers with. Exit 0, no credentials, no scope, no request. This document does not repeat any of it, so `--explain` is the answer rather than a second opinion. Run it before a flags-only call too: a body key is a flag under another spelling, and the rule says which (`version` is `--package-version`, `eventListenerTypeId` is `--listener-type-id`, `waitForResponse` is `--wait`).
+
+    ```sh
+    npx @sr-connect/cli event-listener update --explain          # what it accepts, and when each thing is refused
+    npx @sr-connect/cli log list-invocation-logs --explain       # a verb with no body answers the same way
+    ```
+
+- **Add** `--raw` **by default**, or set `SR_CONNECT_CLI_RAW=1` once. It gives one compact JSON document on stdout, exactly as the API sent it, and errors as a JSON envelope on stdout. Nothing refuses it except `log list-console-logs --expand-large` and `log list-http-logs --verbose`. Two verbs are worth reading **without** it, and the reason is size rather than taste: `log list-console-logs` renders 2 KB where the stored file is 5 KB of `{values:[{type,value}]}` wrappers, and `log list-http-logs` renders 160 bytes where the file is 1.3 KB. Both render what you would otherwise rebuild. Keep `--raw` everywhere else, the other two log listings included: their tables print the environment and the script by name, and the IDs are what the next call takes. See [Output](#output).
+
+    ```sh
+    npx @sr-connect/cli script create --explain --raw > body.json   # rules on stderr
+    # edit body.json, then
+    npx @sr-connect/cli script create -w <workspaceId> -e <environmentId> --input body.json --raw --agent
+    ```
+
+- **Supply scope with flags or environment variables.** `-w`, `-e` and `--team`, or `SR_CONNECT_CLI_WORKSPACE`, `SR_CONNECT_CLI_ENVIRONMENT` and `SR_CONNECT_CLI_TEAM`. A `workspace.json` at or above the working directory also supplies all three, with a stderr note. Session defaults are read too, and announced.
+- **Credentials come from the environment.** `SR_CONNECT_CLI_USERNAME` and `SR_CONNECT_CLI_PASSWORD` replace a stored login entirely. They are not inputs to `auth login`; with them set, no login is needed. `SR_CONNECT_CLI_INSTANCE` names the instance.
+- **Destructive verbs need** `--yes`**.** Without it, and without a terminal, they exit 2 having done nothing. `workspace update` takes one too, for its `--team` move alone: an ordinary update never needs it, and a move without it is exit 2 `CONFIRMATION_REQUIRED`. Four operations confirm only on a terminal and have no `--yes`: `connector-sharing set`, `environment target-release`, `script replay-invocation` and `script abort-invocation`.
+- **`--version` belongs to the root.** Passed beside a verb it is exit 2 naming the flag the verb meant, because it used to print the CLI's version and exit 0 having sent nothing. The flags are `--release-version` and `--package-version`.
+- **A streamed run narrates, it does not record.** `script trigger --stream-logs` prints rows as the frames arrive, and the order they are sent in is not guaranteed, so two lines can appear swapped. The stored file is ordered: read `log list-console-logs` when the order of two lines carries meaning.
+- **Read the exit code.** 0 ok, 1 the API or the run failed, 2 usage, 3 not authenticated, 4 not found or an empty lookup, 130 cancelled. See [Exit codes](#exit-codes).
+- **Read this document with** `cli get-readme`**.** It needs no credentials. Under `--raw` it prints the markdown source. It is orientation — what a verb takes is `--explain` on the verb.
+- **Every request is recorded locally** for troubleshooting, with secrets redacted. `cli list-api-logs` reads the record back and needs no credentials.
+- **Take the workspace lock before a series of edits** with `workspace-lock take`, even though every write takes one on its own. When somebody else holds it, never pass `--force` on your own: stop and ask the user whether to take it over. The one exception is a refusal that says the holder is **you** — "another session of yours, taken through the API" — where the hint says taking it back costs nobody anything, because it does. Trust the lapse time the CLI prints over any number in this document.
+- **Push content, but rename and delete by ID.** `local-workspace push` is the way to change the content of several scripts at once. For a rename or a deletion use `script update --name` and `script delete`, which name the script by its ID, where a push has to infer a rename from content.
+- **Give the lock back after a one-off write.** Every write takes the workspace lock and keeps it for the rest of a fifteen-minute lease, which is what you want for a series of edits and not for a single scripted change: until it lapses, a colleague's write is refused and names you. `workspace-lock release -w <workspaceId>` after the last write of a one-off run costs one request and saves them the wait.
+- **Cache `app list` for the session.** Every event listener, API connection and connector verb takes IDs from it, and the catalogue almost never changes.
+- **Create workspaces with `--language ts-strict`.** A workspace made from another workspace or a template inherits its language; check it and upgrade with `workspace update --language ts-strict`.
+
+## Global switches
+
+Accepted by every command. A flag beats its environment variable, and both beat a stored setting; off wins from any of the three.
+
+| flag                           | env var                                | effect                                                                                                                                                                                                                                                |
+| ------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--instance <instance>`        | `SR_CONNECT_CLI_INSTANCE`              | `eu`, `us`, or a base URL. Overrides the stored instance                                                                                                                                                                                              |
+| `--raw`                        | `SR_CONNECT_CLI_RAW=1`                 | Compact JSON on stdout. Not an agent switch: on a terminal, prompts still appear, on stderr. The only switch here that changes the shape of stdout, and the one `cli settings` does not report, so a stale export shows up as output looking wrong    |
+| `--agent`                      | `SR_CONNECT_CLI_AGENT=1`               | Declares an agent is driving and switches every prompt off. An explicit `0`, `false`, `no`, `off` or empty value reads as off                                                                                                                         |
+| `--no-prompts`                 | `SR_CONNECT_CLI_NO_PROMPTS=1`          | Switches every prompt off without the declaration                                                                                                                                                                                                     |
+| `--no-session`                 |                                        | Ignore this shell's session defaults                                                                                                                                                                                                                  |
+| `--no-local-workspace`         | `SR_CONNECT_CLI_NO_LOCAL_WORKSPACE=1`  | Do not take scope from a `workspace.json` at or above the working directory                                                                                                                                                                           |
+| `--copy-output-to-file [file]` |                                        | Append everything stdout gets to a file too. Default name `output-<unix-ts>.json`, or `.txt` without `--raw`. Put it after the command, or name the file: the value is optional, so a bare flag ahead of the command takes the group name as the file |
+| `--no-record-api-calls`        | `SR_CONNECT_CLI_NO_RECORD_API_CALLS=1` | Do not record this run's requests                                                                                                                                                                                                                     |
+| `--no-lock`                    | `SR_CONNECT_CLI_NO_LOCK=1`             | Write without taking or presenting a workspace lock. The API applies such a write whether or not somebody else holds the lock, so this is the one switch here that can overwrite an edit in progress                                                  |
+| `--lock-id <lockId>`           | `SR_CONNECT_CLI_LOCK_ID`               | Present this lock on writes instead of the one the shell holds; never remembered by the shell                                                                                                                                                         |
+| `--no-local-sync`              | `SR_CONNECT_CLI_NO_LOCAL_SYNC=1`       | Do not update a local copy of the workspace a command changes                                                                                                                                                                                         |
+| `--no-update-check`            | `SR_CONNECT_CLI_NO_UPDATE_CHECK=1`     | Do not look NPM up for a newer version, and print no notice                                                                                                                                                                                           |
+| `--no-version-gate`            | `SR_CONNECT_CLI_NO_VERSION_GATE=1`     | Run even when the server declares this CLI version unsupported                                                                                                                                                                                        |
+| `--no-crash-reports`           | `SR_CONNECT_CLI_NO_CRASH_REPORTS=1`    | Do not write or offer a crash report                                                                                                                                                                                                                  |
+| `--no-agentic-feedback`        | `SR_CONNECT_CLI_NO_AGENTIC_FEEDBACK=1` | `feedback post` and `post-crash-report` are refused unless a human is answering                                                                                                                                                                       |
+| `-V, --version`                |                                        | Print the CLI version                                                                                                                                                                                                                                 |
+
+Five of these can be turned off for good with `cli settings`: recording, locking, local sync, crash reports and agentic feedback. The others are per run or per shell only.
+
+One shape difference worth knowing: `cli settings`, `cli list-api-logs` and `cli list-crash-reports` answer with a bare JSON array, where every API-backed list answers with a named key (`{"teams":[…]}`). They are the CLI's own state rather than a response passed through, and the shape is kept for callers that already read it.
+
+Other environment variables the CLI reads: `SR_CONNECT_CLI_USERNAME` and `SR_CONNECT_CLI_PASSWORD` (credentials), `SR_CONNECT_CLI_TEAM`, `SR_CONNECT_CLI_WORKSPACE` and `SR_CONNECT_CLI_ENVIRONMENT` (scope), `SR_CONNECT_CLI_BASIC_AUTH_PASSWORD` (the password for `connector create --basic-auth-username`), `SR_CONNECT_CLI_DISABLE_KEYCHAIN` (any value makes the keychain unavailable), `SR_CONNECT_CLI_STATE_HOME` (the root the state directory sits under, see below), `SR_CONNECT_CLI_SESSION_ID` (names the shell session when the terminal cannot), `SR_CONNECT_CLI_NPM_REGISTRY` (a mirror for the NPM lookups).
+
+Where the CLI keeps its files:
+
+| what                                                                  | macOS and Linux              | Windows                      | override                                                                             |
+| --------------------------------------------------------------------- | ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------ |
+| The instance, and the credentials file with `--insecure-storage`      | `~/.config/sr-connect/`      | `%APPDATA%\sr-connect\`      | `XDG_CONFIG_HOME` replaces the root on any platform                                  |
+| Session defaults, API-call recordings, crash reports, `settings.json` | `~/.local/state/sr-connect/` | `%LOCALAPPDATA%\sr-connect\` | `SR_CONNECT_CLI_STATE_HOME`, then `XDG_STATE_HOME`, replace the root on any platform |
+
+The API key itself is in the operating system's secure store unless `--insecure-storage` was used.
+
+## Instances
+
+An instance is `eu`, `us`, or the base URL of a self-hosted server (`https://api.example.com`; the scheme may be omitted, a path prefix is kept, credentials, query and fragment are refused). Resolution is `--instance`, then `SR_CONNECT_CLI_INSTANCE`, then what `auth login` stored in the config directory.
+
+IDs are instance-scoped, so this shell keeps one session record **per instance**: defaults and workspace locks recorded against another instance are never reused, and never destroyed either — switching away and back finds them where they were. A `workspace.json` from another instance neither supplies scope nor accepts a push. A plain `http://` instance prints a warning that credentials travel unencrypted; loopback is exempt.
+
+## Output
+
+**Human mode** is the default, even when stdout is a pipe. Lists are tables with the ID first, single resources a `LABEL value` detail view, mutations a green `✔ … created:` line followed by the detail. Prompts and spinners go to stderr, and so do notes and warnings. Three shapes, and which modes each prints in is worth knowing: a `⚠` warning prints in **both** modes, a `✔` status note only in human mode, and a **plain note with no glyph** in both. So `--raw` still tells you about anything the run carried on past, and stays quiet about what it merely did (the local sync's `✔ Local copy updated: …` among it). The glyphless ones say where a value came from rather than what happened — `Using session defaults: …` and `Using the local workspace in …` — and they print under `--raw` on purpose: the line naming the workspace a command was pointed at matters as much to an agent as to a person. Only the document goes to stdout.
+
+`--raw` prints exactly one compact JSON document on stdout per run. API responses pass through untouched; no field is filtered or renamed. A response with no body becomes `{"updated":true,"id":…}` or `{"deleted":true,"id":…}`. Errors are one envelope on stdout:
+
+```json
+{ "error": { "code": "NOT_FOUND", "message": "…", "status": 404, "hint": "…" } }
+```
+
+Exceptions, all listed here and noted again at the verb:
+
+- **Nine verbs print a file rather than a document.** Whether `--raw` changes anything is the column that matters, and byte-exact means exactly that: nothing added, nothing trimmed, so `… > file` reproduces what is stored. That is what a released environment's echo rule and a clone's checksums both depend on. The cost is the one `cat` pays: a file whose last byte is not a newline leaves the shell prompt mid-line.
+
+    | verb                                             | what `--raw` selects                       | byte-exact         |
+    | ------------------------------------------------ | ------------------------------------------ | ------------------ |
+    | `log get-invocation-payload`                     | the stored payload over the rendered one   | yes, under `--raw` |
+    | `log list-console-logs`                          | the stored file over the rendered console  | yes, under `--raw` |
+    | `log list-http-logs`                             | the stored file over the rendered table    | yes, under `--raw` |
+    | `log get-large-log-message`                      | the stored bytes (still JSON)              | yes, under `--raw` |
+    | `readme get --content-only`                      | the markdown source over the rendered form | yes, under `--raw` |
+    | `cli get-readme`                                 | the markdown source over the rendered form | yes, under `--raw` |
+    | `script get --content-only`                      | nothing — same bytes either way            | always             |
+    | `event-listener-test-payload get --content-only` | nothing — same bytes either way            | always             |
+    | `cli get-crash-report --content-only`            | nothing — same bytes either way            | always             |
+
+    The last three take no envelope in either mode. The six above them render for a terminal without `--raw`, and a rendered form is not the stored one: `readme get --content-only` prints markdown through the renderer, which is where the trailing newline you may notice comes from.
+
+- **A human answering prompts can produce several documents**: paging through `log list-audit-logs` or `log list-invocation-logs`, and a `script create` or `update` that accepted the offer to run the script. Agents never reach either.
+- **Refused with** `--raw`: `log list-console-logs --expand-large` and `log list-http-logs --verbose`.
+- `--dry-run` **on** `connector-sharing set` **and** `remove` prints an impact report as the document instead of the API's response.
+- **An update whose answers change nothing prints nothing.** No request is made and a stderr note says so. This is the interactive updates. `environment target-release` is the one exception in both directions: it reads the environment first on the **flags** path too, so `--head` on an environment already running HEAD and a release ID naming the release already deployed both send nothing — and because that is the one state a scripted caller reaches, it answers a document rather than silence, `{"updated":false,"id":…,"reason":"already-current"}`, with the sentence in its place in human mode.
+- `--explain` prints the example body pretty in human mode and compact under `--raw`, and `{}` in both where the verb sends no body; the key lines, rules and notes go to stderr either way.
+- **A group typed with no verb prints its help on stdout and exits 0**, under `--raw` as well: `npx @sr-connect/cli team --raw` lists the verbs rather than answering a document. Nothing was resolved and nothing was asked for, so there is no response to shape — it is the same screen `--help` prints. An agent that reaches this has typed an incomplete command; a verb always answers a document.
+
+Warnings are yellow stderr lines starting `⚠` and print in both modes. A `⚠` means the run carried on with something other than what you asked; `✖` means it failed.
+
+`--copy-output-to-file` mirrors stdout to a file, ANSI stripped: the file gets the bytes stdout got, and a rendered document gets the newline that separates it from the next one. A verb whose document _is_ a file gets neither an added byte nor a separator, so the copy of a `--content-only` read is the stored bytes too. The file is opened before anything prints, so an unwritable path fails the run before any output. The six `log` verbs also offer the copy interactively before their first output. The file name is optional, and the flag takes the next word as the name unless it starts with `-`: `--copy-output-to-file team list` would write to a file called `team` and run nothing, so the CLI refuses a value that names a command group, exit 2 `OUTPUT_FILE_ERROR`. Put the flag after the command, or name the file.
+
+## Exit codes
+
+| code | meaning                                                                                                                                                                                                                            |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | Done. Also a save whose TypeScript diagnostics were reported, a push with nothing to send, and a list that came back empty                                                                                                         |
+| 1    | The API refused for a reason of its own, the run failed, a lock was lost, a push was partial                                                                                                                                       |
+| 2    | Usage: a missing value nobody could be asked for, a bad flag, an exclusive pair, a name or body **this CLI** refused, a confirmation without `--yes`, an unsupported CLI version                                                   |
+| 3    | Not authenticated, or the credentials were rejected                                                                                                                                                                                |
+| 4    | A single resource that does not exist. Also `workspace-lock check` when nobody holds the lock, and a write whose workspace is gone — the lock the CLI takes first answers 404 and the verb reports that rather than a lock failure |
+| 130  | Cancelled: Ctrl-C, or a confirmation declined                                                                                                                                                                                      |
+
+**The line between 1 and 2 is who refused, not how bad it was.** Anything the CLI validates before
+sending is exit 2 with a named code; **every 400 from the API is exit 1** with `BAD_REQUEST`. So
+`script create --name "bad name!"` is exit 2 `INVALID_SCRIPT_NAME` and a duplicate name is exit 1,
+though both are your command to fix. A mistyped ID is exit 2 `INVALID_ID` for the same reason: the
+shape is published, so the CLI owns it, while "no such workspace" is exit 4 and needs the API. Which rules the CLI checks itself is listed under
+[Validated before sending](#validated-before-sending). A **403** is exit 1 too: the API answers it
+rather than saying whether the ID exists.
+
+**Two statuses are retried before you ever see them.** A `429` (rate limited) and a `503` (the API
+could not reach its database for that request) are resent up to three times, honouring
+`Retry-After`, with one dim stderr line per wait naming which of the two it was. A `503` that
+outlives all four attempts is exit 1 `SERVICE_UNAVAILABLE`, and its hint says what the status
+guarantees: the request never ran and nothing changed, so the same command is safe to send again.
+A `500` is different and is not retried — it is reported as a crash you can send with
+`feedback post-crash-report`.
+
+**An empty list is exit 0**, not 4. `script list` in an empty workspace prints `{"scripts":[]}` and
+succeeds, and so does a `log list-invocation-logs` whose filters match nothing. Exit 4 is for a
+single resource that is not there.
+
+## Validated before sending
+
+A rule this document or `--help` states, the CLI checks itself, and a failure is exit 2 with a
+named code and no request made. That covers script, connector, event queue, test payload,
+environment and workspace names, the API connection path, an event listener's URL path, a
+parameter key, a CRON expression, a release version and label, the eviction policy, an attachment
+and its name, `--page-size`, and every enumerated flag (`--type`, `--language`, `--visibility`,
+`--execution-status`, `--order-by`, `--timestamps`, …). Exclusive flag pairs and a missing
+required value are the same: exit 2, before anything is sent.
+
+**Every ID is checked too.** The API's IDs are ULIDs — 26 upper-case characters — and it refuses
+a malformed one with a 400, so the CLI refuses it first: exit 2 `INVALID_ID`, naming where the
+value came from. That covers a scope flag, its `SR_CONNECT_CLI_`* variable, a session default, a
+clone's `workspace.json`, every positional that is an ID, `--lock-id`, and every `…Id` key of an
+`--input` body. Surrounding whitespace is trimmed rather than refused, so an ID pasted with a
+newline is the ID you meant. What it does not cover is whether the ID _exists_ or is yours, which
+is the API's 404 and 403, nor the opaque tokens the API hands back for paging — `--cursor` and
+`--next-token` are the API's to define and are sent as given. Lower case is refused rather than
+up-cased: the API stores IDs upper case, and quietly changing one would mean sending an ID you
+never typed.
+
+Three things are deliberately the API's, and they come back as exit 1:
+
+- **Uniqueness.** Whether a name is already taken needs the list the API holds, and its refusal
+  names the clash. A local check could only ever disagree with the authority.
+- **An email address's shape.** `feedback post --email` is checked for a length and for having
+  one `@` with something either side. Nothing finer: a guessed pattern is how a legal address gets
+  refused, and `"weird local part"@example.museum` is legal.
+- **An NPM package name.** Same reason. Scopes and the registry's own history make the real rule
+  wider than any regex worth writing, so `package add` sends the name and reports
+  `Invalid package name format.` if the API disagrees.
+
+Everything a **released environment** refuses is the API's too, and on purpose: the CLI does not
+pre-check a flags-driven run against the environment's own state, so those are exit 1 with the
+message naming the field. See [How commands work](#how-commands-work).
+
+## Workspace locks
+
+A workspace has one editing lock, shared with the web application. Before every write the CLI takes it, or reuses the one this shell already holds, and renews it as writes continue. You see one extra spinner on a fresh workspace and nothing afterwards.
+
+When someone else holds it, a terminal gets a question naming the holder and how they are editing, with three answers: cancel, take the lock, or continue without it. Taking it from a browser tab makes that tab lose edit control at once. Without a terminal the write stops with exit 1 `WORKSPACE_LOCKED` and a hint naming `workspace-lock take --force`. Two lock IDs from one account conflict exactly as two people do, so the refusal says which case it is: another session **of yours** through the API, your own browser tab, or somebody else. A lock that lapsed between two commands is taken again and the write re-sent once, with one dim line saying so. A lock taken for a write the API then refuses with a 4xx is given back in the same run, so a command that wrote nothing leaves nothing held; one the shell already had is kept, and so is a lock on a `409` the command retries with `--force`.
+
+Only a 409 that is about the lock is recovered from. The API answers 409 for other things — a script an event listener still uses, an invocation that has already finished — and those reach the command as themselves, with their own code and hint.
+
+`--lock-id` presents a lock taken elsewhere, for a pipeline step that cannot keep shell state; it is redacted from every recording and never written into the shell's record, so the next command in the shell presents its own lock again. A lock belongs to the account that took it, so an ID is not transferable between accounts: presenting another user's live lock is refused exactly like presenting one that holds nothing, on the write, the renewal and the release alike. Two pipeline steps sharing a lock ID have to share the API key too. `--no-lock` writes without one, and a write presenting no lock is **applied whether or not somebody else holds it** — measured, with another account's lock live: the same write is `WORKSPACE_LOCKED` with the lock the CLI would take for it, and a `204` with `--no-lock`. So the flag is not a way to work politely alongside somebody, it is a way to write straight past them; the lock stays where it was and its holder is never told. Reach for it in a pipeline step that cannot keep shell state, not to get around a conflict. A lock the shell remembers is recorded with the account that took it: a second account in the same terminal is told the recorded lock belongs to the first and takes its own, so the API reports the conflict rather than handing the lock over. `script trigger`, `replay-invocation` and `abort-invocation` never take a lock: they run a script rather than edit the workspace. `workspace delete` presents the lock like any other write and goes through on its own; it is refused only while somebody else holds one, with the holder named.
+
+## Local sync
+
+When a command changes something a clone contains, and you are standing in that clone, the file on disk is updated to match: a script saved, renamed or deleted; a test payload written or moved; `ev-params.ts` regenerated after a parameter change; `scripts/api/**` and `package.json` regenerated after an API connection or package change; `README.md` after `readme update`. `workspace.json` records the checksum of every file it wrote, so the next push has nothing to re-send for them. Nothing is refetched, and the sync can never fail or slow the command it follows.
+
+A local file that differs from what the clone last recorded is skipped with a warning rather than overwritten. When you edit a script, payload or README inline while its local copy has changed, the editor asks which version you mean. A clone that describes another workspace, environment or release gets one warning and is left alone. `environment target-release` and a deploy print a note that the clone needs re-cloning. `--no-local-sync` turns the sync off; it is a separate switch from `--no-local-workspace`, which governs reading scope from the clone rather than writing to it.
+
+## API call recording
+
+Every request the CLI makes is appended to a per-shell log under the state directory, for troubleshooting. Request headers are never recorded; response headers are an allowlist; bodies are capped at 4 KB with anything named like a password, token, secret or lock ID replaced by `<redacted>`; a Generic connector's header values and a feedback attachment's bytes are blanked. Files older than 7 days are swept. `cli list-api-logs` reads the log back and `cli clear-api-logs` deletes it; neither needs credentials. `--no-record-api-calls` switches recording off.
+
+## Crash reports
+
+When a run fails for a reason that is the CLI's or the server's, an unexpected error or a status of 500 or above, a markdown report is written under the state directory: version, command line with secrets removed, platform, the error and its stack, and this run's recorded API calls, capped at 512 KB. Usage errors, 4xx answers and cancellations never produce one.
+
+On a terminal with stored credentials you are asked whether to send it, review it first, or keep it. Otherwise two yellow lines name the file and the `feedback post-crash-report --report <id>` command that sends it later. Reports are pruned after 7 days or past 20. `cli list-crash-reports`, `cli get-crash-report` and `cli clear-crash-reports` manage them locally. `--no-crash-reports` switches the whole thing off.
+
+## Settings
+
+`cli settings` shows the five switches the CLI keeps for itself and, on a terminal, lets you change them for good. Only the offs are stored, in a file that survives `cli clear-session` and `auth logout`. A switch disabled by its environment variable cannot be toggled and is written as off. Under `--raw` the command only prints the table; it is the one place `--raw` suppresses a question, because the table is the answer a scripted run wants. All five are on until something turns them off: a flag for one run, an environment variable for a shell, or this command for good. Agentic feedback is on for a user who authenticates with `SR_CONNECT_CLI_USERNAME` and never ran `auth login`.
+
+## Concepts
+
+What each resource is, and what it belongs to. Everything a _verb_ does is `--explain` on that verb; this is the part no per-verb answer can carry.
+
+### api-connection (ac)
+
+An API connection is what a script imports as `./api/<path>` to talk to an app. Its path and its vendor API package belong to the workspace; the connector attached to it is environment-specific configuration. `create` is workspace-scoped, the other four are environment-scoped.
+
+### cli
+
+The CLI's own state. Every verb but `set-session` works without credentials or an instance, which is what you want when authentication is the thing that broke.
+
+### connector (con)
+
+A connector is an authorized account that an event listener or an API connection uses to reach an app. It belongs to a user and is looked up through a team, so this group's scope stops at `--team`. Connectors shared with you appear beside your own. `list` and `get` report each connector's `connectionType`, which is the app's own `connectionType` in `app list`; the API connection type a connector was created for is never reported back.
+
+### connector-sharing (cs)
+
+Lets the owner grant other users `use` and `edit` permission on a connector. `edit` allows renaming it and replacing its credentials, never deleting it. `use` allows attaching it to event listeners and API connections, in every team you share with that user or in named teams only. Every verb is owner-only; the connector picker offers only connectors you own. The user is the positional argument; the connector is `--connector-id`.
+
+### environment (env)
+
+Environments belong to a workspace and each runs either the workspace's current state (HEAD) or a release (non-HEAD). The environment is this group's resource, so `get`, `update` and `delete` take it as a positional argument; `-e` names the same value.
+
+### environment-parameter (ep)
+
+Typed configuration values an environment holds, arranged in a tree of `FOLDER` parameters that is one level deep: only a `FOLDER` can be a parent, and a `FOLDER` cannot be given one. Types: `TEXT`, `PASSWORD`, `NUMBER`, `BOOLEAN`, `DATE`, `MULTILINE_TEXT`, `SINGLE_CHOICE`, `MULTIPLE_CHOICES`, `LIST`, `MAP`, `FOLDER`. There is no `get`; `list` is the only read. The type of a parameter cannot be changed. A parameter's default value is what it starts with in a new environment and in a copy of the workspace, both seeded from the default environment alone; the value itself is not carried over to either, and a default value is not read at runtime.
+
+### event-listener (el)
+
+An event listener runs a script in response to an external event: an app's event type is bound to a script, optionally through a connector and an event queue. Its URL path, connector and enabled state are environment-specific configuration; the event type, the script, the queue and its grouping are shared by every environment and captured by a release.
+
+### event-listener-test-payload (tp)
+
+A test payload is a sample event that a manual trigger of an event listener runs. The payloads are the same in every environment; which one is the default is user-specific and environment-specific configuration. Every verb takes `--event-listener-id <eventListenerId>` beside the scope flags.
+
+### event-queue (eq)
+
+An event queue holds an event listener's incoming events and hands them to the script one at a time. A queue belongs to the whole workspace; only its enabled state is environment-specific configuration. Queues are gated per team: where a team cannot use them every verb here is refused, and `team get` reports `features.eventQueues`.
+
+### feedback
+
+Feedback to the ScriptRunner Connect team. Both verbs are refused when the agentic-feedback switch is off and nobody can be asked. Nothing reads feedback back; the returned ID is the only handle.
+
+### local-workspace (lw)
+
+A workspace as a directory on disk. See [Work from a local copy](#work-from-a-local-copy) for what a clone is for.
+
+### log
+
+Audit logs and invocation logs are team-scoped, and so is an invocation's payload: `log get-invocation-payload` takes `--team` and no `-w`, its route being a team one. Console logs, HTTP logs and large messages belong to a single invocation and need its workspace; `--team` there only narrows the interactive browse list. The workspace resolves through the ordinary chain, so a `SR_CONNECT_CLI_WORKSPACE`, a clone's `workspace.json` or a session default supplies it. An invocation belongs to one workspace, so where the value was inherited rather than passed with `-w`, a not-found answer carries a `⚠` naming where it came from. Every verb here offers, on a terminal, to copy its output to a file before printing. Nothing here writes anything.
+
+### package
+
+The NPM packages a workspace depends on. Workspace-scoped, no environment anywhere: a non-HEAD environment keeps the dependencies its release captured. The version is the only writable field; changing a name or type means removing and adding. A change here recompiles nothing until a script is next saved, and a note says so.
+
+When a package is not written in TypeScript, add its companion `@types/<name>` package as well, where one exists, so the compiler has types for it.
+
+### readme
+
+A workspace has one README, shared by every environment and addressed through the scope.
+
+### release
+
+An immutable snapshot of a workspace, optionally deployed into environments. Releases cannot be edited or deleted; which release an environment runs is `environment target-release`.
+
+### scheduled-trigger (st)
+
+Runs a script on a schedule. The schedule and the enabled state are environment-specific configuration and can be changed in a non-HEAD environment too; the script belongs to the trigger and is shared by every environment.
+
+### script
+
+A script is one TypeScript file in a workspace, read through an environment. In a non-HEAD environment `list` and `get` answer what the release captured. Saving a script compiles and bundles the whole workspace, so an import that cannot be resolved fails the save, while TypeScript diagnostics are reported and do not block it. Changing the content of several scripts at once is what [local-workspace push](#local-workspace-push) is for; renames and deletions are clearer through `script update --name` and `script delete`, which name the script by ID.
+
+### temp-remote-workspace (trw)
+
+A temporary copy of a workspace's current setup in a private SFTP space, reachable only with the returned credentials, for editing with any tool that speaks SFTP. The workspace is untouched until the copy is deleted.
+
+Two switches gate it, and they fail differently. The **team's** is `features.remoteWorkspace` on `team get`; false there answers 403 with a hint naming the field. The **workspace's** own is `remoteWorkspaceEnabled` on `workspace get`; false there answers exit 1 `BAD_REQUEST` with `SFTP server is not enabled for the workspace: <id>.` and a hint. **Nothing in this API turns the workspace switch on** — not `workspace create`, not `workspace update` — so a workspace the web application has not enabled it for cannot use either verb here. Check both before you plan around them.
+
+### workspace
+
+The unit everything else lives in. Team-scoped; the workspace is the resource, so `get`, `update` and `delete` take it as a positional argument and there is no `-w` here.
+
+### workspace-lock (wl)
+
+The editing lock the CLI takes on its own before every write; see [Workspace locks](#workspace-locks). These verbs are for looking at it, holding it across commands that cannot keep shell state, and giving it back early. A lock is not a permission: a write presenting none is applied, whoever holds the lock. What the lock protects against is a _second session claiming to be the holder_ — which is what every write the CLI makes does, and why one gets `WORKSPACE_LOCKED` while the same write under `--no-lock` goes through.
+
+## How commands work
+
+The rules below hold everywhere, so no verb repeats them.
+
+- **Scope flags** are `-w, --workspace <workspaceId>`, `-e, --env <environmentId>` and `--team <teamId>`. Each can come from a flag, its `SR_CONNECT_CLI_`* variable, a clone's `workspace.json`, the session record or a picker, in that order. The `session default` token covers the clone too: a flag that reads the session record reads `workspace.json` under the same conditions, and a flag without the token (`release create -e`, a deploy target) reads neither. That includes filters: `log list-invocation-logs -w` run inside a clone is narrowed to that workspace, with a stderr note. Non-interactively, a missing required one is exit 2. Destructive verbs, the ones that take `--yes`, read the session record and a clone's `workspace.json` only when a human is there to see the question naming them; their flags say `session default on a TTY only`, and a scripted delete has to name its scope with flags or environment variables. Every workspace-scoped verb accepts `--team`, including the ones where it only narrows the list a workspace is chosen from.
+- **Positional arguments** such as `<scriptId>` are picked interactively when omitted; non-interactively they are required. **The resource a verb acts on is its positional argument, and any other resource it needs is a flag** — `script get <scriptId>`, but `event-listener create --script-id <scriptId>`. `--explain` on the verb prints both, under `Arguments:` and `Scope flags:`. A positional argument that _is_ its group's scope resource reads the scope sources the matching flag would, and its description says so: `team get <teamId>`, `workspace get|update|delete <workspaceId>` and `environment get|update|delete <environmentId>` each take a session default and an `SR_CONNECT_CLI_`* variable. Every other positional argument takes neither, `environment target-release <releaseId>` included, the positional there being a release rather than the environment. Where the group's resource is also a scope flag, the three `environment` verbs accept both and the positional wins; `-e` there is marked `ignored when the positional argument is given`.
+- `--input <file>` reads the whole request body as JSON from a file, or `-` for stdin, and supersedes every body flag. Local validation still applies to what it carries.
+- **An update needs something to change.** Interactively, answers that keep every value send nothing and say so. Non-interactively, an update with no body flag and no `--input` is exit 2, and so is an `--input` body with no keys.
+- `--explain` prints what the verb takes and sends nothing: the example `--input` body on stdout where there is one and `{}` where there is not, and on stderr a sentence per parameter under `Rules:` plus whatever the parameters do not cover under `Notes:`. It exits 0 without credentials, scope or a request, and every body flag, scope flag and positional is ignored, along with the scope environment variables, the session record and a clone's `workspace.json`. Two globals still apply: `--raw` picks the shape, and `--copy-output-to-file` mirrors the document the way it mirrors any other. An option the verb does not have is still a parse error, not an ignored flag. The body shows every key the verb accepts, keys that exclude each other included, so where a rule names such a pair drop one before sending; `--explain --raw > body.json`, edited, is then a file the verb accepts back through `--input`.
+- `--yes` skips the confirmation a destructive verb asks for on a terminal; without a terminal it is required. Declining is exit 130.
+- `--file <path>` accepts `-` for stdin wherever it appears.
+- **HEAD and non-HEAD environments.** An environment either runs the workspace's current state (HEAD) or a release (non-HEAD). A non-HEAD environment is a snapshot: reads there answer from it, and writes to fields the release owns are refused. Interactive runs check first and ask only about what can change; flag-driven runs are refused by the API with a message naming the field.
+- **A local copy** of the workspace is kept current after the writes listed in [Local sync](#local-sync).
+
+## Commands
+
+One line per verb. What a verb takes — every parameter, its format, when it is refused — is `--explain` on the verb itself, which prints it without credentials, scope or a request:
+
+```sh
+npx @sr-connect/cli event-listener update --explain
+```
+
+<!-- commands:start -->
+
+### api-connection (ac)
+
+- `api-connection create` — Create an API connection in a workspace
+- `api-connection list` — List API connections in a workspace
+- `api-connection get` — Get a single API connection as the environment sees it
+- `api-connection update` — Update an API connection
+- `api-connection delete` — Delete an API connection from a workspace
+
+### app
+
+- `app list` — List apps with their connection types, API connection types, event listener types, event types and packages
+- `app get` — Get a single app with every ID the other groups take
+
+### auth
+
+- `auth login` — Verify and store API credentials in the OS keychain
+- `auth status` — Show credential source, instance, and verify against the API
+- `auth logout` — Remove stored credentials and every shell session's remembered scope
+
+### cli
+
+- `cli get-readme` — Print the CLI's own README
+- `cli settings` — View or change the CLI's own switches
+- `cli set-session` — Remember team/workspace/environment as defaults for this shell session
+- `cli clear-session` — Forget the session defaults for this shell session
+- `cli list-api-logs` — List the API calls this CLI recorded
+- `cli clear-api-logs` — Delete recorded API calls
+- `cli list-crash-reports` — List the crash reports this CLI stored
+- `cli get-crash-report` — Read one stored crash report
+- `cli clear-crash-reports` — Delete stored crash reports
+
+### connector (con)
+
+- `connector list` — List connectors
+- `connector get` — Get a single connector
+- `connector create` — Create a connector
+- `connector update` — Rename a connector, or replace a Generic connector's configuration
+- `connector delete` — Delete a connector
+
+### connector-sharing (cs)
+
+- `connector-sharing list` — List everyone a connector is shared with
+- `connector-sharing get` — Get a single user's permissions on a connector
+- `connector-sharing list-assignable-users` — List the users a connector can still be shared with
+- `connector-sharing set` — Share a connector with a user, or change what they may do with it
+- `connector-sharing remove` — Remove a user's access to a connector
+
+### environment (env)
+
+- `environment list` — List environments in a workspace
+- `environment create` — Create an environment in a workspace
+- `environment get` — Get a single environment of a workspace
+- `environment update` — Rename an environment
+- `environment delete` — Delete an environment from the workspace
+- `environment target-release` — Change which release an environment runs, or move it back to HEAD
+
+### environment-parameter (ep)
+
+- `environment-parameter list` — List parameters in a workspace environment
+- `environment-parameter create` — Create an environment parameter
+- `environment-parameter update` — Update an environment parameter
+- `environment-parameter delete` — Delete an environment parameter
+
+### event-listener (el)
+
+- `event-listener list` — List event listeners in a workspace
+- `event-listener get` — Get a single event listener as the environment sees it
+- `event-listener create` — Create an event listener in a workspace
+- `event-listener update` — Update an event listener
+- `event-listener delete` — Delete an event listener from a workspace
+
+### event-listener-test-payload (tp)
+
+- `event-listener-test-payload list` — List an event listener's test payloads
+- `event-listener-test-payload get` — Get a single test payload with its content
+- `event-listener-test-payload create` — Create a test payload for an event listener
+- `event-listener-test-payload update` — Replace a test payload's content and/or rename it
+- `event-listener-test-payload set-default` — Make a test payload the one a manual trigger runs
+- `event-listener-test-payload delete` — Delete a test payload
+
+### event-queue (eq)
+
+- `event-queue list` — List event queues in a workspace
+- `event-queue get` — Get a single event queue
+- `event-queue create` — Create an event queue in a workspace
+- `event-queue update` — Update an event queue
+- `event-queue delete` — Delete an event queue from a workspace
+
+### feedback
+
+- `feedback post` — Post feedback, optionally with files attached
+- `feedback post-crash-report` — Post a crash report this CLI stored earlier
+
+### local-workspace (lw)
+
+- `local-workspace clone` — Clone the workspace into a local directory
+- `local-workspace push` — Push local scripts, a README and test payloads back to the workspace
+
+### log
+
+- `log list-audit-logs` — List audit logs (paginated)
+- `log list-invocation-logs` — List script invocation logs (paginated, filterable)
+- `log get-invocation-payload` — Fetch the payload (the incoming event) of a script invocation
+- `log list-console-logs` — List the console output (console.log/warn/error) of a script invocation
+- `log list-http-logs` — List the HTTP calls a script invocation made
+- `log get-large-log-message` — Fetch a single console log too large to be stored with the rest
+
+### package
+
+- `package list` — List the packages a workspace depends on
+- `package get` — Get a single package of a workspace
+- `package add` — Add an NPM package to a workspace
+- `package update` — Change the version of a package on a workspace
+- `package remove` — Remove a package from a workspace
+- `package list-npm-versions` — List the versions the NPM registry publishes for a package
+
+### readme
+
+- `readme get` — Get the workspace's README
+- `readme update` — Update the workspace's README
+
+### release
+
+- `release list` — List releases of a workspace
+- `release create` — Create a workspace release and optionally deploy it
+
+### scheduled-trigger (st)
+
+- `scheduled-trigger create` — Create a scheduled trigger in a workspace
+- `scheduled-trigger list` — List scheduled triggers in a workspace
+- `scheduled-trigger get` — Get a single scheduled trigger as the environment sees it
+- `scheduled-trigger update` — Update a scheduled trigger
+- `scheduled-trigger delete` — Delete a scheduled trigger from a workspace
+
+### script
+
+- `script create` — Create a script in a workspace
+- `script update` — Update a script
+- `script list` — List scripts in a workspace
+- `script get` — Get a single script as the environment sees it
+- `script delete` — Delete a script from a workspace
+- `script trigger` — Run a script in a workspace
+- `script replay-invocation` — Replay a past invocation through its own script, optionally with another payload
+- `script abort-invocation` — Request that a queued or running invocation be aborted
+
+### team
+
+- `team list` — List teams
+- `team get` — Get a single team
+
+### temp-remote-workspace (trw)
+
+- `temp-remote-workspace create` — Open a temporary remote workspace and retrieve its SFTP credentials
+- `temp-remote-workspace delete` — Dispose a temporary remote workspace, optionally releasing and deploying its work
+
+### template
+
+- `template list` — List published templates, most frequently used first
+
+### workspace
+
+- `workspace list` — List workspaces
+- `workspace create` — Create a workspace, optionally from another workspace or a published template
+- `workspace get` — Get a single workspace
+- `workspace update` — Update a workspace
+- `workspace delete` — Delete a workspace
+
+### workspace-lock (wl)
+
+- `workspace-lock check` — Check who holds the workspace lock (exit 4 when nobody does)
+- `workspace-lock take` — Take the workspace lock, or renew one this shell already holds; kept for the rest of the shell session
+- `workspace-lock release` — Release the workspace lock, rather than waiting for the lease to lapse
+
+<!-- commands:end -->