CLI

Authenticate

Catalog search and pull require sign-in so we can attribute usage. The public catalog is free — authentication is not a paywall.

adversary login
adversary whoami

Headless and CI options include adversary login --device, --ci, and service-account tokens via --token-stdin. See Registry authentication.

Quick start

New here? Follow the getting started guide. Short version:

adversary pull go/security

adversary run go/security --path .

# Or author and run a local project
adversary init my-adversary
cd my-adversary
npm ci && npm run build
adversary run . --path ../service

Catalog ids use domain/name form (for example go/security, ci/github-actions). Browse the live catalog at /adversaries.

Command reference

Canonical flags live in the binary: adversary help <command>. Global flags: --api-url, --profile.

adversary run

Review a local source tree. Pass one or more adversary references, or omit them to auto-select from the catalog and local store.

adversary login
adversary run --path .
# pulls accessible catalog packages (unless --no-pull),
# detects which apply to the review scope, and runs them

adversary run --dry-run --explain --path .
adversary run --all --all-files --path .
adversary run go/security security/secrets --path . --format json

Composition (uses)

Explicit refs expand adversary.yaml uses transitively (language packs like lang/go, personas like torvalds). Detection runs on each member; GitHub comment voice stays on the entry package. See the SDK docs for the manifest field shape.

# Language pack (adversary.yaml uses → go/* specialists)
adversary run lang/go --path ./service

# Persona pack (uses specialists; voice from entry agent/voice*)
adversary run local/torvalds-adversary --path ./app --github-review

# Local checkout as entry
adversary run ./torvalds-adversary --path ./app --github-review

# Skip expansion — only the named package
adversary run lang/go --path ./service --no-compose

Comment voice

With --github-review, the CLI rewrites comment bodies using the package agent/voice.md (core rules + optional example few-shots). Voice is how it sounds; findings still carry technical depth. Under composition, the package you name on the CLI owns voice—not every specialist. Train apply banks human gold into the example-bank subsections (style only).

# Rewrite PR comments with package agent/voice.md (needs model provider)
export OPENAI_API_KEY=…   # or provider-specific env
adversary run ./torvalds-adversary --path ./app   --github-review --github-dry-run   --model-provider openai --model gpt-4o-mini

# Voice resolve order: package agent/voice.md → train/voice.md → voice.md → CLI default
# Without model credentials, comments keep the deterministic template body.

Train (home-built packages)

Improve your local adversaries from your team’s real PR reviews. Train grades local packages against human comments, optionally runs official catalog packages as a read-only jury, and writes an inbox of drafts. Only locals receive apply issues—never official catalog ids.

# From a home-built package root (has adversary.yaml)
export GH_TOKEN=…   # or ADVERSARY_GITHUB_TOKEN / GITHUB_TOKEN

adversary train init --single-package
# edit adversary.train.yaml:
#   sources.repos / sources.org  OR  discovery: author_reviews + authors_only
#   official.enabled: true  (jury; never trains official packages)

adversary train run
adversary train results ls
adversary train results inspect <id>
adversary train results apply <id>
# → docs/train-drafts/<id>.md + GitHub issue on the package remote
# Implement detection class + bank human gold in agent/voice.md (style only)

Subcommands: train init, train run, train results ls|inspect|apply|dismiss, train status, train reset. Config: committed adversary.train.yaml; state: gitignored .adversary-train/. On apply, implement detection for the spirit class and bank human wording in agent/voice.md (style few-shots only).

Scope inference (when you omit --base/ --head/ --all-files): CI PR refs → worktree changes → feature branch vs default branch → whole tree. Selected scope is printed on stderr before execution.

Catalog lifecycle

adversary search dockerfile
adversary list
adversary list --outdated
adversary pull go/cli
adversary outdated
adversary remove go/cli:0.0.15

List and search merge the local store with the remote catalog you can access. Status is installed, catalog, or outdated. Retired path styles are hidden; domain catalog ids remain.

Author and publish

Only the TypeScript SDK template is supported for adversary init. Node.js 22+ is required and managed by you (the CLI does not download Node).

adversary init my-adversary --sdk typescript
cd my-adversary
npm ci && npm test && npm run build
adversary validate .
adversary pack .
adversary push my-adversary:0.1.0 ghcr.io/acme/my-adversary:0.1.0

Official catalog packages are signed in release CI after push. For private packages, any OCI registry works. See Distribution and Official signatures.

Trust and host execution

Local projects selected by filesystem path run on HostExecutor without friction. Installed packages need a verified official signature for the same. Unsigned packages are untrusted: interactive TTY prompt, or --allow-unsafe-host-execution in CI.

Details: Official signatures · Execution trust model.

Configuration

Precedence: command flags → environment → profile config → defaults.