@seclai/cli 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+## [1.5.0] - 2026-07-31
+
+### Changed
+
+- Require `--step-type` on `agents ai history`. The API marks the parameter required and the command had no way to supply it, so every call answered 422 — the command could not succeed before and the requirement breaks nothing. `--step-id`, `--limit` and `--offset` are now accepted as well
+- Deprecate `agents runs delete`. It never deleted anything — the endpoint it calls is the cancel endpoint, and the API has no delete-a-run operation — so it now warns on stderr and cancels. stdout stays `{"ok": true}`; use `agents runs cancel`, which prints the cancelled run
+- Warn on an empty `--api-version` and ignore it as before. Unlike the four above it costs only the version header, so it keeps working; a future release will reject it
+- Warn on a `--severity` passed to `alerts list` and stop sending it. `GET /alerts` declares no such filter, so it never filtered, and sending it becomes a 422 once `--api-version` is `2026-07-27` or later. The flag still parses and a future release will remove it
+- Reject a non-numeric `--page`, `--limit` or `--offset` at parse time instead of sending `NaN` and reporting the server's 422
+- Require `@seclai/sdk` 1.5.0
+
+### Added
+
+- Add an `--api-version <date>` global option, sent as the `Seclai-Version` header, opting into dated API changes released on or before that date. Omitted by default, so upgrading the CLI alone never changes a command's output. `SECLAI_API_VERSION` sets it for a shell, and `--allow-unknown-api-version` permits a date this release was not built against
+- Add `api-version get`, `api-version set <date>` and `api-version clear` to read the version a request resolves to and to pin or clear the account's version. `set` rejects anything that is not a `YYYY-MM-DD` date, since the pin applies to every client on the account and nothing re-checks it afterwards
+- Add the `email` command group covering agent email: `domains` (list, add, remove, verify, set-primary, use-shared, test-email, dmarc), `blocked` (list, add, remove, auto-block-mode), `inbound` (status, rejections, cancel-queued, resume) and `optouts` (list, remove)
+- Add `agents disable` and `agents enable` to pause and resume an agent across every trigger path, and `agents callers` to list the live agents that call it via a `call_agent` step
+- Add `agents triggers email-config` to set the alias, sender allowlist and inbound-handling flags on an `EMAIL_RECEIVED` trigger
+- Add `me`, reporting the authenticated user's account ID and organization memberships
+- Add `docs search` for keyword or semantic search over the Seclai documentation. `--mode` accepts `keyword` or `semantic` and rejects anything else at parse time
+- Add `models tiers`, mapping each media-generation modality and tier to its model and cost
+- Add `--supports-input-media` and `--supports-output-media` filters to `models list`
+- Add `--paged` to `evals criteria list`, wrapping the results in `{data: [...]}` instead of a bare array so `.data` reads the same whatever `--api-version` is in effect. The `pagination` block appears only once the API sends one, from `2026-07-27`
+
+### Fixed
+
+- Reject an empty `--api-key`, `--profile`, `--account-id` or `--config-dir` instead of acting as an identity the caller never named. A shell expanding an unset variable passes `""`, which the SDK's credential chain discards, so each silently resolved elsewhere: `--api-key` to `SECLAI_API_KEY` and then a cached SSO session, `--config-dir` to another account's cached tokens, `--account-id` to the default org, `--profile` to the built-in SSO defaults. The command then exited 0, having read or written somewhere other than where it was pointed. Guard the flag rather than the value — `seclai ${KEY:+--api-key "$KEY"} …`
+- Ship current skill content from `skills install`. The files it writes are string constants compiled into the CLI, regenerated by a script that nothing ran, so since March it had been installing a skill that documented a since-removed flag and none of the commands added after 1.1.0
+- Split the installed skill into a short index plus per-domain references, so an agent loads a command map rather than every command. `skills install` now writes 12 files instead of 4, and the set is discovered from disk rather than hard-coded
+- Complete the `auth` and `configure` groups and their subcommands, and `models list` / `models get`, in bash, zsh and fish. All were reachable but absent from the generated completion scripts — including `configure sso`, the first command a new user runs
+- Offer `--profile`, `--account-id` and `--config-dir` in the zsh and fish completions. They have been accepted as global options since 1.2.0 but were never suggested
+
+## [1.4.0] - 2026-06-05
+
+### Added
+
+- Add `agents attachment-references` to read an agent's static attachment-reference contract before staging uploads ([#9](https://github.com/seclai/seclai-cli/pull/9))
+- Add `agents runs download-attachment` for a file emitted by a run step, writing to `--output` or streaming raw bytes to stdout ([#9](https://github.com/seclai/seclai-cli/pull/9))
+- Add `models experiments delete` to soft-delete a model playground experiment ([#9](https://github.com/seclai/seclai-cli/pull/9))
+
+## [1.3.0] - 2026-05-22
+
+### Added
+
+- Add `agents preview-import` to validate an agent definition without creating anything, reporting step, schedule, alert, criteria and policy counts plus any unresolved entity refs ([#8](https://github.com/seclai/seclai-cli/pull/8))
+
+## [1.2.2] - 2026-04-24
+
+### Added
+
+- Add `models list` and `models get` for the model catalog ([#7](https://github.com/seclai/seclai-cli/pull/7))
+- Add model playground commands `models experiments list`, `create`, `get` and `cancel` ([#7](https://github.com/seclai/seclai-cli/pull/7))
+
+## [1.2.1] - 2026-04-02
+
+### Added
+
+- Add `agents export`, returning a portable JSON snapshot of an agent definition ([#6](https://github.com/seclai/seclai-cli/pull/6))
+
+## [1.2.0] - 2026-03-27
+
+### Added
+
+- Add `auth login`, `logout`, `status` and `refresh` for browser-based OAuth2/PKCE SSO, with tokens cached locally and refreshed automatically. `login` takes `--no-browser` and `--port` ([#5](https://github.com/seclai/seclai-cli/pull/5))
+- Add `configure sso` and `configure list` to create and inspect `~/.seclai/config` profiles ([#5](https://github.com/seclai/seclai-cli/pull/5))
+- Add `--profile` and `--config-dir` global options, selecting the SSO profile and config directory ([#5](https://github.com/seclai/seclai-cli/pull/5))
+
+## [1.1.1] - 2026-03-24
+
+### Added
+
+- Add `mcp configure` to write Seclai MCP server config into AI coding tool config files, and `mcp show` to print the snippet for manual setup ([#4](https://github.com/seclai/seclai-cli/pull/4))
+
+## [1.1.0] - 2026-03-24
+
+### Added
+
+- Expand coverage from agents, sources and contents to knowledge bases, memory banks, source exports, embedding migrations, solutions, governance, evaluations, alerts, model alerts and the AI assistants ([#3](https://github.com/seclai/seclai-cli/pull/3))
+- Add `agents run --events` to stream every SSE event as newline-delimited JSON, with `--event-filter` and `--output full|data|status`, and `--poll` to submit and poll until completion ([#3](https://github.com/seclai/seclai-cli/pull/3))
+- Add `search` across all resource types in an account ([#3](https://github.com/seclai/seclai-cli/pull/3))
+- Add `skills install` to install Seclai CLI skill files into AI coding tool directories ([#3](https://github.com/seclai/seclai-cli/pull/3))
+- Add `completion bash|zsh|fish` to generate shell completion scripts ([#3](https://github.com/seclai/seclai-cli/pull/3))
+
+## [1.0.6] - 2026-01-30
+
+### Added
+
+- Add `contents upload` to replace existing content with a file upload, taking `--title` and `--mime-type`
+- Add `--metadata` and `--metadata-file` to the upload commands
+
+### Removed
+
+- **Breaking:** Remove the `<agentId>` argument from the run-scoped commands. The API stopped requiring it in 1.0.4, where it was retained and ignored; pass the run ID alone
+
+## [1.0.5] - 2026-01-30
+
+_Documentation only. Every command and option gained help text; there are no functional changes._
+
+## [1.0.4] - 2026-01-27
+
+### Added
+
+- Accept a run ID alone in `agents runs get` and `agents runs cancel`. The agent ID argument is still accepted, and is removed in 1.0.6
+
+## [1.0.3] - 2026-01-20
+
+### Added
+
+- Accept `source` as an alias for the `sources` command
+
+### Fixed
+
+- Send requests to `https://api.seclai.com` by default rather than relying on the SDK's default, and honour `SECLAI_API_URL` when set
+- Resolve the entrypoint through symlinks, so a globally installed `seclai` runs instead of exiting silently
+- Report SDK errors with status, URL and response body instead of a bare message
+
+## [1.0.2] - 2026-01-13
+
+### Changed
+
+- Require `@seclai/sdk` 1.0.3
+
+## [1.0.1] - 2026-01-13
+
+### Added
+
+- Add `agents run --stream` to wait for a streaming run to complete and print the final result
+
+## [1.0.0] - 2026-01-12
+
+_Stable release. No functional changes since 0.0.2._
+
+## [0.0.2] - 2026-01-12
+
+### Fixed
+
+- Report the published version in the generated documentation instead of `0.0.0`
+
+## [0.0.1] - 2026-01-12
+
+_Initial release._
+
+[1.5.0]: https://github.com/seclai/seclai-cli/releases/tag/1.5.0
+[1.4.0]: https://github.com/seclai/seclai-cli/releases/tag/1.4.0
+[1.3.0]: https://github.com/seclai/seclai-cli/releases/tag/1.3.0
+[1.2.2]: https://github.com/seclai/seclai-cli/releases/tag/1.2.2
+[1.2.1]: https://github.com/seclai/seclai-cli/releases/tag/1.2.1
+[1.2.0]: https://github.com/seclai/seclai-cli/releases/tag/1.2.0
+[1.1.1]: https://github.com/seclai/seclai-cli/releases/tag/1.1.1
+[1.1.0]: https://github.com/seclai/seclai-cli/releases/tag/1.1.0
+[1.0.6]: https://github.com/seclai/seclai-cli/releases/tag/1.0.6
+[1.0.5]: https://github.com/seclai/seclai-cli/releases/tag/1.0.5
+[1.0.4]: https://github.com/seclai/seclai-cli/releases/tag/1.0.4
+[1.0.3]: https://github.com/seclai/seclai-cli/releases/tag/1.0.3
+[1.0.2]: https://github.com/seclai/seclai-cli/releases/tag/1.0.2
+[1.0.1]: https://github.com/seclai/seclai-cli/releases/tag/1.0.1
+[1.0.0]: https://github.com/seclai/seclai-cli/releases/tag/1.0.0
+[0.0.2]: https://github.com/seclai/seclai-cli/releases/tag/0.0.2
+[0.0.1]: https://github.com/seclai/seclai-cli/releases/tag/0.0.1

package/README.md

@@ -42,7 +42,7 @@ npx add-mcp https://api.seclai.com/mcp --header "X-API-Key: $SECLAI_API_KEY" --n
 
 ## Documentation
 
-Command reference (latest): https://seclai.github.io/seclai-cli/1.4.0/
+Command reference (latest): https://seclai.github.io/seclai-cli/1.5.0/
 
 ## Authentication
 
@@ -86,6 +86,16 @@ or set environment variables:
 | `SECLAI_SSO_CLIENT_ID` | Cognito app client ID | `4bgf8v9qmc5puivbaqon9n5lmr` |
 | `SECLAI_SSO_REGION` | AWS region | `us-west-2` |
 
+Set profiles up interactively, and list the ones you have:
+
+```bash
+# Prompts for domain, client ID, region, and account ID
+seclai configure sso [--profile-name <name>]
+
+# Show every configured profile
+seclai configure list
+```
+
 Use a named profile with `--profile`:
 
 ```bash
@@ -102,6 +112,7 @@ Tokens are cached in `~/.seclai/sso/cache/` and auto-refreshed when expired.
 | `SECLAI_API_URL` | Override API base URL (default: `https://api.seclai.com`) |
 | `SECLAI_PROFILE` | Default SSO profile name (default: `default`) |
 | `SECLAI_CONFIG_DIR` | Config directory path (default: `~/.seclai`) |
+| `SECLAI_API_VERSION` | Dated API version (alternative to `--api-version`) |
 | `SECLAI_SSO_DOMAIN` | Override SSO domain (default: `auth.seclai.com`) |
 | `SECLAI_SSO_CLIENT_ID` | Override SSO client ID (default: `4bgf8v9qmc5puivbaqon9n5lmr`) |
 | `SECLAI_SSO_REGION` | Override SSO region (default: `us-west-2`) |
@@ -114,11 +125,54 @@ Tokens are cached in `~/.seclai/sso/cache/` and auto-refreshed when expired.
 | `--profile <name>` | SSO profile name |
 | `--account-id <id>` | Account ID (`X-Account-Id` header) |
 | `--config-dir <path>` | Config directory path |
+| `--api-version <date>` | Opt into dated API changes released on or before this `YYYY-MM-DD` |
+| `--allow-unknown-api-version` | Send an `--api-version` this CLI was not built against |
 | `--compact` | Output compact (single-line) JSON |
 | `-V, --version` | Print version |
 
 ---
 
+## API Versions
+
+The API is versioned by date. Responses can change shape between versions — a
+bare array becoming a `{data, pagination}` envelope, for instance — so the CLI
+sends **no version header by default**. Upgrading the CLI on its own never
+changes what a command prints.
+
+```bash
+# See which version a request resolves to
+seclai api-version get
+
+# Opt one invocation into the changes released up to a date
+seclai --api-version 2026-07-27 alerts list
+
+# Or for every client on the account, not just this CLI
+seclai api-version set 2026-07-27
+seclai api-version clear    # revert to the default
+```
+
+An `--api-version` this CLI was not built against is rejected, because a newer
+version can reshape a response the CLI would then misread. Pass
+`--allow-unknown-api-version` to send it anyway. `api-version set` takes a
+`YYYY-MM-DD` date and rejects anything else, because the pin applies to every
+client on the account and nothing re-checks it afterwards.
+
+`--api-key`, `--profile`, `--account-id` and `--config-dir` reject an empty
+value. A shell expanding an unset variable passes `""`, which the SDK discards,
+so `--api-key "$KEY"` with `KEY` unset would fall back to `SECLAI_API_KEY` or a
+cached SSO session and run as a different identity — and `--account-id ""` would
+act on the default org rather than the one you named. Guard the flag instead of
+the value:
+
+```bash
+seclai ${KEY:+--api-key "$KEY"} agents list
+```
+
+An empty `--api-version` is still accepted, with a warning: it costs only the
+version header. A future release will reject that too.
+
+---
+
 ## Commands
 
 ### Agents
@@ -129,6 +183,20 @@ seclai agents create --json '{"name":"My Agent"}'
 seclai agents get <agentId>
 seclai agents update <agentId> --json '{"name":"Renamed"}'
 seclai agents delete <agentId>
+
+# Pause an agent across every trigger path, then resume it
+seclai agents disable <agentId>
+seclai agents enable <agentId>
+
+# Which live agents call this one via a call_agent step?
+seclai agents callers <agentId>
+```
+
+#### Triggers
+
+```bash
+# Alias, sender allowlist, and inbound-handling flags for an EMAIL_RECEIVED trigger
+seclai agents triggers email-config <agentId> <triggerId> --json '{"alias":"support"}'
 ```
 
 #### Running Agents
@@ -158,8 +226,8 @@ seclai agents run <agentId> --json '{"input":"Hi"}' --poll --poll-interval-ms 20
 ```bash
 seclai agents runs list <agentId> [--page N] [--limit N]
 seclai agents runs get <runId> [--include-step-outputs]
-seclai agents runs delete <runId>
 seclai agents runs cancel <runId>
+seclai agents runs delete <runId>   # deprecated alias for `runs cancel`
 seclai agents runs search [--page N] [--limit N] [--json '...']
 seclai agents runs eval-results <agentId> <runId> [--page N] [--limit N]
 # Download a file attachment emitted by a run step. attachmentId is the
@@ -204,7 +272,8 @@ seclai agents input-status <agentId> <uploadId>
 ```bash
 seclai agents ai gen-steps <agentId> --user-input "Build a QA chatbot"
 seclai agents ai step-config <agentId> --user-input "Configure the search step"
-seclai agents ai history <agentId>
+# --step-type is required: the API rejects the request without it.
+seclai agents ai history <agentId> --step-type llm [--step-id <id>] [--limit N] [--offset N]
 seclai agents ai mark <agentId> <conversationId> --json '{"accepted":true}'
 ```
 
@@ -303,7 +372,7 @@ seclai memory ai accept <conversationId> --json '{"accepted":true}'
 #### Criteria
 
 ```bash
-seclai evals criteria list <agentId> [--page N] [--limit N]
+seclai evals criteria list <agentId> [--page N] [--limit N] [--paged]
 seclai evals criteria create <agentId> --json '{"name":"Quality"}'
 seclai evals criteria get <criteriaId>
 seclai evals criteria update <criteriaId> --json '{"name":"Renamed"}'
@@ -311,6 +380,12 @@ seclai evals criteria delete <criteriaId>
 seclai evals criteria summary <criteriaId>
 ```
 
+`--paged` wraps the results in `{"data": [...]}` instead of returning a bare
+array, so `.data` is a stable path to read whatever `--api-version` is in
+effect. Nothing is invented: the `pagination` block appears only once the API
+sends one, from `--api-version 2026-07-27`. Migrate scripts to `.data` first,
+then opt in to get `.pagination`.
+
 #### Results
 
 ```bash
@@ -375,7 +450,7 @@ seclai governance ai decline <conversationId>
 ### Alerts
 
 ```bash
-seclai alerts list [--page N] [--limit N] [--status open] [--severity high]
+seclai alerts list [--page N] [--limit N] [--status open]
 seclai alerts get <alertId>
 seclai alerts status <alertId> --json '{"status":"resolved"}'
 seclai alerts comment <alertId> --json '{"comment":"Investigating"}'
@@ -383,6 +458,10 @@ seclai alerts subscribe <alertId>
 seclai alerts unsubscribe <alertId>
 ```
 
+`--severity` is accepted for compatibility but ignored with a warning, and will
+be removed. `GET /alerts` declares no severity filter, so it never filtered.
+Filter client-side: `seclai alerts list | jq '[.data[] | select(.severity == "high")]'`.
+
 #### Alert Configurations
 
 ```bash
@@ -402,6 +481,15 @@ seclai alerts prefs update <organizationId> <alertType> --json '{"enabled":true}
 
 ### Models
 
+```bash
+seclai models list [--provider <name>] [--supports-tool-use] [--supports-thinking]
+seclai models list --supports-input-media image --supports-output-media video
+seclai models get <modelId>
+
+# Each media-generation modality and tier, with its model and cost
+seclai models tiers
+```
+
 #### Model Alerts
 
 ```bash
@@ -431,6 +519,63 @@ seclai models experiments delete <experimentId>   # soft-delete, preserves audit
 
 ```bash
 seclai search --query "deployment guide" [--limit N] [--entity-type agent|source|kb]
+
+# Search the Seclai documentation
+seclai docs search --query "memory banks" [--mode keyword|semantic] [--limit N]
+```
+
+### Account
+
+```bash
+# The authenticated user's account ID and organization memberships
+seclai me
+```
+
+### Email
+
+Agent email: the domains agents send from, the inbound blocklist, inbound
+health, and recipient opt-outs.
+
+#### Domains
+
+```bash
+seclai email domains list
+seclai email domains add --kind custom --value mail.example.com [--delegated]
+seclai email domains verify <domainId>        # check DNS now
+seclai email domains set-primary <domainId>
+seclai email domains test-email <domainId>    # send a test to the account owner
+seclai email domains dmarc <domainId> [--days N] [--top-sources N]
+seclai email domains remove <domainId>
+seclai email domains use-shared               # revert to agent.seclai.com
+```
+
+`add` returns the DNS records to publish. Use `--delegated` when the domain's
+DNS is delegated to Seclai, so those records are published for you.
+
+#### Blocked Senders
+
+```bash
+seclai email blocked list [--limit N] [--offset N]
+seclai email blocked add --sender-email spam@example.com [--note "phishing"]
+seclai email blocked add --sender-email example.com --match-type domain
+seclai email blocked remove <blockedId>
+seclai email blocked auto-block-mode disabled|input|input_and_output
+```
+
+#### Inbound Health
+
+```bash
+seclai email inbound status                   # quota, pause state, queued runs
+seclai email inbound rejections [--agent-id <id>] [--limit N]
+seclai email inbound cancel-queued            # fail all over-quota parked runs
+seclai email inbound resume                   # lift the account-wide pause
+```
+
+#### Opt-outs
+
+```bash
+seclai email optouts list [--agent-id <id>] [--limit N] [--offset N]
+seclai email optouts remove <optoutId>
 ```
 
 ### AI Assistant