# Red Team Agent: Automated Penetration Testing
Source: https://docs.tolmo.com/agents/red-team-agent

Red Team Agent tests your authorized domains the way an attacker would. Authorize domains, understand the ten-day run schedule, review validated findings, and copy a fix prompt straight into your editor.

![Tolmo Red Agent](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/cover.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=aa544f03fe9cf51dbba5d95ae8986a36)

Red Team Agent tests your authorized domains the way an attacker would, and reports only what it could actually reproduce — so you can fix real vulnerabilities before somebody else finds them.

This page covers the current release: how to authorize what it may test, when it runs, how to read what it finds, and how to act on a finding without leaving the page.

## What Red Team Agent does

Red Team Agent attacks your own application from the outside, the way an attacker with no inside knowledge would. It works only against domains your organization has explicitly authorized, it announces itself as a test, and it never sends anything destructive.

It reports what it could actually reproduce. A finding appears because the agent ran a request and got a result it should not have — not because a scanner recognized a pattern. Every finding carries the request that proved it.

### The lifecycle

Four steps, and the product is arranged in that order:

**1. Authorized domains**

You authorize what may be tested, once.

**2. Automatic testing**

Testing happens on a schedule, without being asked.

**3. Findings**

What the agent proves arrives on the Red Team Agent page.

**4. Actionable fixes**

Each finding carries enough context to be fixed from the page it is on.

![The Red Team Agent page: header with agent status and actions, a completed run, three result metrics, the findings table, and the run schedule and actionable findings cards in the right column.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/overview.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=d583431c10a8c363d3683211dbdd10aa)

Red Team Agent is one of three agents that share a findings model. Blue triages findings from your other security tools, and Green verifies fixes. Red is the one that goes and attacks something.

## Set up Red Team Agent

Until something is in scope there is nothing to attack, so a new workspace opens on a setup checklist instead of an empty dashboard. Three tasks, each with the control that completes it.

![The Get ready to run checklist with three rows: connect your environment, configure authorized domains, and configure notifications.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/setup-checklist.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=2d51d521f5ebddecd3ed6d90bcbb6fda)

| Task | What it gets you |
| - | - |
| **Connect your environment** | AWS, GCP, or Azure. Your attack surface is discovered from the connected account rather than typed in by hand, so this is what gives the agent something to look at. |
| **Configure authorized domains** | The domains the agent is permitted to test. Nothing outside this list is ever in scope. |
| **Configure notifications** | Where run results and new findings are announced. |

Once a domain is authorized, the header status changes from **Not set up** to **Watching** and the agent joins the schedule. Everything after this point is adjustment, not setup.

### Change the configuration later

Open **Settings** in the page header. One dialog holds what the agent tests, how often it tests, and where it reports — the three things you might come back to change.

![The Red Team Agent settings dialog showing domains in scope, the fixed ten-day run cadence, and a notifications grid of events against email and Slack.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/settings-modal.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=97c35dfdf161222422d09d3f0e9c4419)

## Authorize the domains it may test

**Domains in scope** is the list of domains Red Team Agent is allowed to attack. It is the only thing that decides where the agent may act: a hostname that is not covered by an entry on this list is never touched, on any run.

### Why authorization is required

Your domain inventory is built from public DNS and certificate transparency, so it lists names your organization does not own — a typosquat, a partner's hostname, something a former employee still holds. Appearing in the inventory is not ownership, and it is not permission to attack. Authorization is therefore two separate steps, in this order:

**1. Verify ownership**

Tolmo gives you a `tolmo-domain-verification=…` TXT record to publish in the domain's DNS zone. Only someone who controls the zone can publish it, which is the point — it cannot simply be asserted.

**2. Permit the domain**

A separate, explicit decision that offensive testing is allowed against it. Verifying a domain does not authorize anything on its own.

![The which domains Red may test step, listing domains from the inventory with hostname counts and either a Verify ownership or a Revoke control.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/domains-permit.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=853fcc9c10d225df0e902134264a413d)

### What an entry covers

An entry covers the domain and everything beneath it. Permitting `staging.example.com` permits every hostname under it, which is how people already think about a staging environment. The row shows the hostname count so you can see the size of what you are agreeing to.

Each domain in the list reads as one of three states:

* **Red may test these** — verified and permitted. In scope.
* **Ownership proven, not authorised** — verified, but deliberately not permitted.
* **Something beneath it is authorised** — the domain itself is out of scope, but an entry below it is in scope.

> [!NOTE]
>
> This is one setting for the whole organization, not a per-agent one. Blue and Green read the same list. Revoking an entry takes effect immediately: the agents read the list at the moment they run, so the next run is already out of scope. Revoking keeps the ownership verification, so you never have to re-publish a DNS record to undo a policy decision.

### Where to manage it

Two routes to the same list. Use **Change what is permitted** inside **Settings** when you are already adjusting the agent, or **Manage** on the **Domains** card to open the domain inventory, where the permission lives as a property of the domain.

## Understand the run schedule

Red Team Agent tests every **10 days**, automatically, across every authorized domain. A full run takes roughly ninety minutes, and its findings take days to work through — ten days leaves room to close them before the next run asks again.

The cadence is fixed in this release. It is stated on the **Run schedule** card and in **Settings** as a fact rather than offered as a choice, because there is no control that changes it.

![The Run schedule card: last run three days ago completed, next run available in seven days, a ten-tick cycle rail, and the Domains section showing one authorized domain with seven hostnames.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/run-schedule.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=d03d3c1050fcc5bc2baae38e039ee934)

| Field | What it tells you |
| - | - |
| **Last run** | When the most recent run happened and how it ended. **Completed** means the run finished; what it concluded is the three numbers and the findings table below. |
| **Next run** | When the agent will test again on its own — **Available today**, **Available tomorrow**, or **Available in n days**. |
| **Every 10 days** | The cadence, as a tag beside the card title. The rail underneath has one tick per day, so the gap reads as a countable stretch rather than an undifferentiated bar. |
| **Domains** | What the schedule runs against, in the same card. A schedule with no scope is a rhythm against nothing, so the two are one answer. |

> [!TIP]
>
> **Start run** in the page header runs the agent now, against the same authorized domains. It is an additional run: it does not consume the scheduled one and it does not move the date on the right. If ten days is too slow for your release cycle, the run dialog carries a way to ask us for a faster schedule.

**View all** on the card, and **View runs** in the header, both open the full run history. See [View run history in Mission Control](#view-run-history-in-mission-control).

## Choose where results are announced

Runs happen without you watching, so notifications are how you find out. Open **Settings** in the page header and use the **Notifications** grid: events down the side, channels across the top. One cell answers "does a completed run reach Slack".

![The notifications grid: run started, run completed and new finding, each with an email and a Slack toggle, above a note naming the destination address and channel.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/notifications.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=19cf44f978bd78c2beb11577cd1f3823)

| Event | When it fires |
| - | - |
| **Run started** | Red Team Agent has begun testing. |
| **Run completed** | With what it found, or that it found nothing. |
| **New finding** | A vulnerability was reproduced. |

Channels are **Email** and **Slack**. The destinations — which address, which channel — are set once for the whole organization in **Notification settings**, not per agent. The panel names the current destinations so you can see where a toggle will actually send something.

> [!NOTE]
>
> A run that finds nothing still sends a **Run completed** notification if that event is on. A clean result is a result, and silence is indistinguishable from a run that never started.

## Understand your results

Three numbers sit above the findings table. They describe the same set of issues at three different levels of certainty, so reading them left to right tells you how much of the last run is settled.

![Three metrics side by side: Discovered 18 potential issues found, Needs review 3 require your attention, Validated 11 confirmed exploitable.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/results-metrics.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=d6362132d81d695059c4ae1e2496b943)

| Metric | What it counts |
| - | - |
| **Discovered** | Potential issues found. Everything the run surfaced, before the agent decided what it could prove. |
| **Needs review** | Require your attention. The agent got far enough to be worth your time and not far enough to call it, so it is holding the finding for a person. This is the number you work down. |
| **Validated** | Confirmed exploitable. The agent reproduced the issue and kept the request that did it. |

After a run that found nothing, all three read zero and the table says so explicitly rather than looking empty. A run that completed clean is the product working.

![A run completed strip naming the run id, eighteen of eighteen paths, the duration, the host, and a two new findings tag.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/run-completed.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=cd5aa834c3887c9b698d18c33cff5434)

## Review findings

The findings table lists what the last runs produced, most severe first. Four columns: **Severity**, **Finding**, **Stage**, and **Run**.

![The findings table with Stage, Severity and Recent runs filters, a search field, and five rows in four columns: severity, the finding title with its affected endpoint underneath, the stage, and the run id.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/findings-table.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=f29457b389e76c80008a0f8290181f18)

### Narrow the list

* **Search findings or targets** matches both the finding title and the affected address, so you can search by endpoint as well as by name.
* **Stage**, **Severity**, and **Recent runs** filter the list. Each choice you make becomes a tag underneath that you can drop on its own.

### Severity

**Critical**, **High**, **Medium**, and **Low**, on the same scale and in the same colors as the rest of Tolmo. It is the first column and the table sorts by it, so the row at the top is the one to open.

### Stage

The stage says where a finding is in its life on this page.

| Stage | Meaning |
| - | - |
| **Detected** | Reproduced by the agent and not waiting on anybody. Ready to be fixed. |
| **Validated** | Confirmed exploitable, with the request that did it kept as evidence. |
| **Needs review** | Waiting on your decision. Open the row and answer it there. |
| **Accepted** · **Dismissed** · **Deferred** | What a **Needs review** finding becomes once you have answered it. A dismissed finding keeps the reason it was dismissed, and does not come back as new on the next run. |

### The affected target

Under each title is the address or endpoint the finding is about — a full URL, or a method and path such as `POST /api/auth/reset-password`. The **Run** column names the run that produced it, which is the link back into the run history.

> [!TIP]
>
> The table on this page is a working view of the most urgent findings, not the whole record. **Open in Findings** inside any finding, and **View All** on the **Actionable findings** card, open the full findings list with the same context carried over.

![The Actionable findings card showing the most urgent finding with a View finding button and a severity mix bar reading four critical, five high, two medium.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/actionable-findings.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=47d5b53af7ad1d2923b68b088099ff5a)

## Take action on a finding

Click a row. The finding opens in place, underneath the row it belongs to — the table stays where it is, so closing it puts you back exactly where you were.

It opens on one layer, which answers four questions in order:

* **What happened** — what the agent did, and what came back.
* **Why it matters** — who could do this, and what they would get.
* **Key evidence** — the one request and response that carries the argument.
* **Recommended fix** — the change that closes it.

![An opened finding: severity and title, the stage chip and affected endpoint, a Copy fix prompt button, then what happened, why it matters, key evidence as a request and response, and a recommended fix.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/finding-detail.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=553a69da57e5492512d926f8adf0a922)

This is enough to decide and act on without reading a technical report. The technical record is kept, folded behind [See more](#see-the-complete-technical-detail).

### Answer a finding that needs review

A **Needs review** finding carries three answers in its own panel. There is no fourth.

![The action row of a needs-review finding: Copy fix prompt, Accept, Dismiss, Defer, and Open in Findings.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/needs-review-actions.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=b6c87fa9078dfa8d93d2cad5312be011)

| Answer | What it means |
| - | - |
| **Accept** | It is real. The finding moves on as something to fix. |
| **Dismiss** | It is not. Choose a reason — **Not exploitable**, **Accepted risk**, **False positive**, **Out of scope**, or **Already fixed**. The reason is kept with the decision, so the next person can see why rather than doing the work again. |
| **Defer** | Not now. It stays in the queue. |

> [!NOTE]
>
> A decision stays decided. What you dismiss does not return as a new finding on the next run, and **Undo** is there beside the decision if you clicked the wrong one.

## Copy a fix prompt

**Copy fix prompt** is the primary action on every finding. It copies the whole finding to your clipboard as a single instruction, written for a coding agent, scoped to the affected endpoint.

![The action row of an opened finding, with Copy fix prompt as the primary button next to Open in Findings.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/copy-fix-prompt.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=d78920c50be1ed714442ba9df0ebb44b)

What you get is the finding as a prompt: the severity and title, the affected address, what happened, why it matters, the evidence, and the recommended fix — ending with an instruction to propose the smallest change that closes it and to say how to verify the fix.

Paste it into whatever you fix code with — Claude Code, your editor's assistant, or a colleague's terminal. Tolmo does not apply the change: the agent identifies and proves the vulnerability, Tolmo hands over the context to fix it, and you decide what to ship.

> [!TIP]
>
> The prompt is deliberately self-contained. It carries the evidence, so whoever receives it does not need access to Tolmo to understand what they are fixing.

## See the complete technical detail

**See more**, at the bottom of an open finding, unfolds the technical record. The first layer is for deciding and acting; this layer is for whoever has to reproduce the issue or review the fix.

![The expanded technical detail of a finding: reproduction steps, the full request and response, technical context, impact, remediation detail, and the run that found it.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/finding-see-more.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=b976cb1fbcfd6fabb08ca147410633f9)

| Section | What it holds |
| - | - |
| **Reproduction** | Numbered steps that reproduce the issue from a signed-in session. |
| **Request and response** | The full exchange, headers included, as the agent sent and received it. |
| **Technical context** | Why the code behaves this way — which is usually why the issue was not obvious. |
| **Impact** | What it means beyond the endpoint, including regulatory consequences where they apply. |
| **Remediation detail** | The fix in full, with the regression test and the audit worth doing alongside it. |

The hierarchy is deliberate: quick view to understand and act, **See more** to investigate. **Show less** folds it back. Not every finding has a second layer — where there is nothing more to show, the control is not there.

## View run history in Mission Control

The Red Team Agent page shows the current state: the last run, and what it left you to work on. The full operational history lives in Mission Control, which answers a different question — not "what security issues do I have" but "what have my agents been doing".

**View runs** in the page header and **View all** on the **Run schedule** card both open Mission Control with **Red Agent** already applied as a filter, so you land on your runs rather than on every run in the organization.

![The Agent runs table in Mission Control with the Red Agent filter active, showing run id, agent, trigger, status, result and start time for each run.](https://mintcdn.com/tolmo/kiwEv-e5yPkqiwY3/images/red-team-agent/mission-control-red-runs.png?fit=max\&auto=format\&n=kiwEv-e5yPkqiwY3\&q=85\&s=275405a8fab42a7e2a11638b9fdabb23)

| Column | What it holds |
| - | - |
| **Run** | The run's id, with the target it ran against underneath. |
| **Trigger** | What set the run off. |
| **Status** | Whether the run finished — **Running**, **Completed**, or **Failed**. |
| **Result** | What it concluded, which is a separate fact from whether it finished: how many issues reproduced, whether a check could not complete, or that nothing reproduced. |
| **Started** | When it began, and how long it took. |

Expand a run to see the findings it touched, by name. A finding is referenced rather than copied, so the same issue crossing Blue, Red, and Green stays one finding with several runs against it. The filter chips at the top switch between agents and statuses, and **All runs** clears them.

> [!NOTE]
>
> A failed check is not a finding. It is a probe that could not complete, which is a gap in coverage rather than a vulnerability — the **Result** column reports it so it does not pass unnoticed.

## Next steps

> **[Manage findings from the CLI](/commands/findings)**
>
> Create, triage, and update findings with `tolmo findings`.

> **[Threat models](/features/threat-model)**
>
> Download threat model pipeline runs and artifacts.

Still stuck? Email [support@tolmo.com](mailto:support@tolmo.com) and tell us what you were trying to cover.


# Review agent run history
Source: https://docs.tolmo.com/agents/run-history

List existing Red and Blue Agent runs and inspect Blue Agent execution details from the CLI.

Use the CLI to review completed and active runs for your organization.

## List runs

```bash theme={null}
tolmo red-agent runs --days 7 --run-status completed --json
tolmo blue-agent runs --days 7 --severity high,critical --json
```

Both commands support these filters:

| Flag | Behavior |
| - | - |
| `--days` | Runs started in the last N days |
| `--severity` | Comma-separated severities |
| `--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 retrieve subsequent pages.

Blue Agent also supports `--scope` for comma-separated target hostnames and `--search` for a run ID or workflow ID.

## Inspect a Blue Agent run

```bash theme={null}
tolmo blue-agent runs show <run-id>
tolmo blue-agent runs show <run-id> --json
```

The 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](/commands/findings).


# List activity events
Source: https://docs.tolmo.com/api-reference/activity-feed/list-activity-events

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/activity-feed/events
Cursor-paginated Mission Control activity events. Filters are applied before the page limit; follow nextCursor until null.



# Authenticate to the Tolmo API with an API key
Source: https://docs.tolmo.com/api-reference/authentication

Create an API key in the Tolmo app, send it as a bearer credential, and understand how keys and user tokens expire and are revoked.

Every Tolmo API request carries a bearer credential in the `Authorization` header:

```bash theme={null}
curl https://api.tolmo.com/api/v1/orgs/acme/findings \
  -H "Authorization: Bearer $TOLMO_API_TOKEN"
```

A request with no credential, an unknown credential, or an expired credential returns `401`.

## Get an API key

An API key is scoped to one organization rather than to a person, which is what you want for automation — it keeps working when the person who created it changes roles or leaves.

**1. Open API keys**

Go to [API keys](https://app.tolmo.com/settings/api-keys) in the Tolmo app (**Settings → API keys**).

**2. Create a key**

Click **Create key**. Give it a name you will recognize later, such as the pipeline or service that will use it.

**3. Copy it immediately**

The key is shown **once, at creation**. Copy it then — it cannot be retrieved afterwards.

**4. Send it on every request**

Export it with your org slug, then pass it as a bearer credential:

```bash theme={null}
export TOLMO_API_TOKEN="api_tok...."
export TOLMO_ORG_SLUG="acme"
```

An API key is scoped to its organization. Endpoint-specific permissions still apply, and user-only endpoints reject API keys. For example, a key created this way carries ordinary member permissions, so it can read published findings and create drafts, but it cannot publish one. Evidence attachments and user membership endpoints require a user token.

> [!NOTE]
>
> Keys created before this credential was renamed begin with `org_tok.` instead of `api_tok.`. They remain valid and need no action — authentication is by a hash of the whole value, so the prefix is only a label.

> [!WARNING]
>
> Store API keys in your CI provider's secrets vault. Never commit one to source control or paste it into a workflow file — a leaked `api_tok.` is valid for your whole organization until it is revoked.

## Credential types

Tolmo issues two kinds of credential. You can tell them apart by their prefix.

| Prefix | Type | Acts as | Use it for |
| - | - | - | - |
| `api_tok.` | API key | The organization, not a person | CI pipelines, servers, scheduled jobs |
| `usr_tok.` | User token | You, with your own permissions | Local development, scripts you run yourself |

### User tokens (`usr_tok.`)

A user token represents *you*. It resolves your permissions on every request, so it sees exactly what you see in the app — no more.

Get one by logging in with the CLI:

```bash theme={null}
tolmo auth login
```

The token is stored in your profile under `~/.tolmo/`. Read it from there, or set it explicitly with the `TOLMO_API_TOKEN` environment variable.

User tokens are deliberately short-lived:

* They **expire seven days** after they are minted.
* They also expire after **three days of inactivity**, whichever comes first.

Both windows are evaluated against the database clock, so a token cannot be extended by a client with a skewed clock. When a token lapses, run `tolmo auth login` again.

## What a credential can see

Authorization is enforced at the data layer, not only in the route handler, so a credential cannot reach around the API to read data it should not see — including through the SQL and openCypher query endpoints.

Two consequences worth designing around:

* Findings that are still **drafts** are not visible to ordinary callers. You will see published findings, plus ingested ones.
* An `/orgs/{orgSlug}/...` path for any organization other than your own is rejected. Inside your own organization, a resource id you cannot see returns **`404`** — the API will not confirm that it exists elsewhere.

## Revoking a credential

Revoke the user token you are currently authenticated with:

```bash theme={null}
tolmo auth logout
```

Logout attempts server-side revocation and clears the local cache. If revocation fails, the CLI prints a warning; clearing the cache alone does not invalidate the remote token.

API keys are revoked under [API keys](https://app.tolmo.com/settings/api-keys) in **Settings**. Revocation is recorded rather than deleted, so the list stays an audit trail of what was issued and what happened to it.

If you believe a key has leaked, revoke it first and investigate afterwards — revocation takes effect on the next request.

## Choosing between them

> **Use an API key**
>
> The caller is a pipeline, a server, or a scheduled job that must keep running unattended and outlive any one person's account. Create one under [API keys](https://app.tolmo.com/settings/api-keys).

> **Use a user token**
>
> You are exploring the API, writing a script you run yourself, or want every call attributed to you and limited to your own access.


# Clone a repository
Source: https://docs.tolmo.com/api-reference/code/clone-a-repository

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/code/clone
Download a bare git repo archive from storage or a live GitHub PR ref



# Download a repository archive
Source: https://docs.tolmo.com/api-reference/code/download-a-repository-archive

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/code/clone/{owner}/{repo}
Download a bare git repo as a tar archive from S3



# List code repositories
Source: https://docs.tolmo.com/api-reference/code/list-code-repositories

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/code/repositories
List code repositories with clone availability



# List connected services
Source: https://docs.tolmo.com/api-reference/connected-services/list-connected-services

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/connected-services
List connected integrations available for querying via the proxy



# Proxy a raw AWS request
Source: https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-delete

/api-reference/openapi.json delete /api/v1/orgs/{orgSlug}/connected-services/provider/aws/raw-proxy/{*}
Re-sign and forward raw AWS HTTP requests from the CLI local proxy



# Proxy a raw AWS request
Source: https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-get

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/connected-services/provider/aws/raw-proxy/{*}
Re-sign and forward raw AWS HTTP requests from the CLI local proxy



# Proxy a raw AWS request
Source: https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-patch

/api-reference/openapi.json patch /api/v1/orgs/{orgSlug}/connected-services/provider/aws/raw-proxy/{*}
Re-sign and forward raw AWS HTTP requests from the CLI local proxy



# Proxy a raw AWS request
Source: https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-post

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/connected-services/provider/aws/raw-proxy/{*}
Re-sign and forward raw AWS HTTP requests from the CLI local proxy



# Proxy a raw AWS request
Source: https://docs.tolmo.com/api-reference/connected-services/proxy-a-raw-aws-request-put

/api-reference/openapi.json put /api/v1/orgs/{orgSlug}/connected-services/provider/aws/raw-proxy/{*}
Re-sign and forward raw AWS HTTP requests from the CLI local proxy



# Proxy a request to a provider
Source: https://docs.tolmo.com/api-reference/connected-services/proxy-a-request-to-a-provider

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/connected-services/provider/{provider}/proxy
Proxy a read-only request to an external API through a connected integration



# Run an AWS CLI command
Source: https://docs.tolmo.com/api-reference/connected-services/run-an-aws-cli-command

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/connected-services/provider/aws/execute
Execute an AWS CLI command server-side using the org's connected AWS integration



# Run a Cypher query
Source: https://docs.tolmo.com/api-reference/cypher/run-a-cypher-query

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/cypher
Execute an openCypher query (org-scoped, read-only, temporary). Automated and agent callers must send `intent`: one short sentence naming the specific question this query should answer and how the result will guide the next step. It never changes the query or its results; when set, it is attached to the request trace in APM and to the security audit log of rejected queries, so automated traffic has an attributable purpose.



# Create a Datadog monitor
Source: https://docs.tolmo.com/api-reference/datadog-monitors/create-a-datadog-monitor

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/datadog/monitors
Create a Datadog monitor through Tolmo's managed Datadog integration.



# Delete a Datadog monitor
Source: https://docs.tolmo.com/api-reference/datadog-monitors/delete-a-datadog-monitor

/api-reference/openapi.json delete /api/v1/orgs/{orgSlug}/datadog/monitors/{monitorId}
Delete a Tolmo-managed Datadog monitor. This removes the monitor in Datadog itself.



# Get a Datadog monitor
Source: https://docs.tolmo.com/api-reference/datadog-monitors/get-a-datadog-monitor

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/datadog/monitors/{monitorId}
Fetch one Tolmo-managed Datadog monitor by its Datadog monitor id.



# List Datadog monitors
Source: https://docs.tolmo.com/api-reference/datadog-monitors/list-datadog-monitors

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/datadog/monitors
List the Datadog monitors Tolmo manages for this organization. Requests are proxied to Datadog with platform-held credentials, so no Datadog API key is needed.



# Update a Datadog monitor
Source: https://docs.tolmo.com/api-reference/datadog-monitors/update-a-datadog-monitor

/api-reference/openapi.json patch /api/v1/orgs/{orgSlug}/datadog/monitors/{monitorId}
Update the definition of an existing Tolmo-managed Datadog monitor.



# Export the domain inventory
Source: https://docs.tolmo.com/api-reference/domains/export-the-domain-inventory

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/domains/export
Download canonical (primary) domain inventory as CSV or JSON. One row per hostname, same filters as the list (`q`, lifecycle, dns, web, source). Omits Attack Surface / candidates and bookkeeping evidence sources. Ordered by apex then FQDN.



# List apex domains
Source: https://docs.tolmo.com/api-reference/domains/list-apex-domains

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/domains/apexes
List apex domains with an exact organization-wide subdomain total, host counts, and collapsed-row summaries (apex host, probe snapshots, first/last seen) for canonical domain inventory. Ordered by apex ASC. Offset pagination via page + limit.



# List descendant probe aggregates
Source: https://docs.tolmo.com/api-reference/domains/list-descendant-probe-aggregates

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/domains/descendant-probes
Complete probe aggregates for every intermediate parent under one apex (Postgres; not Attack Surface). Same filters as the host list. Not paginated — one row per parent with grouped subdomainProbes (capped) and subdomainCount.



# List domains
Source: https://docs.tolmo.com/api-reference/domains/list-domains

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/domains
List hostnames (Postgres; not Attack Surface). Ordered by apex then FQDN. Optional apexDomain scopes to one apex. Offset pagination via page + limit.



# Tolmo API Error Responses and Status Codes
Source: https://docs.tolmo.com/api-reference/errors

Read the Tolmo API error body, understand what each status code means, and handle retries, precondition failures, and permission errors correctly.

Tolmo signals failure with the HTTP status code. Most API errors return a JSON body describing what went wrong. Some endpoints and provider proxies use a different error shape; check the HTTP status and the endpoint schema.

## Error shape

```json theme={null}
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Finding not found"
}
```

| Field | Type | Description |
| - | - | - |
| `statusCode` | number | The HTTP status code, repeated in the body |
| `error` | string | The status code's reason phrase, for example `Not Found` |
| `message` | string | A human-readable explanation of this specific failure |
| `code` | string | A machine-readable identifier, present on some errors |
| `validation` | array | Present on schema validation failures; one entry per offending field |

Branch on the HTTP response status, and on `code` where an endpoint documents one. Treat `message` as text for a human — it is written to be read, and its wording may change.

## Status codes

| Code | Meaning | What to do |
| - | - | - |
| `400` | The request failed validation — a malformed body, an unknown enum value, or a parameter outside its allowed range | Fix the request. Retrying unchanged will fail again |
| `401` | The token is missing, unrecognized, or expired | Re-authenticate. For a user token, run `tolmo auth login` |
| `403` | The token is valid but lacks permission for this operation, or the `{orgSlug}` in the path is not the token's organization | Check the org slug, or use a token with the right role. Do not retry |
| `404` | The resource does not exist — **or** it exists in an organization your token cannot see | Check the id and the org slug. See below |
| `409` | The request conflicts with the resource's current state, such as an invalid status transition | Re-read the resource and reconcile before retrying |
| `412` | A precondition was not met — a required prior step has not completed | Satisfy the precondition, then retry |
| `503` | A dependency Tolmo relies on is unavailable | Retry with backoff |

### `404` versus `403`

An API key is bound to one organization. Using it against any other `{orgSlug}` is rejected with `403`, regardless of what that slug is — check that the slug in your path is your own.

Inside your own organization, a `404` on a resource id means one of two things, and the API will not tell you which:

* the id is wrong, or
* the resource belongs to another organization.

Check the org slug in your path before assuming the id is bad.

Within an organization you *can* see, `403` also means your role is insufficient for this operation. Creating a finding as a *published* one with an ordinary member token returns `403`; creating it as a draft succeeds.

## Retrying

Retry `503`, and `429` if you receive one, with exponential backoff.

Do not blindly retry `400`, `401`, `403`, or `404` — none of them will succeed on a second identical attempt.

Writes are not automatically idempotent. If a write times out and you cannot tell whether it landed, re-read the resource before sending it again rather than risking a duplicate.

## Validation errors

Request validation runs from the same schemas that generate this reference, so a `400` almost always means the request disagrees with a documented parameter or body schema.

Validation failures carry an extra `validation` array alongside the usual fields — one entry per offending field, so you can report every problem at once instead of fixing them one request at a time:

```json theme={null}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "...",
  "validation": [
    {
      "keyword": "too_big",
      "instancePath": "/limit",
      "schemaPath": "#/limit/too_big",
      "message": "Too big: expected number to be <=100",
      "params": { "origin": "number", "maximum": 100, "inclusive": true }
    }
  ]
}
```

`instancePath` points at the field, `keyword` is the validation rule it broke, and `params` carries that rule's bounds. Check the endpoint's parameter table for each field's type and limits.


# Count findings by saved view
Source: https://docs.tolmo.com/api-reference/external-findings/count-findings-by-saved-view

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/external-findings/views
Return counts for the saved finding views visible to the caller, with the time the counts were computed.



# Get a unified finding
Source: https://docs.tolmo.com/api-reference/external-findings/get-a-unified-finding

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/external-findings/{externalFindingId}
Fetch a Tolmo-authored or third-party finding by its unified finding ID, including its description and assessment history. Returns 404 when the finding is not visible to the caller.



# Import third-party findings
Source: https://docs.tolmo.com/api-reference/external-findings/import-third-party-findings

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/external-findings
Import findings under a provider and stable source name. Reusing the same provider, source, and external ID updates the existing record. Returns the imported finding IDs.



# Create a finding
Source: https://docs.tolmo.com/api-reference/findings/create-a-finding

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/findings
Create a finding. Regular human tokens and purposeless customer automation tokens may create drafts but cannot publish; platform-minted agent-run tokens, verified super-admins, and scoped pentesters may publish. Accepts optional `sourceAgentName` provenance for agent-authored drafts.



# Delete a finding attachment
Source: https://docs.tolmo.com/api-reference/findings/delete-a-finding-attachment

/api-reference/openapi.json delete /api/v1/orgs/{orgSlug}/findings/{findingId}/attachments/{attachmentId}
Permanently delete one attachment. Because it is irreversible, the caller must be the attachment's uploader or an effective super-admin.



# Download a finding attachment
Source: https://docs.tolmo.com/api-reference/findings/download-a-finding-attachment

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings/{findingId}/attachments/{attachmentId}/content
Stream one attachment's bytes back through the authenticated route — attachments are served from a private bucket and never exposed as object URLs. Responses are forced to attachment disposition with `no-store` and `nosniff`.



# Get a finding
Source: https://docs.tolmo.com/api-reference/findings/get-a-finding

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings/{findingId}
Fetch a single finding by id. Internal triage columns are never serialized on this org-facing surface. Returns 404 rather than 403 for a finding in another organization, and for a draft the caller may not see.



# List a finding's attachments
Source: https://docs.tolmo.com/api-reference/findings/list-a-findings-attachments

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings/{findingId}/attachments
List the evidence files attached to a finding. Human tokens only; machine org tokens are rejected.



# List a finding's sources
Source: https://docs.tolmo.com/api-reference/findings/list-a-findings-sources

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings/{findingId}/sources
Return the evidence sources attached to a finding — the scans, resources, and detections that produced or corroborated it.



# List a finding's status history
Source: https://docs.tolmo.com/api-reference/findings/list-a-findings-status-history

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings/{findingId}/status-history
Return the ordered audit trail of status transitions for one finding, including who made each change and when.



# List finding filter facets
Source: https://docs.tolmo.com/api-reference/findings/list-finding-filter-facets

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings/facets
Return the available filter values (status, severity, and related dimensions) with their counts for the current query, for building filter UIs without a second full scan. Applies the same visibility rules as GET /findings/catalog.



# List findings
Source: https://docs.tolmo.com/api-reference/findings/list-findings

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings
List every finding in the organization — Tolmo-authored and third-party scanner rows — from the unified findings read. Filter with origin=tolmo for Tolmo-authored rows only. The lean catalog (source/agent facets, idsOnly) lives at GET /findings/catalog.



# List Tolmo-authored findings (catalog)
Source: https://docs.tolmo.com/api-reference/findings/list-tolmo-authored-findings-catalog

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings/catalog
List the organization's Tolmo-authored findings, newest first, with the shared lean paginated contract. Regular callers see published findings only; effective super-admins may additionally read all drafts, and a scoped pentester may list drafts they authored. Scanner-origin rows are excluded. Prefer GET /findings for the unified org list.



# List Tolmo catalog filter facets
Source: https://docs.tolmo.com/api-reference/findings/list-tolmo-catalog-filter-facets

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/findings/catalog/facets
Return the available filter values (status, severity, and related dimensions) with their counts for the current query, for building filter UIs without a second full scan. Applies the same visibility rules as GET /findings/catalog.



# Update a finding's status
Source: https://docs.tolmo.com/api-reference/findings/update-a-findings-status

/api-reference/openapi.json patch /api/v1/orgs/{orgSlug}/findings/{findingId}/status
Transition a finding between `open`, `in_review`, `acknowledged`, `closed`, `false_positive`, and `canceled`. The transition is recorded in the finding's status history with its actor, so the change is auditable. On a scanner row (GitHub, Wiz, and the rest) this writes `provider_status` and does not call the provider; `canceled` is refused. A later scan that still reports the alert overwrites that provider status.



# Upload a finding attachment
Source: https://docs.tolmo.com/api-reference/findings/upload-a-finding-attachment

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/findings/{findingId}/attachments
Upload one evidence file for a finding as `application/octet-stream`, capped at 250 MiB. File name and content type travel in the `X-Attachment-File-Name` and `X-Attachment-Content-Type` headers, with an optional URI-encoded `X-Attachment-Title`. A `report_exhibit` video must send `X-Attachment-Exploit-Id`, the exploit it records. A film with no exploit is rejected. Human tokens only.



# Connect an integration
Source: https://docs.tolmo.com/api-reference/integrations/connect-an-integration

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/integrations/{provider}
Create/update an integration



# List integration providers
Source: https://docs.tolmo.com/api-reference/integrations/list-integration-providers

/api-reference/openapi.json get /api/v1/integration-providers
List publicly available integration providers and their field specs. A client-supplied `orgId` is accepted for compatibility and ignored: org-restricted specs are never unlocked by a query parameter.



# List integrations
Source: https://docs.tolmo.com/api-reference/integrations/list-integrations

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/integrations
List integrations



# Tolmo REST API Reference for Security Automation
Source: https://docs.tolmo.com/api-reference/introduction

Call the Tolmo API directly over HTTPS to read findings, query your infrastructure graph, manage integrations, and drive security workflows from your own tooling.

The Tolmo API is a REST API over HTTPS. Use the published endpoints to integrate Tolmo with your own tools. The [CLI](/introduction) also provides local conveniences such as report parsing, artifact downloads, and installation.

Use it when you want to pull findings into an internal dashboard, gate a deploy on your organization's security posture, sync the infrastructure graph into a warehouse, or drive Tolmo from a language the CLI doesn't cover.

> [!TIP]
>
> If you just want results in a terminal or a pipeline, reach for the CLI first — it handles authentication, org context and command-specific pagination for you. Drop to the API when you are building a service.

## Base URL

All requests go to:

```text theme={null}
https://api.tolmo.com
```

Every endpoint lives under the `/api/v1` prefix. Requests must use HTTPS.

## Authentication

Every endpoint requires a bearer token:

```bash theme={null}
curl https://api.tolmo.com/api/v1/orgs/acme/findings \
  -H "Authorization: Bearer $TOLMO_API_TOKEN"
```

See [Authentication](/api-reference/authentication) for how to get an [API key](https://app.tolmo.com/settings/api-keys).

## Organization scoping

Most endpoints are scoped to a single organization, identified by its slug in the path:

```text theme={null}
/api/v1/orgs/{orgSlug}/findings
```

Find your slug with `tolmo org list`, or read it from your organization settings in the Tolmo app.

An API key is limited to its organization. A user token can access the organizations you belong to. Authorization also applies to SQL and Cypher queries. A resource ID outside your access returns `404`.

## Your first request

List your organization's open critical findings — substitute your own slug for `acme`:

```bash theme={null}
curl -G https://api.tolmo.com/api/v1/orgs/acme/findings \
  -H "Authorization: Bearer $TOLMO_API_TOKEN" \
  -d status=open \
  -d severity=critical
```

## What you can do

> **Findings**
>
> List, filter, create, and triage security findings, with their full status history and evidence attachments.

> **Query your graph**
>
> Run read-only SQL and openCypher against your organization's infrastructure graph.

> **Inventory**
>
> Read the canonical domain inventory, code repositories, scan runs, and the resource graph.

> **Integrations**
>
> Connect and inspect providers, and proxy read-only calls to them using Tolmo-held credentials.

## Pagination

Pagination depends on the endpoint:

| Endpoint | Parameters | Response |
| - | - | - |
| Unified findings | `limit`, `cursor` | `items` and `nextCursor` |
| Domains and apex domains | `page`, `limit` | `items`, `total`, and `totalPages` |
| Threat model versions | `limit`, `offset` | Array of version summaries |
| Secret findings | `limit`, `offset` | Array of detections |

For findings, pass `nextCursor` as the next request's `cursor` until it is null. Check each endpoint's schema for defaults and bounds.

## Content types

Send `Content-Type: application/json` on requests with a body. Two endpoints deviate deliberately: finding attachment uploads take `application/octet-stream` with metadata in headers, and attachment and screenshot downloads return binary streams.

## Errors

Most failures return a JSON body with `statusCode`, `error`, and `message`; some endpoints and provider proxies use different shapes. See [Errors](/api-reference/errors) for the full shape and the status codes each endpoint uses.

## Stability

This reference is generated from the server's own route definitions, so it reflects exactly what the API accepts and returns.

Use the documented `/api/v1` routes for integrations. Other route namespaces are not part of this public reference.


# Get a resource subgraph
Source: https://docs.tolmo.com/api-reference/resource-graph/get-a-resource-subgraph

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/resource-graph/subgraph
Get a subgraph filtered by provider/service/resourceType



# List scan runs
Source: https://docs.tolmo.com/api-reference/scans/list-scan-runs

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/scans
List scan runs for the org



# Get a screenshot
Source: https://docs.tolmo.com/api-reference/screenshots/get-a-screenshot

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/screenshots/{id}
Stream a single screenshot PNG. Bucket is private; this endpoint proxies the GetObject through the backend so org isolation can be enforced.



# List screenshots
Source: https://docs.tolmo.com/api-reference/screenshots/list-screenshots

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/screenshots
List URL screenshots captured for the org by the daily Cloudflare browser-rendering pipeline.



# List secret findings
Source: https://docs.tolmo.com/api-reference/secrets/list-secret-findings

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/secret-findings
List leaked-credential findings detected across the organization's connected source repositories, with their current triage state.



# Run a SQL query
Source: https://docs.tolmo.com/api-reference/sql/run-a-sql-query

/api-reference/openapi.json post /api/v1/orgs/{orgSlug}/sql
Execute a read-only SQL query with RLS org isolation



# Get a threat model version
Source: https://docs.tolmo.com/api-reference/threat-models/get-a-threat-model-version

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/threat-models/{version}
Fetch one specific version of the organization's threat model, in full — the stable way to pin a report to a known revision.



# Get the latest threat model
Source: https://docs.tolmo.com/api-reference/threat-models/get-the-latest-threat-model

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/threat-models/latest
Fetch the most recent threat model generated for the organization, in full.



# List threat model versions
Source: https://docs.tolmo.com/api-reference/threat-models/list-threat-model-versions

/api-reference/openapi.json get /api/v1/orgs/{orgSlug}/threat-models
List the organization's generated threat models, newest first. Each entry is a summary; fetch a version to get the full document.



# Authenticate the Tolmo CLI
Source: https://docs.tolmo.com/authentication

Sign in with a browser for interactive use, or use an organization API key for automation.

Use browser login for interactive work. For CI and services, create an API key under **Settings → API keys** and pass it through `TOLMO_API_TOKEN`.

## Sign in

```bash theme={null}
tolmo auth login
tolmo auth status
```

Login opens your browser and asks you to select an organization if you belong to more than one. It saves a user token (`usr_tok.*`) and the selected organization in the active profile. The default profile is `default`.

To print the login URL without opening a browser:

```bash theme={null}
tolmo auth login --no-browser
```

You still need to complete the browser flow. Use an API key for unattended jobs.

`tolmo auth status` shows the effective profile, API URL, organization, and the source of each setting. It also shows the credential type and a shortened token prefix.

## Select an organization

```bash theme={null}
tolmo org list
tolmo org switch acme
tolmo --org other-org findings list
```

`org switch` saves your choice in the active profile. `--org` applies to one invocation. A user token can access the organizations you belong to without a separate login for each one.

## Use a named profile

```bash theme={null}
tolmo auth login --profile work --api-url https://api.tolmo.com
tolmo --profile work findings list
```

Set `TOLMO_PROFILE=work` to select that profile for your shell. See [Profiles](/configuration/profiles) for credential storage and logout behavior.

## Use an API key

Create a key in [**Settings → API keys**](https://app.tolmo.com/settings/api-keys). Store it in your environment or CI secret store:

```bash theme={null}
export TOLMO_API_TOKEN="your-api-key"
export TOLMO_ORG_SLUG="acme"
tolmo findings list --status open --json
```

When `TOLMO_API_TOKEN` is set, the CLI skips profile configuration and cached credentials. Set the organization with `TOLMO_ORG_SLUG` or `--org`. The API URL comes from `TOLMO_API_URL`, or defaults to `https://api.tolmo.com`.

API keys are scoped to one organization. `--org` cannot expand a key's access. User-specific operations such as listing your memberships and managing evidence attachments require a user token.

Unset `TOLMO_API_TOKEN` before running `tolmo auth login`. `tolmo org switch` is unavailable while this variable is set; change `TOLMO_ORG_SLUG` instead.

## Sign out

```bash theme={null}
tolmo auth logout
```

Logout attempts to revoke the cached user token and clears the local credential even if server revocation fails. In that case, the CLI prints a warning. The profile's API URL and organization remain saved.

Logout does not revoke an API key supplied through the environment. Revoke API keys in **Settings → API keys**.

User tokens expire after seven days or three days of inactivity. Run `tolmo auth login` again when your session expires. See [API authentication](/api-reference/authentication) for credential permissions.


# Changelog
Source: https://docs.tolmo.com/changelog

New features and improvements in Tolmo, newest first.

**Week of September 28, 2026**

* [Red Team Agent](/agents/red-team-agent) and Blue Agent are available to every organization.
* The findings table shows an **Exploitability** column: **Validated exploit**, **Not validated**, or **Resolved**.
* Mission Control lists new findings under a **New Finding** category.
* HackerOne findings show the report's attachments inline.

**Week of September 21, 2026**

* A **Triggers** tab in **Agent Settings** lets you schedule, pause, and delete agent runs.
* Change a published finding's severity from the dropdown next to its status.
* Set your timezone under **Settings** → **Preferences**. Your daily digest arrives at 8:00 a.m. in that timezone.
* Get a Slack message when an agent starts a live test. Turn on **When an agent starts** in **Agent Settings**.
* GitLab's integration page lists your projects.


# Inspect discovered applications
Source: https://docs.tolmo.com/commands/apps

List applications from your repositories and inspect their HTTP endpoints and linked hostnames.

Use `tolmo apps` to inspect applications discovered in your organization's repositories. The commands read the infrastructure graph.

## List applications

```bash theme={null}
tolmo apps list
tolmo apps list --json
```

The table shows each application's name, type, system, endpoint count, and linked hostnames. Applications can appear before hostnames have been linked.

## Inspect one application

Pass an exact application name or resource key:

```bash theme={null}
tolmo apps get payments-api
tolmo apps get payments-api --json
```

The detail view lists HTTP methods and paths, linked hostnames, and URLs assembled from those values. Use the resource key to distinguish applications with the same name. JSON output is an array of matching graph rows.

Linked hostnames reflect the graph's recorded deployment relationships. A displayed URL does not confirm that an endpoint is currently reachable.

See [Repositories](/commands/code) to inspect the source and [SQL and Cypher](/commands/sql-cypher) to query the graph directly.


# Browse and Clone Repositories Connected to Your Organization
Source: https://docs.tolmo.com/commands/code

Use tolmo code to list repositories in your organization and clone them from GitHub or GitLab. Supports multiple input formats and bulk cloning.

The `tolmo code` command lets you browse and clone repositories connected to your organization. Tolmo resolves access credentials on the backend, so you can clone repositories from GitHub or GitLab without managing tokens locally. All subcommands accept the global `--org` flag to target a specific organization.

## List repositories

Use `tolmo code list` to see every repository Tolmo knows about for your organization.

```bash theme={null}
# Show all repositories in a table
tolmo code list

# Show only repositories available to clone
tolmo code list --cloneable

# Return results as JSON
tolmo code list --json
```

The `--cloneable` flag filters to repositories that have storage artifacts ready for cloning. Use it before running a bulk clone to preview what will be fetched.

## Clone a repository

Use `tolmo code clone` to clone a single repository. You can pass the repository in any of the following formats — Tolmo normalizes them automatically:

```bash theme={null}
# Short org/repo notation
tolmo code clone org/repo

# With explicit host
tolmo code clone github.com/org/repo

# Full URL (Tolmo extracts the repo path from the URL)
tolmo code clone https://github.com/superset-sh/superset/tree/main/apps/relay

# Full URL with a custom local target directory
tolmo code clone https://github.com/superset-sh/superset ./relay

# GitLab with nested subgroups
tolmo code clone https://gitlab.com/group/subgroup/repo

# GitLab short notation with explicit provider flag
tolmo code clone group/subgroup/repo --provider gitlab
```

Tolmo defaults to GitHub. Pass `--provider gitlab` when the short `group/repo` notation is ambiguous or when the host is not included in the URL.

## Select a ref and working tree

A repository URL containing `/tree/<branch>/<directory>` identifies the repository only. Use `--ref` to select the branch, tag, or commit, and repeat `--sparse` to limit the checked-out files:

```bash theme={null}
tolmo code clone acme/payments ./payments --ref main --sparse 'services/api/**' --sparse 'go.mod'
```

Sparse patterns use Git's non-cone, gitignore-style syntax. They restrict the working tree; the repository archive is still downloaded. You need `git` installed locally.

## Clone all repositories

Use `tolmo code clone all` to clone every repository in your organization that is available for cloning. Tolmo prompts for confirmation before starting.

```bash theme={null}
# Clone all cloneable repos (prompts for confirmation)
tolmo code clone all

# Skip the confirmation prompt
tolmo code clone all ./repositories --yes
```

> [!WARNING]
>
> `tolmo code clone all` may clone a large number of repositories, some of which can be several gigabytes. Check `tolmo code list --cloneable` first to understand the scope, and make sure you have sufficient disk space before proceeding.


# Review and triage security findings
Source: https://docs.tolmo.com/commands/findings

Filter Tolmo and third-party findings, import scanner reports, create drafts, and record status decisions with the Tolmo CLI.

Use `tolmo findings` to review Tolmo-authored findings and findings from connected scanners in one list. All subcommands accept `--org` and `--profile`. Use `--json` for structured output.

## List and filter findings

```bash theme={null}
tolmo findings list
tolmo findings list --status open --severity critical
tolmo findings list --origin wiz --search payments --json
tolmo findings list --include-info --json
```

The CLI follows the API's pagination and returns all matching findings. JSON output is an array. Ordinary callers see published Tolmo findings and ingested scanner findings. Informational findings and findings without a severity are excluded unless you pass `--include-info`.

| Flag | Description |
| - | - |
| `--status` | Comma-separated statuses: `open`, `in_review`, `closed`, `acknowledged`, `false_positive` |
| `--severity` | `critical`, `high`, `medium`, `low`, or `info` |
| `--origin` | `tolmo` or a provider name, such as `wiz` |
| `--search` | Search titles, external IDs, rules, and resource keys |
| `--query` | A findings query expression |
| `--state` | Comma-separated lifecycle states |
| `--retest` | Comma-separated retest values |
| `--rule` | Exact provider rule |
| `--provider-status` | Comma-separated provider statuses |
| `--verdict` | `tolmo` or `none` |
| `--scope` | `all` (default) or `open` |
| `--include-info` | Include informational findings and findings without a severity |

Use the [filter facets endpoint](/api-reference/findings/list-finding-filter-facets) to discover filter values for your organization.

## View a finding

```bash theme={null}
tolmo findings get <finding-id>
tolmo findings get <finding-id> --json
```

The detail view works for Tolmo-authored and scanner findings. You can use a full UUID or a unique ID prefix from the list. Use a longer prefix if the CLI reports multiple matches.

## Create a draft

API keys and ordinary user tokens can create draft findings. They cannot publish findings.

```bash theme={null}
tolmo findings create --title "Overpermissive storage access" --severity high --resource-name customer-exports --description-file ./finding.md
```

`--title` and `--severity` are required. When you use a user token, also supply `--resource-name` to identify the affected resource. The default visibility is `draft`, and the default status is `open`. Use either `--description` for inline Markdown or `--description-file` for a file. Pass `--description-file -` to read stdin.

Save the ID returned by creation. Drafts are not included in the ordinary customer findings list.

## Import a scanner report

Use `upload` to import a Markdown security report as third-party findings:

```bash theme={null}
tolmo findings upload ./security-report.md --provider code-security --source payments-review --json
```

The report must contain a `## Unified finding details` section and findings with `### USR-<number>: <title>` headings:

```markdown security-report.md theme={null}
# Security review

## Unified finding details

### USR-0001: Storage permissions need review

- **Highest reported severity:** `HIGH`

The storage policy grants broader access than this service requires.

**Recommended remediation:** Restrict the policy to the required resources.
```

The CLI parses findings locally and uploads them in batches.

| Flag | Description |
| - | - |
| `--provider` | Required producer name. Use lowercase letters, digits, `.`, `_`, or `-`; start with a letter or digit |
| `--source` | Stable import source. Defaults to the report filename; required for stdin |
| `--status` | Provider status assigned to imported findings; defaults to `open` |
| `--kind` | Finding kind; defaults to `code_security` |

Keep the provider, source, and finding identifiers stable when you import an updated report. Matching records are updated instead of duplicated.

## Change status

```bash theme={null}
tolmo findings status <finding-id> in_review --justification "The fix is under review" --proof-url https://github.com/acme/payments/pull/42
tolmo findings status <finding-id> closed --justification-file ./resolution.md
tolmo findings status <finding-id> false_positive --justification "The affected configuration is not used"
```

The supported statuses are `open`, `in_review`, `closed`, `acknowledged`, and `false_positive`. Use the underscore in `false_positive`.

You can attach a justification to `in_review`, `closed`, or `false_positive`. Use either `--justification` or `--justification-file`; `-` reads stdin. `--proof-url` is available only for `in_review` and requires an HTTP or HTTPS URL.

For scanner findings, status changes affect Tolmo's record. They do not update the source provider. A later scan can replace the local status.

## Review status history

```bash theme={null}
tolmo findings history <finding-id>
tolmo findings history <finding-id> --json
```

## Manage evidence attachments

Sign in with `tolmo auth login` to manage attachments. These operations require a user token; organization API keys are not accepted.

```bash theme={null}
tolmo findings attachments list <finding-id>
tolmo findings attachments upload <finding-id> ./evidence.pdf --title "Review evidence"
tolmo findings attachments download <finding-id> <attachment-id> --output ./evidence.pdf
tolmo findings attachments delete <finding-id> <attachment-id> --yes
```

Uploads support files up to 250 MiB. Downloads use the stored filename unless you pass `--output`. Pass `--force` to overwrite an existing local file. Attachment deletion is permanent and requires `--yes`.


# Query Connected Services Through Tolmo's Secure Proxy
Source: https://docs.tolmo.com/commands/query

Proxy REST, GraphQL, and CLI requests to GitHub, AWS, Linear, Sentry, and Datadog through Tolmo. Credentials are resolved server-side and never exposed.

The `tolmo query` command proxies requests to your organization's connected services. Credentials are resolved on the backend — they never leave the server, and your local machine never sees a token or secret key. Use `tolmo query list` to discover which connected providers support proxy queries. All subcommands accept the global `--org` flag to target a specific organization.

## Discover available services

Before querying a service, use `tolmo query list` to see which providers are connected for your organization.

```bash theme={null}
# List connected services for the active org
tolmo query list

# List connected services for a specific org
tolmo query list --org superset
```

Providers are discovered dynamically from the backend. New backend adapters become available without any CLI update on your end.

## GitHub (REST)

Send REST requests directly to the GitHub API. Tolmo injects the org's GitHub App credentials on the backend.

```bash theme={null}
# List pull requests for a repository
tolmo query github '/repos/owner/repo/pulls?state=all'

# Search issues and PRs across an org
tolmo query github '/search/issues?q=type:pr+org:myorg'
```

## GitHub CLI passthrough

`tolmo query -- gh ...` runs your locally installed `gh` CLI with a short-lived token injected by the backend via a Unix socket proxy. This supports `gh` output features — including pagination, `--jq`, `--template`, and `gh api` — backed by the org's GitHub App credentials rather than your personal token.

> [!WARNING]
>
> The `--` separator between `tolmo query` and `gh` is **mandatory**. Without it, the Cobra argument parser strips unknown flags (like `--repo`, `--limit`, or `--state`) before they ever reach `gh`, causing unexpected errors or silent failures.

```bash theme={null}
# List repositories in an org
tolmo query -- gh repo list myorg --limit 50

# Search PRs with a date range using full gh api syntax
tolmo query -- gh api --method GET search/issues -f "q=type:pr org:myorg created:2026-01-01..2026-03-01" -f per_page=100

# List open issues with JSON output
tolmo query -- gh issue list --repo myorg/myrepo --state open --json number,title

# Use a different org's GitHub credentials
tolmo query --org superset -- gh api '/repos/superset-sh/superset/pulls?state=all&per_page=5'
```

## AWS CLI passthrough

`tolmo query -- aws ...` sends AWS CLI arguments to the backend, which parses and executes the supported request with your integration credentials. You do not need a local AWS CLI installation. Provider permissions and proxy restrictions still apply.

> [!WARNING]
>
> The `--` separator is **mandatory** here too. Without it, flags like `--region` and `--output` are stripped before reaching the AWS CLI.

```bash theme={null}
# Describe EC2 instances
tolmo query -- aws ec2 describe-instances

# List S3 buckets
tolmo query -- aws s3 ls

# List IAM roles in a specific region
tolmo query -- aws iam list-roles --region us-east-1

# Query a specific org's AWS environment
tolmo query --org klarify -- aws ec2 describe-security-groups --region ca-central-1
```

## Linear (GraphQL)

Send GraphQL queries to Linear. Pass the query inline as a string or load it from a file.

```bash theme={null}
# Inline GraphQL query
tolmo query linear '{ viewer { id name } }'

# Load a query from a file
tolmo query linear --file query.graphql
```

## Sentry (REST)

Send REST requests to the Sentry API. The path is appended to the Sentry base URL.

```bash theme={null}
# List issues for an organization
tolmo query sentry /api/0/organizations/acme/issues/
```

## Datadog (REST)

Send REST requests to the Datadog API. The path is appended to the Datadog base URL.

```bash theme={null}
# List all monitors
tolmo query datadog /api/v1/monitor
```

## Multiple integrations

When your organization has more than one integration for the same provider (for example, two separate GitHub App installations), pass `--integration <id>` to tell Tolmo which credentials to use. Integration IDs are shown in the output of `tolmo query list`.

```bash theme={null}
# Disambiguate when multiple GitHub integrations exist
tolmo query --integration <id> -- gh repo list

# Disambiguate a direct REST call
tolmo query --integration <id> github /repos/owner/repo/pulls
```

## Select an AWS account

When multiple AWS integrations are connected, select one by integration ID or account ID:

```bash theme={null}
tolmo query --account 123456789012 -- aws ec2 describe-instances --region us-east-1
```

## Fly.io CLI passthrough

Use `fly` or `flyctl` after the required separator. The CLI runs locally and routes supported requests through Tolmo's proxy:

```bash theme={null}
tolmo query -- fly apps list --json
```

## GraphQL variables

Pass repeatable `--var key=value` arguments with `--file`. Values are parsed as JSON when possible. Quote a JSON-looking value as a JSON string when you need to preserve it as text:

```bash theme={null}
tolmo query linear --file query.graphql --var 'limit=10' --var 'label="123"'
```


# Run SQL and Cypher Queries Against Your Infrastructure
Source: https://docs.tolmo.com/commands/sql-cypher

Run SQL queries against your org's relational data and Cypher queries against the infrastructure graph. Both commands support --json for scripting.

Tolmo lets you query two data stores — a relational database (via SQL) and a graph database (via Cypher) — directly from the command line. Use SQL for structured, tabular data about your organization and Cypher for traversing infrastructure relationships in the graph. Both commands support `--json` for machine-readable output and accept the global `--org` flag to target a specific organization.

## SQL queries

The `tolmo sql` command executes a SQL query against your organization's relational database and prints results as a formatted table by default.

```bash theme={null}
# Return a scalar value to verify connectivity
tolmo sql "SELECT 1"

# Machine-readable output for scripting
tolmo sql --json "SELECT 1"
```

Pass `--json` to receive raw JSON — useful when piping output to `jq` or another tool.

### Query findings at a past time

```bash theme={null}
tolmo sql --as-of 2026-09-01 "SELECT id, title, severity, status FROM findings LIMIT 20"
```

`--as-of` accepts a date or timestamp. Values without a timezone use UTC. It reconstructs findings at that instant; other tables remain current. See [Time machine](/guides/time-machine).

## Cypher (graph) queries

The `tolmo cypher` command executes a Cypher query against the infrastructure graph database. The graph represents your cloud environment as a network of nodes (resources) and edges (relationships between them), giving you a powerful way to understand how infrastructure components connect.

```bash theme={null}
# Count nodes by label
tolmo cypher "MATCH (n) RETURN labels(n), count(*)"

# Return a sample of raw nodes as JSON
tolmo cypher --json "MATCH (n) RETURN n LIMIT 5"
```

### Record why you're running a query

Pass `--intent` with one sentence stating the goal the query serves. Tolmo attaches it to the request trace in APM and to the security audit log of rejected queries, so a burst of automated queries has an attributable purpose. It never changes the query or its results.

```bash theme={null}
tolmo cypher --intent "triaging exposed EC2 with IAM roles" "MATCH (i:Exposed {resourceType: 'EC2Instance'})-[h:GRAPH_EDGE {type:'HAS_ROLE'}]->(r:GraphNode) RETURN i.resourceKey, r.resourceKey"
```

> [!NOTE]
>
> Agents and scripts must set `--intent` on every query. Skip it only for a one-off query you type yourself. When you call the [Cypher endpoint](/api-reference/cypher/run-a-cypher-query) directly, send the same text in the `intent` field of the request body.

## Graph data model

Every resource in the infrastructure graph is stored as a **`GraphNode`**, and every relationship between resources is stored as a **`GRAPH_EDGE`**.

| Element | Key properties | Description |
| - | - | - |
| `GraphNode` | `resourceType`, `resourceKey` | Represents a single infrastructure resource (e.g. an S3 bucket, an IAM role, a GitHub repository). |
| `GRAPH_EDGE` | `type` | A directed relationship between two nodes (e.g. `HAS_ROLE`, `OWNS`, `CONNECTS_TO`). |

Both nodes and edges carry **temporal tracking fields**:

| Field | Type | Description |
| - | - | - |
| `firstSeenAt` | epoch milliseconds | When the crawler first discovered this resource or relationship. |
| `lastSeenAt` | epoch milliseconds | The most recent time the crawler confirmed it still exists. |

You can use these fields to write time-aware queries:

```bash theme={null}
# Resources added in the last 7 days
tolmo cypher "MATCH (n:GraphNode) WHERE n.firstSeenAt >= (timestamp() - 7*24*60*60*1000) RETURN n.resourceType, n.resourceKey ORDER BY n.firstSeenAt DESC"

# Stale resources not seen in the last 48 hours
tolmo cypher "MATCH (n:GraphNode) WHERE n.lastSeenAt < (timestamp() - 48*60*60*1000) RETURN n.resourceType, n.resourceKey LIMIT 50"

# New relationships discovered in the last 24 hours
tolmo cypher "MATCH ()-[r:GRAPH_EDGE]->() WHERE r.firstSeenAt >= (timestamp() - 24*60*60*1000) RETURN r.type, count(r) AS cnt ORDER BY cnt DESC"
```

## Output formats

Both `sql` and `cypher` support two output modes:

| Mode | Flag | Description |
| - | - | - |
| Table | *(default)* | Human-readable, column-aligned output. Best for interactive use. |
| JSON | `--json` | JSON object containing `rows`, `fields`, and `metadata`. Best for scripting and automation. |

> [!TIP]
>
> Always pass `--json` when parsing output programmatically. Table formatting can vary across CLI versions, and JSON gives you structured fields to process with tools like `jq`: `tolmo sql --json "SELECT 1" | jq '.rows[]'`.


# Configure the CLI with environment variables
Source: https://docs.tolmo.com/configuration/environment-variables

Set API credentials, organization context, profiles, and installer options for the Tolmo CLI.

Use environment variables to configure Tolmo in your shell or CI environment.

| Variable | Behavior |
| - | - |
| `TOLMO_API_TOKEN` | API key or user token. When set, bypasses profile configuration and cached credentials |
| `TOLMO_ORG_SLUG` | Organization slug. Overrides the saved organization; required for organization commands with `TOLMO_API_TOKEN` unless you pass `--org` |
| `TOLMO_API_URL` | API base URL. Overrides the profile URL; defaults to `https://api.tolmo.com` without a profile |
| `TOLMO_PROFILE` | Profile name used when `--profile` is absent; defaults to `default` |
| `TOLMO_APP_URL` | Base URL for links the CLI prints into the Tolmo app; otherwise inferred from the API URL |
| `TOLMO_DISABLE_UPDATE_CHECK` | Any non-empty value disables update checks; checks are also skipped when `CI=true` |
| `TOLMO_DISABLE_SKILL_PROMPT` | Any non-empty value suppresses the agent skill installation prompt |
| `TOLMO_INSTALL_DIR` | Installer-only override for the directory containing the CLI binary |
| `TOLMO_SYSTEM_BIN_DIR` | Installer-only override for the system fallback directory; defaults to `/usr/local/bin` |

## Configuration precedence

| Setting | Resolution order, highest priority first |
| - | - |
| Profile | `--profile`, `TOLMO_PROFILE`, `default` |
| Organization | `--org`, `TOLMO_ORG_SLUG`, profile organization |
| API URL with a profile | `TOLMO_API_URL`, profile URL, production URL |
| API URL with `TOLMO_API_TOKEN` | `TOLMO_API_URL`, production URL |

`TOLMO_API_TOKEN` bypasses the entire profile. A profile's custom API URL and organization do not apply in this mode.

At login, `--api-url` takes precedence over `TOLMO_API_URL` and an existing profile URL. It is a login option, not a global flag. Cached user credentials are bound to the API origin that issued them. Sign in to a separate profile when you change environments.

Run `tolmo auth status` to see each effective value and its source.

## CI example

Inject your API key from your CI provider's secret store:

```bash theme={null}
export TOLMO_API_TOKEN="your-api-key"
export TOLMO_ORG_SLUG="acme"
tolmo findings list --status open --severity critical --json
```

See [CI/CD](/guides/ci-cd) for complete pipeline examples.

## Installer example

Set the install directory on the shell that runs the installer:

```bash theme={null}
curl -fsSL https://tolmo.com/install.sh | TOLMO_INSTALL_DIR="$HOME/.local/bin" sh
export PATH="$HOME/.local/bin:$PATH"
```


# Global flags and JSON output
Source: https://docs.tolmo.com/configuration/global-flags

Select an organization or profile for one invocation and understand command-specific JSON output.

Tolmo exposes two persistent configuration flags:

| Flag | Description |
| - | - |
| `--org <slug>` | Override the organization for one command |
| `--profile <name>` | Select a named profile for one command |

```bash theme={null}
tolmo --org acme findings list
tolmo findings list --org acme
tolmo --profile work sql "SELECT 1"
```

Flags override the corresponding environment variables and stored profile settings. They do not grant access to other organizations.

## JSON output

`--json` belongs to individual commands or command groups. Put it after the command or group that declares it:

```bash theme={null}
tolmo findings list --json
tolmo sql --json "SELECT 1"
```

JSON shapes depend on the command:

| Command | JSON shape |
| - | - |
| `findings list` | Array of all matching findings |
| `sql`, `cypher` | Object with `rows`, `fields`, and `metadata` |
| `domains list` | Page object with `items` and pagination fields |
| `apps list`, `apps get` | Array of graph rows |

```bash theme={null}
tolmo findings list --status open --json | jq '.[].title'
tolmo sql --json "SELECT 1 AS value" | jq '.rows[]'
```

Use `tolmo <command> --help` to check the flags supported by your installed version. `--api-url` is an `auth login` option, not a global flag.


# Manage named profiles
Source: https://docs.tolmo.com/configuration/profiles

Store separate CLI sessions and API environments, select the active profile, and switch organization context.

A profile stores an API URL and a default organization. Browser login caches a user token for that profile. One user token can access your memberships across organizations; you do not need a separate profile for every organization.

## Create a profile

Provide an API URL when you create a non-default profile:

```bash theme={null}
tolmo auth login --profile work --api-url https://api.tolmo.com
```

Existing profiles reuse their saved URL unless you override it. For a different Tolmo environment, sign in to a separate profile using that environment's API URL. Cached user tokens are bound to the issuing API origin.

## Select a profile

```bash theme={null}
tolmo --profile work findings list
export TOLMO_PROFILE=work
tolmo auth status
```

The resolution order is `--profile`, then `TOLMO_PROFILE`, then `default`. `auth status` reports the effective values and their sources.

## Switch organizations

```bash theme={null}
tolmo org list --profile work
tolmo org switch acme --profile work
tolmo --profile work --org other-org findings list
```

`org switch` saves the organization. `--org` overrides it for one command. `TOLMO_ORG_SLUG` also overrides the saved value.

## Credential storage

Profile settings live in `~/.tolmo/config`. Cached user tokens live under `~/.tolmo/cache/sso/`.

Organization API keys are supplied through `TOLMO_API_TOKEN`, not stored in profiles. When that variable is set, the CLI bypasses profile settings and cached credentials. See [Environment variables](/configuration/environment-variables).

## Sign out of a profile

```bash theme={null}
tolmo auth logout --profile work
```

Logout attempts server-side revocation and clears the cached user credential. It retains the profile's API URL and organization. Without `--profile`, it uses `TOLMO_PROFILE` or `default`, just like other commands.


# Browse the domain inventory
Source: https://docs.tolmo.com/features/domains

List apex domains and hosts with discovery, lifecycle, DNS, and web status filters.

Use `tolmo domains list` to inspect your organization's canonical domain inventory. By default, it lists apex domains with host counts and probe summaries.

```bash theme={null}
tolmo domains list
tolmo domains list --q api --lifecycle current
tolmo domains list --apex example.com --page 1 --limit 50 --json
```

Pass `--apex` to list individual hosts under one apex domain. JSON output includes `items`, `page`, `limit`, `total`, and `totalPages`.

## Filters and pagination

| Flag | Values or behavior |
| - | - |
| `--q` | FQDN or apex substring |
| `--apex` | List hosts under this apex instead of apex summaries |
| `--lifecycle` | `current`, `stale`, or `historical` |
| `--dns` | `resolved`, `unresolved`, `error`, or `not_checked` |
| `--web` | `reachable`, `unreachable`, `blocked`, or `not_checked` |
| `--source` | Discovery source, such as `cert_spotter` |
| `--page` | One-based page number; defaults to `1` |
| `--limit` | Page size from `1` to `100`; defaults to `50` |

Each command returns one page. Increase `--page` to read more results. The [domain export endpoint](/api-reference/domains/export-the-domain-inventory) provides a CSV or JSON export through the REST API.

For website crawl records and scan history, see [Website and organization commands](/features/website-org).


# Connect and inspect integrations
Source: https://docs.tolmo.com/features/integrations

Discover provider requirements, connect integrations, and select existing integrations with the Tolmo CLI.

Use `tolmo integration` to discover providers and connect your organization's services. `tolmo integrations` is an alias.

## Discover provider requirements

```bash theme={null}
tolmo integration providers
tolmo integration providers --json
tolmo integration list --json
```

The provider catalog lists configuration fields, secret fields, required values, and provider documentation links. The integration list shows integration IDs, aliases, and non-secret configuration.

## Connect an integration

Use the fields from the provider catalog. For an AWS role integration:

```bash theme={null}
tolmo integration connect aws --alias production --config roleArn=arn:aws:iam::123456789012:role/CloudScanner --config externalId=my-external-id
```

| Flag | Behavior |
| - | - |
| `--alias` | Required friendly name |
| `--config key=value` | Configuration field; repeat for multiple values |
| `--secret key=value` | Secret field; repeat for multiple values |
| `--config-json` | Configuration object as a JSON string |
| `--secrets-json` | Secret fields as a JSON string |
| `--id` | Existing integration ID to update; omit to create |
| `--json` | Return the result as JSON |

Individual `--config` and `--secret` values override matching fields in their JSON objects. Avoid putting literal credentials in shell history.

Most OAuth providers, including GitHub, connect through the app. The CLI prints the page to open. CircleCI also supports a CLI browser flow:

```bash theme={null}
tolmo integration connect circleci --alias ci --oauth
tolmo integration connect circleci --alias ci --oauth --no-browser
```

`--no-browser` prints the authorization URL and requires `--oauth`. You cannot combine the CircleCI OAuth flow with config or secret fields.

## Query a connected service

After connecting, use [Query](/commands/query) to make supported provider requests:

```bash theme={null}
tolmo query list
tolmo query --integration <integration-id> github /repos/acme/payments/pulls
```


# Manage Platform-Owned Datadog Monitors
Source: https://docs.tolmo.com/features/monitors

Create, update, and delete Datadog monitors managed by the Tolmo platform. All monitors are tagged managed-by:tolmo and use server-side org credentials.

The `tolmo monitor` command manages Datadog monitors that the Tolmo platform owns on behalf of your organization. Datadog credentials are resolved server-side and never exposed to the CLI. Every monitor created this way is stamped with the `managed-by:tolmo` tag, making it easy to distinguish platform-owned monitors from anything you manage outside Tolmo.

## List managed monitors

`tolmo monitor list` lists monitors visible to the selected integration. Use the `--tag` flag to filter to platform-owned monitors, and add `--json` for machine-readable output:

```bash theme={null}
tolmo monitor list --tag managed-by:tolmo --json
```

To inspect a single monitor by its Datadog ID, use `monitor get`:

```bash theme={null}
tolmo monitor get 12345 --json
```

You can also filter by `--name` and paginate with `--page-size` (up to `1000`) and zero-based `--page`:

```bash theme={null}
tolmo monitor list --name production --page-size 100 --page 0
```

## Create a monitor

Provide a JSON spec file that matches the [Datadog monitor API format](https://docs.datadoghq.com/api/latest/monitors/). The backend always appends `managed-by:tolmo` to the tags array before forwarding the request to Datadog — you do not need to include it yourself.

You can supply the spec as a file path or pipe it from stdin:

```bash theme={null}
tolmo monitor create -f /tmp/cpu-spec.json
cat spec.json | tolmo monitor create -f -
```

## Update a monitor

Pass the monitor's Datadog ID and a JSON patch file to update any fields:

```bash theme={null}
tolmo monitor update 12345 -f /tmp/patch.json
```

> [!WARNING]
>
> `tolmo monitor update` and `tolmo monitor delete` refuse with **HTTP 403** on any monitor that does not carry the `managed-by:tolmo` tag. This safeguard prevents you from accidentally modifying or deleting monitors you manage outside of Tolmo.

## Delete a monitor

Remove a platform-managed monitor by its Datadog ID:

```bash theme={null}
tolmo monitor delete 12345
```

The command fails with HTTP 403 if the target monitor does not carry the `managed-by:tolmo` tag (see the warning above).

## Multiple Datadog integrations

When your organization has more than one Datadog account connected, use `--integration <integration-id>` to target the correct one. Run `tolmo query list` to find integration IDs:

```bash theme={null}
tolmo monitor list --integration <integration-id>
```

## Example monitor spec

Use the following minimal spec as a starting point for a CPU alert monitor. Adapt the `query`, `message`, and threshold values to match your environment, then pass the file to `tolmo monitor create`:

```json cpu-monitor.json theme={null}
{
  "name": "High CPU on production hosts",
  "type": "metric alert",
  "query": "avg(last_5m):avg:system.cpu.user{env:prod} > 80",
  "message": "CPU is over 80% on {{host.name}}. @pagerduty",
  "tags": ["env:prod"],
  "options": {
    "thresholds": {
      "critical": 80,
      "warning": 70
    }
  }
}
```

The backend automatically adds `managed-by:tolmo` to the `tags` array, so you don't need to include it in your spec file.


# Review secret findings
Source: https://docs.tolmo.com/features/secret-findings

Read detected secrets and their triage state through the public REST API.

Use the public API to review secret detections in your organization's resources. Secret findings are separate from the unified vulnerability findings list.

## List detections

```bash theme={null}
curl --get https://api.tolmo.com/api/v1/orgs/acme/secret-findings \
  --header "Authorization: Bearer $TOLMO_API_TOKEN" \
  --data-urlencode severity=high \
  --data-urlencode limit=50 \
  --data-urlencode offset=0
```

Filter by `resourceKey`, `severity`, `ruleId`, or `since`. `since` is an ISO 8601 timestamp applied to the last observation time. The endpoint returns an array and supports `limit` up to `500` with an `offset`.

Each record includes its detection ID, resource key, rule, severity, observation times, and available triage results. See [List secret findings](/api-reference/secrets/list-secret-findings) for the full schema.

The response includes any triage verdict, confidence, and reasoning already recorded for each detection. A missing triage value means it has not yet been assessed.


# Download Threat Model Artifacts
Source: https://docs.tolmo.com/features/threat-model

Retrieve threat model pipeline runs and artifacts using tolmo threat-model. Download the latest run or a specific step from a named pipeline scan.

Tolmo's threat model commands let you download artifacts produced by the platform's threat model pipeline — including full run outputs and individual analysis steps. This is useful for reviewing findings offline or feeding them into other tools.

## List pipeline runs

Use `tolmo threat-model list` to see all recorded pipeline runs for your organization. The output shows each scan's ID and its current status, giving you a quick overview of what has run and whether it completed successfully.

```bash theme={null}
tolmo threat-model list
```

## Download run artifacts

Once you know which run you want to inspect, use `tolmo threat-model get` to fetch its artifacts. You can target the latest run, a specific run by ID, or a single analysis step within a run.

**1. Download the latest run**

Run the command without any flags to pull artifacts from the most recent pipeline execution:

```bash theme={null}
tolmo threat-model get
```

**2. Download a specific run by ID**

Pass the scan ID you retrieved from `threat-model list` to download a particular run's artifacts:

```bash theme={null}
tolmo threat-model get --run <scanId>
```

**3. Download a single step**

Use `--step` to narrow the download to one analysis step within the latest run. For example, to pull only the vulnerability qualification step:

```bash theme={null}
tolmo threat-model get --step vuln-qualif
```

## Output options

```bash theme={null}
tolmo threat-model list --json
tolmo threat-model get --out-dir ./review-artifacts
tolmo threat-model get --run <scan-id-prefix> --json
```

The default directory is `./threat-model-<short-scan-id>`. The CLI writes each step into its own directory. `get --json` prints an array of step outputs instead of writing artifact files. Run lookup uses the latest 100 threat-model step summaries, so it may not include older runs.

## Versioned documents through the API

The REST API also exposes generated threat model documents by version. These version numbers are separate from the pipeline scan IDs used by the CLI:

* [List versions](/api-reference/threat-models/list-threat-model-versions), with `limit` and `offset`.
* [Get the latest document](/api-reference/threat-models/get-the-latest-threat-model).
* [Get a specific version](/api-reference/threat-models/get-a-threat-model-version).

A document response includes `version`, `content`, and `createdAt`. Use its version number to pin an archived review to a revision.

## Working with artifacts

After downloading, artifacts are available locally for inspection or further processing.

> [!TIP]
>
> Add `--json` to get machine-readable output, then pipe it to `jq` to filter or extract specific fields. Artifacts are most meaningful when reviewed alongside the corresponding security findings in your Tolmo dashboard, since the platform links each artifact back to its source findings.

## Common use cases

Threat model artifacts fit naturally into several workflows:

* **Automated artifact archiving in CI** — schedule `tolmo threat-model get` in your pipeline to capture and store artifacts after each scan, building a historical record of your threat model evolution.
* **Offline review** — download artifacts before a review session so that security and engineering teams can work through findings without needing live platform access.
* **Importing into other security tools** — consume the JSON output in vulnerability management platforms, ticketing integrations, or custom dashboards that your team already uses.


# Website Scans and Organization Management
Source: https://docs.tolmo.com/features/website-org

List crawled domains and scan history with tolmo website, and switch between organizations with tolmo org. Manage your active context from the terminal.

Tolmo provides commands to view your platform's website scan data and to manage which organization is active in your CLI session. This page covers `tolmo website` and `tolmo org`.

## Website commands

Use the `tolmo website` subcommands to review crawled domains and their scan history. Crawling itself is managed entirely by the platform — these commands let you inspect the results from your terminal.

> **List crawled domains**
>
> Display crawled website records from the graph:
>
> ```bash theme={null}
> tolmo website list
> ```

> **View scan history**
>
> List scan history with timestamps to see when each domain was last scanned:
>
> ```bash theme={null}
> tolmo website scans
> ```

> [!NOTE]
>
> Crawl scheduling and configuration are managed by the Tolmo platform. Use `tolmo website list` and `tolmo website scans` to review results — you don't need to trigger scans manually from the CLI.

`website list` reads up to 200 graph nodes. `website scans` reads up to 50 scan records. Both support `--json`. For a paginated inventory with DNS, web, and lifecycle filters, use [Domains](/features/domains).

## Organization management

Your CLI session always operates in the context of a single active organization. Use `tolmo org` to list the organizations available to your account and switch between them.

### List organizations

See every organization your account has access to:

```bash theme={null}
tolmo org list
```

### Switch the active organization

Set a new active organization for all subsequent commands in the current profile. Replace `<slug>` with the organization's slug from `tolmo org list`:

```bash theme={null}
tolmo org switch <slug>
```

The active organization is stored in the current profile. If you want to target a different organization for only a single command without permanently switching, use the global `--org <slug>` flag instead — no profile update is made.

To switch the active organization in a specific named profile, pass `--profile`:

```bash theme={null}
tolmo org list
tolmo org switch my-other-org
tolmo org switch --profile staging my-staging-org
```

> [!TIP]
>
> Run `tolmo auth status` at any time to confirm which organization and profile are currently active in your session. This is especially useful when working across multiple profiles or organizations in the same terminal.

`org list` requires a user token from browser login. With an API key in `TOLMO_API_TOKEN`, set `TOLMO_ORG_SLUG` instead of using `org switch`.


# Install the Tolmo CLI skill
Source: https://docs.tolmo.com/guides/agent-skill

Install and update the Tolmo command reference for compatible coding agents.

The Tolmo skill is a Markdown command reference for compatible coding agents. It describes CLI syntax for infrastructure queries, findings review, repository access, and connected services. Commands run with your configured Tolmo credentials and permissions.

## Install and check the skill

```bash theme={null}
tolmo skill install
tolmo skill status
```

The installer writes the CLI reference and finding-format guide to:

* `~/.claude/skills/tolmo/SKILL.md`
* `~/.agents/skills/tolmo/SKILL.md`
* `~/.claude/skills/tolmo-finding-format/SKILL.md`
* `~/.agents/skills/tolmo-finding-format/SKILL.md`

Homebrew installs the CLI binary. Run `tolmo skill install` separately to install the skill. Use [Authentication](/authentication) to configure the CLI before asking an agent to query your organization.

## Update the skill

After updating the CLI, install the bundled skill again:

```bash theme={null}
tolmo update
tolmo skill install
```

`tolmo skill status` reports the installation state for each supported directory.


# Use Tolmo in CI/CD
Source: https://docs.tolmo.com/guides/ci-cd

Install Tolmo, authenticate with an API key, and inspect security findings in GitHub Actions or GitLab CI.

Use an organization API key to run Tolmo without browser login. Create the key in **Settings → API keys**, then store it as `TOLMO_API_TOKEN` in your CI provider's secret store. Set `TOLMO_ORG_SLUG` to your organization slug.

## GitHub Actions

This workflow installs the CLI into a known directory and prints open critical findings:

```yaml .github/workflows/security.yml theme={null}
name: Review security findings
on: [push, workflow_dispatch]
jobs:
  tolmo-check:
    runs-on: ubuntu-latest
    steps:
      - name: Install Tolmo
        run: |
          curl -fsSL https://tolmo.com/install.sh | TOLMO_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: List critical findings
        env:
          TOLMO_API_TOKEN: ${{ secrets.TOLMO_API_TOKEN }}
          TOLMO_ORG_SLUG: ${{ secrets.TOLMO_ORG_SLUG }}
        run: tolmo findings list --status open --severity critical --json
```

Listing findings exits successfully even when findings exist. To fail the job when the filtered list is non-empty, replace the last `run` value with:

```yaml theme={null}
run: |
  tolmo findings list --status open --severity critical --json > findings.json
  jq -e 'length == 0' findings.json
```

The CLI collects all matching pages before returning the array. The gate requires `jq` on the runner.

## GitLab CI

Store the API key and organization slug in **Settings → CI/CD → Variables**. Mark the API key as masked.

```yaml .gitlab-ci.yml theme={null}
security-check:
  image: ubuntu:24.04
  before_script:
    - apt-get update && apt-get install -y ca-certificates curl tar
    - curl -fsSL https://tolmo.com/install.sh | TOLMO_INSTALL_DIR="$HOME/.local/bin" sh
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - tolmo findings list --status open --severity critical --json
```

## Configuration

`TOLMO_API_TOKEN` bypasses saved profiles. Set `TOLMO_API_URL` if you need an API URL other than `https://api.tolmo.com`. See [Environment variables](/configuration/environment-variables) for precedence.

API keys can read published findings and create drafts. User-only operations, including evidence attachments, require a user token and are not available with an organization API key.


# Use the terminal UI
Source: https://docs.tolmo.com/guides/terminal-ui

Browse Tolmo findings, repositories, and threat models with an interactive terminal interface.

Run `tolmo tui` after [authenticating](/authentication):

```bash theme={null}
tolmo tui
tolmo tui --profile work --org acme
```

The terminal UI is experimental and may change between releases. It lets you browse findings, repositories, and threat models, and run SQL or Cypher queries.

| Key | Action |
| - | - |
| Arrow keys or `j` / `k` | Navigate lists and menus |
| Enter or right arrow | Enter a section |
| Escape or left arrow | Return to navigation |
| Tab | Switch between query input and results |
| `r` | Refresh the view |
| Ctrl+R | Execute the SQL or Cypher query |
| `q` or Ctrl+C | Quit |

Use individual [CLI commands](/introduction) with `--json` for scripts and pipelines.


# Query historical findings and graph observations
Source: https://docs.tolmo.com/guides/time-machine

Read findings at a past time with SQL and use graph observation timestamps to review infrastructure changes.

Use SQL's `--as-of` option to query findings as they existed at a past time. Use graph observation timestamps to see when resources were first or most recently observed.

## Historical findings

```bash theme={null}
tolmo sql --as-of 2026-09-01 "SELECT id, title, severity, status FROM findings WHERE severity = 'high' LIMIT 20"
tolmo sql --as-of 2026-09-01T14:30:00Z --json "SELECT status, count(*) FROM findings GROUP BY status"
```

Dates and timestamps without a timezone use UTC. The `findings` table resolves to its state at the requested instant. Other tables remain current, so a join to another table is not a historical snapshot of both tables.

For direct API calls, send the timestamp in the SQL request body's `asOf` field. JSON CLI output contains the result array in `rows`:

```bash theme={null}
tolmo sql --as-of 2026-09-01 --json "SELECT id, title FROM findings LIMIT 20" | jq '.rows[]'
```

## Graph observation timestamps

Graph nodes and edges carry these epoch-millisecond timestamps:

| Property | Meaning |
| - | - |
| `firstSeenAt` | When the crawler first observed the resource or relationship |
| `lastSeenAt` | When the crawler most recently observed it |

Find resources first observed during the last seven days:

```bash theme={null}
tolmo cypher "MATCH (n:GraphNode) WHERE n.firstSeenAt >= (timestamp() - 7*24*60*60*1000) RETURN n.resourceType, n.resourceKey ORDER BY n.firstSeenAt DESC"
```

Find resources not observed during the last 48 hours:

```bash theme={null}
tolmo cypher "MATCH (n:GraphNode) WHERE n.lastSeenAt < (timestamp() - 48*60*60*1000) RETURN n.resourceType, n.resourceKey LIMIT 50"
```

These are observation times. They do not establish when a resource was created or deleted, and they do not reconstruct past property values. A stale observation can also mean a crawl has not run or could not reach the resource.

For scripted graph queries, pass `--intent` to record the purpose of the request. See [SQL and Cypher](/commands/sql-cypher).


# Install the Tolmo CLI: Homebrew, Script, and Debian
Source: https://docs.tolmo.com/installation

Install the Tolmo CLI via Homebrew, the install script, or a Debian package. Supports macOS and Linux on amd64 and arm64 architectures.

Tolmo runs on macOS and Linux and supports both amd64 and arm64 architectures. Choose the installation method that fits your workflow: Homebrew is the easiest option for interactive use, the install script works on any system without a package manager, and the Debian package integrates with `dpkg`-based systems.

**Homebrew**

First, add the Tolmo tap to Homebrew, then install the CLI:

```bash theme={null}
brew tap tolmohq/tolmo https://github.com/tolmohq/tolmo
brew install tolmohq/tolmo/tolmo
```

> [!NOTE]
>
> The Homebrew formula installs the Tolmo CLI binary only. It does **not** automatically modify Claude Code or other coding-agent directories. If you want to use Tolmo as an agent skill, run the following after installation:
>
> ```bash theme={null}
> tolmo skill install
> tolmo skill status
> ```

**Install Script**

Run the official install script with a single command:

```bash theme={null}
curl -fsSL https://tolmo.com/install.sh | sh
```

The script automatically selects a writable install directory. When `/usr/local/bin` is not writable — the common case on macOS without admin rights — it falls back to a user-level directory, so you typically do not need `sudo`.

To install to a custom directory, set the `TOLMO_INSTALL_DIR` environment variable before running the script:

```bash theme={null}
curl -fsSL https://tolmo.com/install.sh | TOLMO_INSTALL_DIR="$HOME/.local/bin" sh
```

After installation, make sure the install directory is on your `PATH`. Add the following line to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) if it is not already present:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

**Debian / Ubuntu**

Download the `.deb` package for your architecture from the [latest GitHub release](https://github.com/tolmohq/tolmo/releases/latest), then install it with `dpkg`:

```bash theme={null}
sudo dpkg -i tolmo_<version>_<arch>.deb
```

Replace `<version>` with the release version number (for example, `0.9.1`) and `<arch>` with your architecture (`amd64` or `arm64`).

## Nightly builds

Nightly builds track the latest development changes and are published automatically from the main branch.

**Homebrew:**

```bash theme={null}
brew install tolmohq/tolmo/tolmo-nightly
```

**Install script:**

```bash theme={null}
curl -fsSL https://tolmo.com/install.sh | sh -s -- --nightly
```

> [!NOTE]
>
> Nightly builds may be unstable and are not recommended for production use. Use them to preview upcoming features or reproduce bugs against the latest code.

## Verify installation

After installing, confirm the CLI is available and check the version:

```bash theme={null}
tolmo --version
```

You should see the installed version number printed to stdout. If the command is not found, check that the install directory is on your `PATH`.

## Update

Use the CLI's update command:

```bash theme={null}
tolmo update
```

It preserves your release channel. Homebrew installations update through Homebrew. Direct installations download and verify the replacement binary. Debian installations print the package download and `dpkg` instructions. Development builds cannot self-update.

After updating, run `tolmo --version`. If you use the [agent skill](/guides/agent-skill), run `tolmo skill install` to refresh it.


# Tolmo CLI
Source: https://docs.tolmo.com/introduction

Use the Tolmo CLI to review findings, query infrastructure, inspect inventory, and manage connected services.

Use the Tolmo CLI to work with your organization's security data from a terminal or CI pipeline. Sign in with a browser for interactive work, or use an API key for automation.

## Get started

[Install Tolmo](/installation), then sign in and review your findings:

```bash theme={null}
tolmo auth login
tolmo auth status
tolmo findings list --status open
```

## Explore the CLI

> **[Findings](/commands/findings)**
>
> Review Tolmo and scanner findings, import reports, create drafts, and record triage decisions.

> **[SQL and Cypher](/commands/sql-cypher)**
>
> Query organization data and infrastructure relationships. Read historical findings with SQL.

> **[Applications](/commands/apps)**
>
> Inspect discovered applications, HTTP endpoints, and linked hostnames.

> **[Domains](/features/domains)**
>
> Browse domain inventory with lifecycle, DNS, and web status filters.

> **[Repositories](/commands/code)**
>
> List and clone repositories available to your organization.

> **[Integrations](/features/integrations)**
>
> Discover provider requirements, connect services, and inspect existing integrations.

> **[Connected service queries](/commands/query)**
>
> Make supported REST, GraphQL, and provider CLI requests through Tolmo.

> **[Threat models](/features/threat-model)**
>
> Download analysis artifacts and retrieve versioned threat model documents.

## Choose your interface

Use `--json` when processing CLI output in scripts. Select an organization with `--org` or a saved session with `--profile`.

* [Authentication](/authentication) explains user tokens and API keys.
* [CI/CD](/guides/ci-cd) provides unattended pipeline examples.
* [Terminal UI](/guides/terminal-ui) provides an interactive view of your data.
* [API reference](/api-reference/introduction) documents direct HTTPS requests.
* [Agent skill](/guides/agent-skill) installs the CLI reference for compatible coding agents.