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

# Create, Triage, and Manage Security Findings via CLI

> Create, update, triage, and delete security findings. Control severity, visibility, and status with a full audit trail via tolmo findings commands.

The `tolmo findings` command group lets you manage security findings for your organization — from creation through triage and closure. Findings include a severity, visibility (draft or published), and status with full audit history. All subcommands accept the global `--org` flag to target a specific organization and `--json` for machine-readable output.

## Findings model

Every finding has three core classification fields:

**Severity** — how critical the issue is:

| Value      | Meaning                                           |
| ---------- | ------------------------------------------------- |
| `critical` | Immediate risk; requires urgent remediation       |
| `high`     | Significant risk; prioritize in the current cycle |
| `medium`   | Moderate risk; address in the near term           |
| `low`      | Minor risk; fix as capacity allows                |
| `info`     | Informational; no direct action required          |

**Visibility** — who can see the finding:

| Value       | Meaning                                                             |
| ----------- | ------------------------------------------------------------------- |
| `draft`     | Hidden from org members; only the creator and org owners can see it |
| `published` | Visible to all org members                                          |

**Status** — where the finding is in the triage lifecycle:

| Value            | Meaning                                  |
| ---------------- | ---------------------------------------- |
| `open`           | Newly created; not yet triaged           |
| `in_review`      | Under active investigation               |
| `closed`         | Resolved and closed                      |
| `acknowledged`   | Accepted risk; no further action planned |
| `false-positive` | Determined not to be a real issue        |

<Note>
  Finding IDs support **prefix matching**. The short 8-character IDs shown in `tolmo findings list` work in every subcommand — you don't need to paste the full UUID.
</Note>

## List findings

```bash theme={null}
# List all findings (org members only see published findings)
tolmo findings list

# Filter by status and severity
tolmo findings list --status open --severity critical

# Show draft findings as JSON
tolmo findings list --visibility draft --json
```

## View a finding

`tolmo findings get` prints the full finding, including its markdown description body.

```bash theme={null}
# Print the finding as formatted text (description rendered as markdown)
tolmo findings get <findingId>

# Return the raw finding object as JSON
tolmo findings get <findingId> --json
```

## Create a finding

You can supply the description inline with `--description` or load it from a file with `--description-file`. The two flags are mutually exclusive.

```bash theme={null}
# Inline description
tolmo findings create \
  --title "Exposed S3 bucket" \
  --severity high \
  --description "Markdown description here"
```

```bash theme={null}
# Description from a file, published immediately
tolmo findings create \
  --title "IAM role misconfiguration" \
  --severity critical \
  --description-file ./finding.md \
  --visibility published \
  --status open
```

Pass `-` as the value to `--description-file` to read the description from stdin:

```bash theme={null}
echo "## Summary\nOver-permissive role detected." | tolmo findings create \
  --title "Overpermissive IAM role" \
  --severity high \
  --description-file -
```

## Update a finding

`tolmo findings update` changes only the fields you specify — all other fields remain unchanged.

```bash theme={null}
# Escalate severity and publish a finding
tolmo findings update <findingId> --severity critical --visibility published

# Replace the description from an updated file
tolmo findings update <findingId> --description-file ./updated.md
```

## Transition status

Use `tolmo findings status` to move a finding through its lifecycle. This command uses a dedicated endpoint that only changes the status field, keeping the rest of the finding intact.

```bash theme={null}
# Mark as under review
tolmo findings status <findingId> in_review

# Close a resolved finding
tolmo findings status <findingId> closed

# Acknowledge accepted risk
tolmo findings status <findingId> acknowledged

# Mark as a false positive
tolmo findings status <findingId> false-positive
```

## Audit history

View the full status-change audit trail for a finding:

```bash theme={null}
tolmo findings history <findingId>
```

The history shows every status transition along with the timestamp and the user who made the change.

## Delete a finding

Deletion is permanent and requires the `--yes` flag to confirm:

```bash theme={null}
tolmo findings delete <findingId> --yes
```

## Flags reference

| Flag                 | Values                                                      | Default | Notes                                              |
| -------------------- | ----------------------------------------------------------- | ------- | -------------------------------------------------- |
| `--title`            | any string (max 512 chars)                                  | —       | Required on create                                 |
| `--severity`         | `critical` `high` `medium` `low` `info`                     | —       | Required on create                                 |
| `--description`      | markdown string                                             | `""`    | Mutually exclusive with `--description-file`       |
| `--description-file` | file path or `-` for stdin                                  | —       | Mutually exclusive with `--description`            |
| `--visibility`       | `draft` `published`                                         | `draft` | `draft` findings are hidden from org members       |
| `--status`           | `open` `in_review` `closed` `acknowledged` `false-positive` | `open`  | Use `findings status` to transition after creation |

<Tip>
  Write finding descriptions the way you'd brief a CTO: start with a one-sentence summary of what is exposed, name the specific affected resource (e.g. the bucket ARN or role name), explain the blast radius if exploited, and end with a concrete next action and owner. Concise, evidence-backed descriptions dramatically reduce triage time.
</Tip>