Skip to main content
The CLI handles everything: interactive setup, attack generation, firing attacks, judging responses, and producing reports. It’s the primary surface for engineers and CI.

​
Install

npm install -g @agent-opfor/cli
From source (contributors): 
git clone https://github.com/KeyValueSoftwareSystems/agent-opfor.git
cd opfor
npm install
npm run install:cli   # builds + installs `opfor` globally

​
Two testing modes

Opfor decides which pipeline to run from target.kind. Pick one per config.
ModeTargetHow attacks are deliveredHow responses are judged
agentHTTP endpoint or local script speaking LLM chatAttacker LLM writes free-text adversarial prompts; opfor sends themJudge LLM reads the target’s text reply
mcpMCP server (stdio process or remote URL)Opfor lists tools; attacker LLM crafts tool name + JSON args; opfor fires tools/callJudge LLM reads the JSON-RPC response, plus a resource + rug-pull scan
This is different from running opfor itself as an MCP server so AI assistants can invoke it.

​
Create a config

Interactive wizard (recommended): 
opfor setup           # prompts: agent vs mcp, provider, target, suite, effort, turns, telemetry
opfor setup --agent   # skip the mode prompt, go straight to the agent wizard
opfor setup --mcp     # skip the mode prompt, go straight to the MCP wizard
Blank config to hand-edit: 
opfor setup --agent --empty   # minimal agent config, no prompts
opfor setup --mcp --empty     # minimal MCP config, no prompts
Configs land in .opfor/configs/opfor-config-<timestamp>-<id>.json unless you pass --config <path>.
Add .opfor/ to .gitignore — it holds configs and reports with embedded target metadata.

​
Config shape

{
  "target": {
    "kind": "agent",
    "name": "My Support Bot",
    "description": "A customer support chatbot with access to booking data and PII. Can issue partial refunds.",
    "type": "http-endpoint",
    "endpoint": "http://localhost:4000/chat",
    "requestFormat": "openai"
  },
  "selection": { "mode": "suite", "suite": "owasp-llm-top10" },
  "attackerLlm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "apiKeyEnv": "OPENAI_API_KEY"
  },
  "effort": "adaptive",
  "turnMode": "multi",
  "turns": 3
}
apiKeyEnv is the env var name holding the key — never the key itself. Don’t put raw keys in a config file.

​
API keys

The attacker/judge LLM key is read at run time. Set it in your shell or a .env file in the working directory: 
export OPENAI_API_KEY=sk-...
Load a non-default path with --env: 
opfor run --config <path> --env .env.prod

​
Next

Running scans

Execute, runtime overrides, and reports.

Config reference

Every config field for agent and MCP targets.