@getantidote/cli 0.0.0-stage → 0.1.1-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duku AI Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,349 @@
-# Temporary Holding Version
+# antidote
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Antidote command-line interface. It signs in to the Antidote platform and runs the
+platform's tools; every tool runs server-side.
+
+## Install
+
+Requires Node.js 22.4 or later.
+
+```bash
+npm i -g @getantidote/cli
+```
+
+## Sign in
+
+```bash
+antidote login            # opens your browser
+antidote login --device   # prints a link and a code to approve on any other device
+```
+
+`antidote login` uses `--device` automatically over SSH, or on Linux/Unix with no
+`DISPLAY` or `WAYLAND_DISPLAY`. Browser login listens for the redirect on the
+first free port of `127.0.0.1:48211`–`48215`. Logging in again replaces the
+previous session, which is revoked on the server first (if that fails, you get
+a warning and the login goes ahead); if the new sign-in then fails, you are
+signed out. When you approve a `--device` sign-in, the page shows where and
+when it was started: deny any you didn't start yourself.
+
+For CI, set an API key from the dashboard (Settings → API keys) instead of
+logging in:
+
+```bash
+ANTIDOTE_API_KEY=<key> antidote whoami
+```
+
+`ANTIDOTE_API_KEY` takes precedence over any stored login, and nothing is written to
+disk in this mode. `antidote login` refuses to run while it holds a key.
+
+### CI without a stored secret: service identities
+
+A service identity lets a CI job act for your organisation with no secret stored
+in the CI: the CLI exchanges the job's OIDC token for a short-lived Antidote token
+that acts as the identity. There are two ways to say which identity.
+
+**Naming it.** Set `ANTIDOTE_SERVICE_IDENTITY` to the id of a service identity from
+the dashboard (Settings → Service identities). One of the identity's trust rules
+must accept the job's token: its issuer, its audience and the rule's conditions.
+The dashboard shows a ready-made job for each CI platform. On GitHub Actions:
+
+```yaml
+jobs:
+  antidote:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # lets the CLI request the job's OIDC token
+    steps:
+      - run: antidote whoami # with the CLI installed
+        env:
+          ANTIDOTE_API_URL: https://platform.duku.ai
+          ANTIDOTE_SERVICE_IDENTITY: svc_…
+```
+
+**Letting the platform find it.** Set only the job's OIDC token
+(`ANTIDOTE_OIDC_TOKEN` or `ANTIDOTE_OIDC_TOKEN_FILE`), without `ANTIDOTE_SERVICE_IDENTITY`.
+The platform finds the identity from the token itself: the one that belongs to
+your organisation's connection to that CI platform (Settings → Integrations →
+Source control & CI/CD), so there is nothing to create or name. No CI
+platform's connection provides one yet; until one does, the platform refuses
+these tokens. The token's audience must be the platform's URL (the origin of
+`ANTIDOTE_API_URL`). When the platform refuses a token, the CLI prints its reason as
+it gave it.
+
+The CLI takes the job's OIDC token from the first of these that is set (a
+variable that is set but empty is an error):
+
+1. `ANTIDOTE_OIDC_TOKEN`, the token itself (GitLab's `id_tokens`, or the output of
+   `circleci run oidc get` or `buildkite-agent oidc request-token`);
+2. `ANTIDOTE_OIDC_TOKEN_FILE`, a file holding it;
+3. with `ANTIDOTE_SERVICE_IDENTITY` only, on GitHub Actions, a token the CLI
+   requests itself, for the audience `ANTIDOTE_OIDC_AUDIENCE` (by default the
+   origin of `ANTIDOTE_API_URL`, such as `https://platform.duku.ai`). The job needs
+   `permissions: id-token: write`. `ANTIDOTE_OIDC_AUDIENCE` has no effect on a
+   token from 1 or 2: its audience is set where it is issued.
+
+The Antidote token lives in memory only, and the CLI exchanges again shortly before
+it expires. Each exchange reads `ANTIDOTE_OIDC_TOKEN_FILE` again or requests a new
+token from GitHub, but sends `ANTIDOTE_OIDC_TOKEN` as it is. The platform refuses a
+CI token that has expired, and, naming an identity, one issued over an hour
+ago, so:
+
+- Naming an identity, exchange GitLab's `id_tokens` in the job's first hour:
+  GitLab issues them when the job starts. Without `ANTIDOTE_SERVICE_IDENTITY`, the
+  CLI leaves the token's age to the platform.
+- Buildkite's tokens last 5 minutes unless `--lifetime` says otherwise.
+- A job that outlives its CI token needs a fresh `ANTIDOTE_OIDC_TOKEN` for each
+  command, or `ANTIDOTE_OIDC_TOKEN_FILE`.
+
+Before sending a token from `ANTIDOTE_OIDC_TOKEN` or the file, the CLI checks it
+itself, because the platform's refusal doesn't say why: it must have an `exp`
+and an `iat`, must not have expired and, naming an identity, must have been
+issued in the last hour. If the platform's token endpoint answers HTTP 429
+`temporarily_unavailable` or 503 `server_error`, or GitHub's token service fails
+or can't be reached, the CLI tries the exchange twice more, waiting as long as
+the platform's `Retry-After` says (5 seconds without one, at most a minute).
+Other failures of the exchange are final, as are a failed discovery and a 503
+from `/mcp`. Nothing is written to disk in either mode.
+
+### Which credentials the CLI uses
+
+| Set | The CLI acts as |
+|---|---|
+| `ANTIDOTE_API_KEY` | the API key's identity |
+| `ANTIDOTE_SERVICE_IDENTITY`, with a CI token from `ANTIDOTE_OIDC_TOKEN`, `ANTIDOTE_OIDC_TOKEN_FILE` or GitHub Actions | that service identity |
+| `ANTIDOTE_OIDC_TOKEN` or `ANTIDOTE_OIDC_TOKEN_FILE`, without `ANTIDOTE_SERVICE_IDENTITY` | the service identity the platform finds for the token |
+| none of these | whoever ran `antidote login` |
+
+Any of these wins over a stored login. An empty `ANTIDOTE_API_KEY` is ignored, as
+if unset: the CLI uses the next row that applies. An `ANTIDOTE_API_KEY` that isn't
+empty can't be set together with `ANTIDOTE_SERVICE_IDENTITY`, `ANTIDOTE_OIDC_TOKEN` or
+`ANTIDOTE_OIDC_TOKEN_FILE` (the CLI exits with a usage error), and
+`ANTIDOTE_SERVICE_IDENTITY`, `ANTIDOTE_OIDC_TOKEN` or `ANTIDOTE_OIDC_TOKEN_FILE` set but
+empty is an error, never a reason to fall back to a stored login. `antidote login`
+refuses to run while any of them is in use.
+
+| Variable | Purpose |
+|---|---|
+| `ANTIDOTE_API_URL` | Platform URL, default `https://platform.duku.ai`. Must be https, except `http://localhost` / `127.0.0.1` / `[::1]` for a local stack. |
+| `ANTIDOTE_API_KEY` | An API key, used instead of any login. |
+| `ANTIDOTE_SERVICE_IDENTITY` | A service identity's id (`svc_…`), used instead of any login. |
+| `ANTIDOTE_OIDC_TOKEN` | The CI job's OIDC token: for `ANTIDOTE_SERVICE_IDENTITY`, or on its own to let the platform find the identity. |
+| `ANTIDOTE_OIDC_TOKEN_FILE` | A file holding the job's OIDC token, read again on every exchange. |
+| `ANTIDOTE_OIDC_AUDIENCE` | The audience the CLI requests from GitHub Actions for `ANTIDOTE_SERVICE_IDENTITY` (default: the origin of `ANTIDOTE_API_URL`). |
+| `XDG_CONFIG_HOME` | Parent of the config directory (default `~/.config`). |
+
+Each `ANTIDOTE_*` variable was `DUKU_*` before the CLI was renamed. The old name
+still works when the new one is unset; a set `ANTIDOTE_*` variable wins, even an
+empty one.
+
+## Commands
+
+```bash
+antidote whoami             # the signed-in user (or service identity), organisation and auth mode (a tool command, below)
+antidote tools              # the tools available to the CLI
+antidote tools --refresh    # re-fetch the tool list
+antidote logout             # revoke the session and delete this machine's credentials
+antidote --version
+```
+
+`antidote logout` removes the stored login only; if `ANTIDOTE_API_KEY`,
+`ANTIDOTE_SERVICE_IDENTITY`, `ANTIDOTE_OIDC_TOKEN` or `ANTIDOTE_OIDC_TOKEN_FILE` is set,
+commands keep using it. If the server can't revoke the session, logout warns and still
+deletes the local credentials. Add `--json` to any command for machine-readable output.
+
+## Tool commands
+
+Each tool the platform exposes to the CLI is a command, `antidote <tool>`, built from
+the tool's input schema. `antidote <tool> --help` lists its flags.
+
+- Each property becomes a kebab-case flag: `maxResults` or `max_results` becomes
+  `--max-results`.
+- Strings, numbers, integers, booleans and enums take plain values; object and
+  array properties take a JSON value: `--filters '{"status":"failed"}'`.
+- A boolean flag sends `true`; `--no-<flag>` sends `false`.
+- Give a negative number as `--limit=-5`.
+- A property named like a CLI flag (`json`, `help`, `version`, `device`,
+  `refresh`) becomes `--arg-<flag>` (e.g. `--arg-json`); a property whose flag
+  would clash with another property's, or is not typable, becomes
+  `--arg-<property>` with its raw name. A tool whose properties still lack
+  usable flags is not offered as a command.
+- Required properties are enforced; the server validates everything else.
+- Tool flags go after the tool name; only `--json` and `--help` may come before
+  it.
+- `--json` prints the tool's structured result as JSON.
+- A tool's snake_case name also works in kebab-case: `antidote record-preview` runs
+  `record_preview`.
+- An input you don't give as a flag is read from the environment variable named
+  `ANTIDOTE_INPUT_` plus the property in capitals (`release_label` is
+  `ANTIDOTE_INPUT_RELEASE_LABEL`). A flag wins over the variable, and an empty
+  variable counts as not set. Use it to keep a value out of a command line and
+  a job log. The prefix keeps every other
+  variable out of reach: the CLI's own variables in the table above and the
+  `ANTIDOTE_<KEY>` values an earlier job's dotenv file passes on are never read
+  as inputs. There is no `DUKU_INPUT_` name. Two
+  properties that map to the same variable (`foo_bar` and `fooBar`) are not read
+  from the environment; give them as flags.
+- `--dotenv <path>` writes the result's top-level strings, numbers and booleans
+  to that file as `ANTIDOTE_<KEY>=<value>` lines (`target_id` becomes
+  `ANTIDOTE_TARGET_ID`, `runStatus` becomes `ANTIDOTE_RUN_STATUS`); objects, arrays
+  and nulls are left out, and line breaks in a value become a space. A key that
+  would make a line starting `ANTIDOTE_INPUT_`, or one naming a variable in the
+  table above under either name (`ANTIDOTE_API_KEY`, `ANTIDOTE_OIDC_TOKEN`, ...),
+  is left out too, so a result can never set an input or the CLI's own variables
+  for a later job. The file is written to a temporary file in the same directory and
+  renamed over `<path>`, so a symbolic link at `<path>` is replaced, never
+  written through. It is emptied as soon as the command starts, so any failure
+  (a usage mistake, no login, a failed call) leaves no values from an earlier
+  run. The exception is a path written directly after another flag
+  (`--dry-run --dotenv antidote.env`), which could be that flag's value: it is
+  emptied once the tool's flags have been read, so write `--dotenv=antidote.env`
+  to have it emptied at the start. The result is printed first; if writing the
+  file then fails, the CLI says the tool succeeded and writing the file failed,
+  and exits 1.
+- Pass free text such as a title as `--title=...` or as `ANTIDOTE_INPUT_TITLE`. A
+  value that starts with `-` after a space (`--title "-x"`) is refused as
+  ambiguous, so a title such as `--dotenv=/path` can never be taken as a flag
+  and nothing is written.
+- `--json`, and the indented JSON printed for a result with nested values, write
+  bidi overrides, zero-width characters and control characters as `\uXXXX`
+  escapes, so the output stays valid JSON.
+- A call that takes longer than about a minute fails in deployed environments,
+  because the load balancer in front of the platform cuts it off. The server may
+  still have finished: the dotenv file is then empty, and running the command again
+  finds the same target by its build key but starts a second run.
+
+### In CI
+
+A job that needs a tool's result in a later job writes it as a dotenv file. In
+GitLab, with `ANTIDOTE_API_KEY` set as a masked CI/CD variable and the product's
+id given to the tool as `ANTIDOTE_INPUT_PRODUCT_ID`:
+
+```yaml
+antidote-preview:
+  stage: test
+  variables:
+    ANTIDOTE_INPUT_PRODUCT_ID: prod_123
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+  script:
+    - npx -y @getantidote/cli@0.1 record-preview --provider gitlab --host "$CI_SERVER_FQDN" --repository "$CI_PROJECT_PATH" --repository-id "$CI_PROJECT_ID" --number "$CI_MERGE_REQUEST_IID" --head-sha "$CI_COMMIT_SHA" --branch "$CI_COMMIT_REF_NAME" --pipeline-id "$CI_PIPELINE_ID" --dotenv antidote.env
+  artifacts:
+    when: always
+    reports:
+      dotenv: antidote.env
+```
+
+`CI_MERGE_REQUEST_IID` is empty on a branch pipeline, so the `rules` line keeps
+the job to merge request pipelines. `--host` takes `$CI_SERVER_FQDN`, not
+`$CI_SERVER_HOST`, because it keeps the port of a GitLab served on one. Jobs in a
+later stage, or jobs that `needs` this one, then receive the variables in the
+table below. Exit codes are 0 on success, 1 when the tool fails and 2 for a usage
+mistake.
+
+`record-preview`, and `record-release` when it is given build fields, refuse a
+signed-in user: a CI job uses `ANTIDOTE_API_KEY` or a CI sign-in
+(`ANTIDOTE_OIDC_TOKEN`). To record the build a pipeline
+deployed to a named environment, send the commit and the repository that make
+its build key (`gitlab:project=acme/web:env=staging:sha=<sha>`; the rule is in
+[the tools README](../../api/platform/src/modules/tools/README.md#build-keys)):
+
+```yaml
+antidote-release:
+  stage: verify
+  needs: [deploy-staging]
+  variables:
+    ANTIDOTE_INPUT_PRODUCT_ID: prod_123
+  script:
+    - npx -y @getantidote/cli@0.1 record-release --environment staging --build-sha "$CI_COMMIT_SHA" --provider gitlab --host "$CI_SERVER_FQDN" --repository "$CI_PROJECT_PATH" --repository-id "$CI_PROJECT_ID" --dotenv antidote.env
+  artifacts:
+    when: always
+    reports:
+      dotenv: antidote.env
+```
+
+On GitLab, `--repository-id` (the numeric `CI_PROJECT_ID`) is required. On
+GitHub, `--repository` is `owner/repo` and the host can only be `github.com`. A
+variable CI leaves unset arrives as an empty string: `--release-label ""` counts
+as no label, while an empty `--environment` or `--environment-id` is refused.
+
+`record-release` starts the exploration first and the product's tests second. If
+the tests then fail to start, the command still exits 0, because the exploration
+is running: `ANTIDOTE_TEST_RUN_STATUS` is `failed` and `--json` shows why in
+`warnings`. A job that must fail in that case checks the variable, for example
+`test "$ANTIDOTE_TEST_RUN_STATUS" != failed`.
+
+`record-release` records a build that an older pipeline deployed, then run again
+(a re-run of the `staging` job after `1.5.0` has gone out), and the product's
+tests run on it, but no exploration starts: an exploration tests what the
+environment serves now. `ANTIDOTE_RUN_STATUS` is `skipped`, `ANTIDOTE_RUN_ID` is empty,
+and `warnings` names both builds. `--test-paths-per-goal` is at most 10 and
+`--test-runs-per-path` at most 5; a larger value is lowered and `warnings` says
+so.
+
+`record-preview` refuses an environment that is persistent when the organisation
+has `version-axis`, because the environment name comes from the branch: a branch
+pipeline on `production` is told to use `record-release`. `--url` must be an
+`http` or `https` URL.
+
+A person can record a release by hand with the two label inputs instead,
+`antidote record-release --environment-id <id> --label 1.4.2`. The product's
+"Runs from API keys" limit applies to it, and to every other caller except the
+web app, including a script that calls the GraphQL `recordManualRelease`
+mutation with an API key: 10 runs in any 10 minutes, counting every run on that
+product that was started with an API key or an `antidote login` session. Duku staff
+can raise it in the product's settings. When it is reached the next call is
+refused ("Release run limit reached for this product (10 of 10 in the last 10
+minutes). Wait a few minutes and try again"). The exploration that a call with
+build fields starts is recorded as CI and does not count.
+
+A tool that starts a run returns `follow_up`, which names the batch to poll with
+`get_batch`. There is no `--wait`: a job that must wait for the result runs
+`antidote get-batch --batch-id "$ANTIDOTE_RUN_ID" --json` every `poll_seconds` (15)
+until `verdict.final` is `true`, and reads `verdict.outcome` (`passed`,
+`new_issues`, `unverified` or `timed_out`) from it; what each outcome means is
+in [AUTH_ARCHITECTURE.md](../../../docs/AUTH_ARCHITECTURE.md#6-mcp-remote-server-oauth-21-facade)
+under *Follow-up contract*. `get_batch` gives the same answer as the check Duku
+posts on the merge or pull request.
+
+When no run started, `ANTIDOTE_RUN_ID` is empty, so poll only when it is not empty
+and `ANTIDOTE_RUN_STATUS` is not `completed` (`record-preview` reports `completed`
+when Duku tests the change with an agentic test instead of an exploration, which
+has no batch to poll). On a product in agentic mode, Duku starts an agentic
+execution instead of an exploration: `ANTIDOTE_RUN_ID` is empty,
+`ANTIDOTE_RUN_STATUS` is `skipped` and `warnings` names the execution.
+`--json` shows the same thing directly: `follow_up` is null when there is
+nothing to poll.
+
+The variables each tool writes with `--dotenv`. A null value is left out of
+the file. `ANTIDOTE_COMMENT_ID` is always written empty (`ANTIDOTE_COMMENT_ID=`),
+`ANTIDOTE_PREVIEW_URL_SOURCE` is empty unless `--url` was sent, and `ANTIDOTE_RUN_ID` is
+empty when no run started:
+
+| Tool | Variables |
+|---|---|
+| `whoami` | `ANTIDOTE_USER_ID`, `ANTIDOTE_EMAIL`, `ANTIDOTE_ORG_ID`, `ANTIDOTE_AUTH_MODE` |
+| `get_product` | `ANTIDOTE_ID`, `ANTIDOTE_BASE_URL`, `ANTIDOTE_DASHBOARD_URL`, `ANTIDOTE_ENVIRONMENTS_TRUNCATED` |
+| `get_batch` | `ANTIDOTE_ID`, `ANTIDOTE_STATUS`, `ANTIDOTE_RUNS_TRUNCATED`, `ANTIDOTE_DASHBOARD_URL` |
+| `record_release` | `ANTIDOTE_RELEASE_ID`, `ANTIDOTE_TARGET_ID`, `ANTIDOTE_TARGET_NAME`, `ANTIDOTE_TARGET_VERSION`, `ANTIDOTE_RUN_ID`, `ANTIDOTE_RUN_STATUS`, `ANTIDOTE_TEST_RUN_ID`, `ANTIDOTE_TEST_RUN_STATUS`, `ANTIDOTE_DASHBOARD_URL` |
+| `record_preview` | `ANTIDOTE_TARGET_ID`, `ANTIDOTE_TARGET_NAME`, `ANTIDOTE_TARGET_VERSION`, `ANTIDOTE_RUN_ID`, `ANTIDOTE_RUN_STATUS`, `ANTIDOTE_EXPLORATION_BATCH_ID`, `ANTIDOTE_PREVIEW_URL_SOURCE`, `ANTIDOTE_COMMENT_ID` |
+
+`ANTIDOTE_RUN_ID` is the batch id. `get_batch`'s verdict and a result's `follow_up`,
+`warnings` and (for `record_release`) `landings` are objects or arrays, so they are not written; use `--json` to
+read them. `list_products` writes only `ANTIDOTE_TRUNCATED`, for the same reason.
+
+A built-in command (`login`, `logout`, `tools`) wins over a tool of the same
+name. Tool commands need a login, `ANTIDOTE_API_KEY`, `ANTIDOTE_SERVICE_IDENTITY` or a CI token:
+logged out, the CLI can't read the tool list, so `antidote whoami` tells you to log in.
+
+## Where state is kept
+
+A signed-in profile per platform URL, in
+`$XDG_CONFIG_HOME/antidote/profiles/<host>[_<port>].json` (default
+`~/.config/antidote/profiles/`): the CLI's client registration, its tokens, and the
+last tool list (so `--help` works offline). Files are mode 0600 in a 0700
+directory. Delete a profile with `antidote logout`.
+
+## Releasing
+
+Publishing is a `cli-v<version>` tag on main; see the header of
+[`.github/workflows/publish-cli.yml`](../../../.github/workflows/publish-cli.yml).