Skip to main content
@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

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

​
antigen logout

Removes the stored credentials file from the workstation.
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. 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.
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.
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. 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:

​
Create and list Runs

​
antigen create

Creates a Run and returns immediately, without streaming events. Use it when the caller schedules observation separately.
--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.
Do not derive authorization, identity, or ordering from a cursor or a Run ID.

​
antigen get

Reads one known Run by its saved ID.
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.
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.
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.
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.
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.

​
antigen resume

Continues a Run observed as stopped.
Resuming does not re-evaluate target approval. Confirm the approved scope still applies before you resume.

​
antigen cancel

Ends the assessment. cancelled is terminal.
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.
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

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":…}}. 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 <uuid>. 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, Guides, Examples, and HTTP API reference.