Command line

The hackagent command runs red-team campaigns against AI agents from your terminal. You describe a run in a campaign file, check it, run it, and read the results, on your own machine or recorded on the HackAgent platform. The same command serves the web dashboard and runs the campaigns you queue from it.

Install it

Install the hackagent package, or download a standalone binary, as Installation describes. The base install has every command on this page except two that need an extra: hackagent web needs hackagent[web], and the terminal app needs hackagent[tui].

Check it works:

hackagent --version
hackagent doctor

hackagent doctor reports the config file, the local database, the storage backend, whether an API key is set, and optional dependencies such as Graphviz. It changes nothing.

The commands

Run hackagent with no command to open the terminal app. Every other command is listed in Commands, with all its options.

Command	What you use it for
hackagent campaign	Validate and run campaign files, list the attacks, print the campaign JSON Schema. See Running campaigns.
hackagent examples	List the bundled example campaigns, copy one to edit, or run one.
hackagent datasets	Browse the dataset presets and print sample goals from one.
hackagent results	Summarize recent results, or show one result in detail.
hackagent web	Serve the dashboard from this machine. See The dashboard server.
hackagent run	Run a campaign queued from the dashboard on this machine. See Running queued runs.
hackagent config	Show, set, validate, import and reset settings. See Configuration.
hackagent init	Answer a few questions and save a config file.
hackagent doctor	Check your setup.
hackagent tui	Open the terminal app, which builds, checks and runs a campaign.
hackagent version	Print the version and the config file path.

Options such as --backend and --config-file belong to hackagent itself, so they go before the command: hackagent --backend remote results summary. Configuration lists them.

Typical workflows

Validate and run a campaign on your machine

Nothing leaves your machine except the calls to the models the campaign names. Start from an example, check it, then run it:

hackagent examples list
hackagent examples copy h4rm3l-demo        # writes h4rm3l-demo.yaml here
hackagent campaign validate h4rm3l-demo.yaml
hackagent campaign run h4rm3l-demo.yaml
hackagent results summary

Each run writes its files under ./logs/runs/<run id>/ and its results to the local database. Running campaigns explains the output, the exit codes and the run-time options; Your first campaign walks through writing one from scratch.

Record runs on the HackAgent platform

Put your API key in the environment, never in a file:

export HACKAGENT_API_KEY="your_api_key"

A campaign is recorded on the platform when its execution.storage says so. Its api_key names the variable:

execution:
  storage:
    backend: remote
    api_key: "${HACKAGENT_API_KEY}"

hackagent campaign run campaign.yaml

To read the platform's results instead of the local ones, select the remote backend once, or for one command:

hackagent config set --backend remote      # saved in the config file
hackagent --backend remote results summary # this command only

Configuration explains what each backend changes.

Open the dashboard

pip install 'hackagent[web]'
hackagent web

With the default local backend, the dashboard shows the runs in your local database. With the remote backend, it shows your platform data. Either way it listens on this machine only. The dashboard server covers the modes and options; the Dashboard guide covers the pages themselves.

Run a campaign queued from the dashboard

On the HackAgent platform you can queue a run for "a local machine". The run waits until a machine with your API key claims it:

export HACKAGENT_API_KEY="your_api_key"
hackagent run              # lists the queued runs and asks which one
hackagent run <run id>     # runs that one

The campaign runs here, with your model keys, and the dashboard follows it live. See Running queued runs.

Where to go next

• Configuration: the config file, environment variables, backends, CA bundles and proxies.
• Campaign files: every field of the campaign format.
• Troubleshooting: common errors, what causes them, and how to fix them.