> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# tolmo red-agent

> Check readiness, start runs, set the schedule, manage test accounts, and list run history for the Red team agent from the CLI.

Use `tolmo red-agent` to operate the Red team agent from a terminal or a pipeline. It sends the same requests as the **Red team agent** page in the web app, so a change you make here shows up there. `tolmo red` is an alias.

For what the agent does and how it tests, see [How the Red team agent tests](https://docs.tolmo.com/pentesting/red-team-agent.md).

Every subcommand accepts `--org`, `--profile`, and `--json`.

> [!NOTE]
>
> Starting a run and changing the schedule require an organization admin or an organization API key.

## Check readiness

```bash theme={null}
tolmo red-agent readiness
tolmo red-agent readiness --json
```

Readiness reports whether the agent has what it needs to run:

| Field | Meaning |
| - | - |
| `ready` | `true` when every required item is in place |
| `provider` | A connected integration that can discover your attack surface |
| `domain` | At least one discovered domain |
| `slack` | Slack is connected for notifications |
| `test-accounts` | Optional. At least one test account exists |
| `instructions` | Optional. App-access instructions are set |

A run also needs at least one domain with offensive testing enabled.

To finish setup, see [Define scope: domains and test accounts](https://docs.tolmo.com/pentesting/scope.md).

## Start a run now

```bash theme={null}
tolmo red-agent run
tolmo red-agent run --json
```

This starts the same whole-organization run as **Start run** in the web app. It tests every authorized domain. The output names the scan ID and the workflow ID of the new run.

An on-demand run is in addition to the schedule. It does not replace or move the next scheduled run.

## Set the schedule

The schedule keeps testing going as production changes. See [Keep up with production changes](https://docs.tolmo.com/pentesting/production-changes.md) for how to choose a cadence.

```bash theme={null}
tolmo red-agent schedule get
tolmo red-agent schedule set --frequency day --time 06:00 --timezone Europe/Paris
tolmo red-agent schedule set --frequency week --days mon,thu --time 14:00 --timezone America/New_York
tolmo red-agent schedule pause
tolmo red-agent schedule resume
```

`tolmo red-agent schedule` without a subcommand is the same as `schedule get`.

`schedule set` creates or replaces the schedule with these flags:

| Flag | Default | Behavior |
| - | - | - |
| `--frequency` | `week` | `day` or `week` |
| `--interval` | `1` | Repeat every N days or weeks |
| `--time` | `14:00` | Local start time as `HH:mm` |
| `--timezone` | `UTC` | IANA timezone, such as `Europe/Paris` |
| `--days` | `0` (Sunday) | Weekdays as `0`–`6` or `sun,mon,…`. Weekly schedules only; at least one day is required. |

`pause` stops scheduled runs without deleting the schedule. `resume` turns it back on. If Tolmo manages a testing campaign for your organization, you can pause it but not delete it.

## Manage test accounts

Test accounts let the agent sign in and test what a signed-in user can reach. `tolmo red-agent test-accounts` is an alias for `accounts`.

```bash theme={null}
tolmo red-agent accounts list
tolmo red-agent accounts get <id>
tolmo red-agent accounts create --kind password --username qa@example.com \
  --role admin --privileged --domain app.example.com --secret-file - <<<"$QA_PASSWORD"
tolmo red-agent accounts update <id> --notes "Use the staging tenant"
tolmo red-agent accounts delete <id>
```

Secrets never go on the command line. Pass them with `--secret-file` or `--totp-seed-file` (use `-` to read from stdin), or inside a `--file` JSON body. `list` and `get` never return a secret.

### Account flags

`create` and `update` accept these flags. On `update`, a flag you do not pass leaves that field unchanged.

| Flag | Behavior |
| - | - |
| `--kind` | Login method: `password`, `header`, or `bearer`. Cannot change after creation. |
| `--username` | Sign-in identity, for `password` accounts |
| `--login-url` | Where the account signs in. Optional hint. |
| `--role` | Role in your app, such as `admin` or `member` |
| `--privileged` | Mark the account as privileged |
| `--group` | Group path segment, outermost first. Repeatable. |
| `--capability` | `totp`, `email_otp`, or `sms_otp`. Repeatable. |
| `--header-name` | Header name, for `header` and `bearer` accounts |
| `--phone` | Phone number. Required with `sms_otp`. |
| `--otp-email` | Inbox for one-time codes. Required with `email_otp`. |
| `--notes` | Notes the agent reads |
| `--notes-private` | Private notes, stored encrypted |
| `--domain` | Hostname or domain ID this account is for. Repeatable. On `update`, replaces the linked domains. |
| `--secret-file` | File that holds the password, header value, or token |
| `--totp-seed-file` | File that holds the TOTP seed or `otpauth://` link |

`create` also accepts `--file` (`-f`): a JSON body in the API's shape, or an array of bodies to create several accounts at once. `update` also accepts `--clear-notes-private` and `--clear-domains`.

## List runs

```bash theme={null}
tolmo red-agent runs --days 7 --run-status completed --json
```

| Flag | Behavior |
| - | - |
| `--days` | Runs started in the last N days. `1` means the last 24 hours. |
| `--severity` | Comma-separated severities: `critical`, `high`, `medium`, `low`, `info` |
| `--run-status` | Comma-separated `running`, `completed`, or `failed` values |
| `--limit` | Page size from `1` to `200`. Defaults to `100`. |
| `--offset` | Number of matching runs to skip. Defaults to `0`. |

Each JSON response contains `items` and `total`. Increase `--offset` to get the next pages.

For the same history in the web app, see [Mission Control and agent runs](https://docs.tolmo.com/agents/mission-control.md).

## Blue Agent runs

The Blue team agent validates findings from your other security tools. List and inspect its runs with `tolmo blue-agent`:

```bash theme={null}
tolmo blue-agent runs --days 7 --severity high,critical --json
tolmo blue-agent runs show <run-id>
tolmo blue-agent runs show <run-id> --json
```

`blue-agent runs` accepts the same filters as `red-agent runs`. It also accepts `--scope` for comma-separated target hostnames and `--search` for a run ID or workflow ID.

The `show` identifier can be a scan ID, a `RUN-` prefix, or a workflow ID. The detail view shows the run's execution stages. A completed run does not by itself mean a finding was confirmed. Review the result and the linked finding with [`tolmo findings`](https://docs.tolmo.com/cli/commands/findings).

See [Validate the findings you already have](https://docs.tolmo.com/pentesting/third-party-findings.md) for what the Blue team agent does.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.