> ## Documentation Index > Fetch the complete documentation index at: https://docs.antigen.sh/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Create, observe, recover, and control authorized Antigen Runs from the command line. `@antigenco/cli` installs the `antigen` command, the interactive path for an organization member who needs to start an authorized Run, follow its evidence, and hand findings to a review process. Every command accepts `--json`, so the same commands work unattended in CI. A Run ID is an opaque locator. Store it with the assessment record, but do not treat possession of an ID as permission: each command is still authorized in the caller's organization context. ## Install ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install --global @antigenco/cli ``` Run `antigen` with no arguments for the full command list, and `antigen version` for the installed version. ## Authenticate The CLI accepts either an interactive device login or an organization API key. `ANTIGEN_API_KEY` takes precedence over stored login credentials whenever it is set. | Credential | Use it for | How it is supplied | | ----------------- | --------------------------------------- | --------------------------------------------------------------------- | | Device login | An interactive member at a workstation. | `antigen login`, stored in `~/.antigen/credentials` with mode `0600`. | | `ANTIGEN_API_KEY` | Unattended automation and CI. | Environment variable only, beginning with `atg_sk_`. | API keys are deliberately not accepted as command-line arguments, because process arguments and shell history expose long-lived credentials. Tokens are never printed. ### antigen login Signs in with a device authorization flow and stores the resulting credentials. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen login --organization-id ``` The organization UUID is required. Supply it with `--organization-id` or `ANTIGEN_ORGANIZATION_ID`. The command prints a verification URL and a user code, then polls until the server deadline. Stored credentials refresh automatically; when the refresh token itself has expired, sign in again. | Option | Description | | --------------------------- | --------------------------------------------------------------------------------- | | `--organization-id ` | The organization authorizing the assessment. Overrides `ANTIGEN_ORGANIZATION_ID`. | | `--platform-base-url ` | Points the verification URL at a non-hosted Platform environment. | ### antigen logout Removes the stored credentials file from the workstation. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen logout ``` This clears local credentials only. It does not stop, resume, or cancel any Run, and it does not revoke an `ANTIGEN_API_KEY` supplied through the environment. ## Global options These options apply to every command. | Option | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `--json` | Emit JSON instead of human-readable output. Streaming commands emit one JSON value per line. | | `--quiet` | Suppress the target banner and event progress from `antigen run`. | | `--base-url ` | Override the API origin. Overrides `ANTIGEN_BASE_URL`; defaults to `https://api.antigen.sh`. | | `--platform-base-url ` | Override the Platform origin used by `login` and `open`. Overrides `ANTIGEN_PLATFORM_BASE_URL`; defaults to `https://platform.antigen.sh`. | A command-line flag always takes precedence over the corresponding environment variable. Use `--base-url` for local development and Preview environments. ## Assess a target ### antigen targets Lists the targets approved for the active organization. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen targets ``` Copy a value from this list unchanged. If a later command reports `TARGET_NOT_APPROVED`, read this list again rather than substituting a hostname from a ticket or a local configuration file. ### antigen run Creates a Run, streams its events, and prints its findings in one command. This is the command most assessments start from. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen run antigen run --targets example.com --model claude-sonnet-4-6 ``` With no options it assesses **every** approved target using `claude-sonnet-4-6` and the Markdown files under `./skills/`. Pass targets explicitly when the assessment should be narrower. | Option | Description | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--target ` | An approved target. Repeat for an explicit target set. | | `--targets ` | A comma-separated approved target set. Combines with `--target`. | | `--model ` | The assessment model. Defaults to `claude-sonnet-4-6`. | | `--guardrails ` | Natural-language scope guidance passed to the model with the Run. | | `--skill `, `--skills ` | Markdown files or directories to send as Skills, replacing the default `./skills/` discovery. Repeatable. Directories are walked in deterministic order and symbolic links are rejected. | Human output opens with the selected targets and closes with finding counts by severity. `--quiet` suppresses the banner and per-event progress while preserving lifecycle truth, findings, and the severity summary. A completed Run exits `0`; a failed or cancelled Run exits `1`. Save the printed Run ID before the command returns. It is the only handle for reconnecting later: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen run --json --targets example.com | tee run.ndjson ``` ## Create and list Runs ### antigen create Creates a Run and returns immediately, without streaming events. Use it when the caller schedules observation separately. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen create --model claude-sonnet-4-6 --target example.com ``` | Option | Description | | -------------------------- | ------------------------------------------------------------- | | `--target ` | Required. An approved target; repeat for several. | | `--model ` | Required. The assessment model. | | `--guardrails ` | Natural-language scope guidance. | | `--skill =` | An inline Skill as a literal `name=content` pair. Repeatable. | `--skill` here takes inline content, not a path. That differs from `antigen run`, where `--skill` takes a file or directory. Persist the printed Run ID before any follow-up work: a second `create` is a new assessment record, not a retry. ### antigen runs Lists Runs visible to the active organization. `antigen list` is an alias for the same command. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen runs --status running --limit 20 ``` | Option | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------- | | `--status ` | Filter by `creating`, `running`, `stopping`, `stopped`, `resuming`, `completed`, `failed`, or `cancelled`. | | `--limit ` | Page size, 1 through 100. Defaults to 50. | | `--cursor ` | An opaque continuation value from a previous page. Pass it back unchanged. | Do not derive authorization, identity, or ordering from a cursor or a Run ID. ### antigen get Reads one known Run by its saved ID. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen get run_0a7f3c215be44d189f628c15d0e37a94 ``` Read the Run here after any interrupted create, wait, or lifecycle command, before sending another request. A local failure tells you what the caller knows, not what the Run did. ## Follow a Run ### antigen events Streams ordered progress events for a saved Run. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen events run_0a7f3c215be44d189f628c15d0e37a94 --after 42 ``` | Option | Description | | -------------------- | ---------------------------------------------------------- | | `--after ` | Resume strictly after this already-handled event sequence. | Persist an event's `sequence` only after the evidence for that event has been handled. On reconnect, pass the saved value to `--after`. Saving the checkpoint first can silently skip unprocessed work; never saving makes the same evidence look new after every interruption. ### antigen findings Reads durable findings and remediation guidance for a saved Run. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen findings run_0a7f3c215be44d189f628c15d0e37a94 --json ``` Findings carry severity, title, description, remediation, and available evidence. A completed Run can legitimately have no findings; record that result rather than treating it as a failure. ### antigen wait Waits locally until a Run reaches `completed`, `failed`, or `cancelled`. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen wait run_0a7f3c215be44d189f628c15d0e37a94 --timeout-ms 300000 ``` | Option | Description | | ------------------------- | -------------------------------------------------------------------- | | `--timeout-ms ` | Total local wait budget. Defaults to `1800000` (30 minutes). | | `--poll-interval-ms ` | Polling interval. Defaults to `1000`, clamped to 100 through 30,000. | The deadline bounds the caller, not the Run. `stopped` is not a terminal state, so a stopped Run keeps the wait running until the deadline expires. When the deadline is reached, reconnect later with `antigen get` and `antigen events --after`; do not cancel unless ending the assessment is the intended decision. ## Guide and control a Run ### antigen send Delivers scoped guidance to a Run that is already under way. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen send run_0a7f3c215be44d189f628c15d0e37a94 "Prioritize the approved target and preserve evidence for review." ``` Everything after the Run ID becomes the message. Keep guidance inside the approved target and Guardrails, and prefer a specific reviewable request over a broad change of purpose. Work outside the approved scope needs its own authorized assessment. ### antigen stop Requests a reviewable pause, leaving the Run resumable. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen stop run_0a7f3c215be44d189f628c15d0e37a94 ``` ### antigen resume Continues a Run observed as `stopped`. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen resume run_0a7f3c215be44d189f628c15d0e37a94 ``` Resuming does not re-evaluate target approval. Confirm the approved scope still applies before you resume. ### antigen cancel Ends the assessment. `cancelled` is terminal. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen cancel run_0a7f3c215be44d189f628c15d0e37a94 ``` Use each lifecycle command to express a decision, not to repair a local timeout. If a lifecycle command returns `INVALID_RUN_STATE`, another transition already occurred: read the Run with `antigen get` and choose an action valid for the observed state rather than repeating the request. ### antigen open Opens a Run's detail page in Platform. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} antigen open run_0a7f3c215be44d189f628c15d0e37a94 ``` Use `--platform-base-url` or `ANTIGEN_PLATFORM_BASE_URL` to target a local or Preview environment. The selected environment must deploy the Run route and have an authenticated session. ## Exit codes | Code | Meaning | | ----- | ------------------------------------------------------------- | | `0` | The command succeeded. For `antigen run`, the Run completed. | | `1` | A runtime error, or a Run that ended `failed` or `cancelled`. | | `2` | Invalid command-line usage. | | `130` | Interrupted, such as by Ctrl-C. | Because `antigen run` maps a failed or cancelled Run to exit `1`, a CI job can gate on the assessment result directly. Distinguish it from a usage error by the exit code rather than by parsing output. ## Errors and recovery With `--json`, errors are emitted on stderr as `{"error":{"code":…,"message":…}}`. | Code | First safe action | | ----------------------- | ----------------------------------------------------------------------------- | | `UNAUTHENTICATED` | Sign in again, or confirm `ANTIGEN_API_KEY` is set and begins with `atg_sk_`. | | `FORBIDDEN` | Confirm the credential carries the scope the command needs. | | `TARGET_NOT_APPROVED` | Re-read `antigen targets` and use a value from that list unchanged. | | `RUN_NOT_FOUND` | Confirm the saved Run ID and the organization the credential belongs to. | | `INVALID_RUN_STATE` | Read the Run with `antigen get` and choose an action valid for its status. | | `EXECUTION_UNAVAILABLE` | Wait and run the command again. Capacity is temporarily exhausted. | | `CLI_USAGE` | Correct the command-line arguments; see `antigen` with no arguments. | `RUN_NOT_FOUND` is also what a Run in another organization returns. Before concluding the Run is gone, confirm which organization the stored credential belongs to by reading `antigen targets`, or sign in again with `antigen login --organization-id `. A successful exit means the CLI received a response for that invocation. An unsuccessful exit, a terminal interruption, or an expired wait does not by itself establish the Run's durable state. Preserve the Run ID and any service request ID reported with an error. Related concepts: [Get started](/getting-started), [Guides](/guides), [Examples](/examples), and [HTTP API reference](/http-api).