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.
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 |
| Value | Meaning |
|---|
draft | Hidden from org members; only the creator and org owners can see it |
published | Visible to all org members |
| 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 |
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.
List findings
# 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.
# 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.
# Inline description
tolmo findings create \
--title "Exposed S3 bucket" \
--severity high \
--description "Markdown description here"
# Description from a file, published immediately
tolmo findings create \
--title "IAM role misconfiguration" \
--severity critical \
--description-file ./finding.md \
--visibility published \
--status open
- as the value to --description-file to read the description from stdin:
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.
# 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.
# 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:
tolmo findings history <findingId>
Delete a finding
Deletion is permanent and requires the --yes flag to confirm:
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 |
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.