Create, Triage, and Manage Security Findings via CLI

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

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

Pass - 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>

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:

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.

​Findings model

​List findings

​View a finding

​Create a finding

​Update a finding

​Transition status

​Audit history

​Delete a finding

​Flags reference

Findings model

List findings

View a finding

Create a finding

Update a finding

Transition status

Audit history

Delete a finding

Flags reference