tolmo

name	tolmo
description	Use the Tolmo CLI to query infrastructure graphs, run SQL/Cypher queries, proxy requests to connected services (AWS, GitHub, Linear, Sentry, Datadog, Drata, Wiz), manage code repositories, and create/manage security findings.

tolmo — Cloud Security Platform CLI

Installation

# Homebrew (macOS / Linux). Homebrew 6.0.0+ requires trusting third-party taps;
# the fully-qualified name trusts just this formula (or run: brew trust tolmohq/tolmo).
brew tap tolmohq/tolmo https://github.com/tolmohq/tolmo
brew install tolmohq/tolmo/tolmo

# Install script
curl -fsSL https://tolmo.com/install.sh | sh

# install.sh uses a writable user install directory by default on macOS/Linux.
# Set TOLMO_INSTALL_DIR to choose a specific target directory.

# Update the current stable or nightly installation.
tolmo update

Authentication

tolmo auth login                 # Interactive login (opens browser)
tolmo auth status                # Check current session
tolmo auth logout                # Logout

Environment variables (CI / automation)

Variable	Description
TOLMO_API_URL	Backend API base URL (defaults to production)
TOLMO_API_TOKEN	API token (skips interactive login)
TOLMO_ORG_SLUG	Organization slug (required with TOLMO_API_TOKEN)

Named profiles

tolmo auth login --profile staging --api-url https://api.staging.example.com
tolmo --profile staging sql "SELECT 1"

Global flags

Flag	Description
--org <slug>	Override the active organization for a single command
--profile <name>	Use a named profile (default: TOLMO_PROFILE env or default)
--json	Output raw JSON (available on most commands)

Commands

SQL queries

tolmo sql "SELECT id, name FROM organization"
tolmo sql --json "SELECT 1"

Cypher (graph) queries

tolmo cypher "MATCH (n) RETURN labels(n), count(*)"
tolmo cypher --json "MATCH (n) RETURN n LIMIT 5"

Time machine (temporal queries)

Every node and edge has firstSeenAt and lastSeenAt (epoch ms) tracking when resources were first discovered and last seen by crawlers.

# 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 48 hours
tolmo cypher "MATCH (n:GraphNode) WHERE n.lastSeenAt < (timestamp() - 48*60*60*1000) RETURN n.resourceType, n.resourceKey LIMIT 50"

# New relationships 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"

Repository operations

tolmo code list                  # List repositories
tolmo code list --cloneable      # Only repos available for cloning
tolmo code clone org/repo        # Clone a repository
tolmo code clone all             # Clone all cloneable repositories
tolmo code clone all --yes       # Clone all without confirmation prompt

code clone accepts multiple input forms (GitHub and GitLab):

tolmo code clone superset-sh/superset
tolmo code clone github.com/superset-sh/superset
tolmo code clone https://github.com/superset-sh/superset/tree/main/apps/relay
tolmo code clone https://github.com/superset-sh/superset ./relay
tolmo code clone https://gitlab.com/group/subgroup/repo
tolmo code clone group/subgroup/repo --provider gitlab

Query connected services

Credentials are resolved server-side — they never leave the backend. Use tolmo query list to discover available providers for an org.

tolmo query list                           # List available connected services
tolmo query list --org superset            # List for a different org

REST and GraphQL providers (direct proxy)

# GitHub REST (proxied through the backend)
tolmo query github /repos/owner/repo/pulls?state=all
tolmo query github /search/issues?q=type:pr+org:myorg

# Linear (GraphQL)
tolmo query linear '{ viewer { id name } }'
tolmo query linear --file query.graphql

# Sentry (REST)
tolmo query sentry /api/0/organizations/acme/issues/

# Datadog (REST)
tolmo query datadog /api/v1/monitors

# Drata (REST, read-only; paths are relative to /public/v2)
tolmo query drata /company
tolmo query drata '/workspaces?size=100&includeTotalCount=true'

# Wiz (GraphQL, read-only)
tolmo query wiz --file query.graphql

When an org has multiple integrations for the same provider, pass --integration <id> to disambiguate (IDs are shown by query list).

GitHub CLI passthrough (tolmo query -- gh ...)

Runs the local gh CLI with a short-lived token injected by the backend via a Unix socket proxy. This gives you the full gh CLI feature set (pagination, --jq, --template, etc.) using the org's GitHub App credentials. The -- separator is required so that gh flags pass through unchanged.

# List repos
tolmo query -- gh repo list myorg --limit 50

# Search PRs (full gh api syntax)
tolmo query -- gh api search/issues -f "q=type:pr org:myorg created:2026-01-01..2026-03-01" -f per_page=100

# Issues with pagination
tolmo query -- gh issue list --repo myorg/myrepo --state open --json number,title

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

# Disambiguate when multiple GitHub integrations exist
tolmo query --integration <id> -- gh repo list

AWS CLI passthrough (tolmo query -- aws ...)

Uses the local AWS CLI with requests proxied through the backend for credential injection. The -- separator is required.

tolmo query -- aws ec2 describe-instances
tolmo query -- aws s3 ls
tolmo query -- aws iam list-roles --region us-east-1
tolmo query --org klarify -- aws ec2 describe-security-groups --region ca-central-1

Threat model artifacts

tolmo threat-model list                    # List pipeline runs
tolmo threat-model get                     # Download latest run
tolmo threat-model get --run <scanId>      # Download specific run
tolmo threat-model get --step vuln-qualif  # Download single step

Findings

Manage security findings for the current organization. Findings have a severity (critical|high|medium|low|info), a visibility (draft|published), and a status (open|in_review|closed| acknowledged|false_positive).

Finding IDs support prefix matching — the short IDs shown by list (first 8 chars) work in all commands. findings list returns published findings by default; pass --include drafts when you also need in-flight draft findings.

Formatting the description body: the markdown passed to --description / --description-file (and edited via findings update) is what dev/CTO customers actually read. Keep it concise, evidence-backed, and specific about the affected resource, impact, and next action. Before writing or editing that body, load the tolmo-finding-format skill (installed alongside this one by tolmo skill install) for the required structure and checklist.

# List findings (published by default; opt in to include drafts too)
tolmo findings list
tolmo findings list --status open --severity critical
tolmo findings list --include drafts --json

# Show a single finding (prints markdown description)
tolmo findings get <findingId>
tolmo findings get <findingId> --json

# Create a finding
tolmo findings create \
  --title "Exposed S3 bucket" \
  --severity high \
  --description "Markdown description here"

# Create with description from a file (or '-' for stdin). --source-name labels
# the finding's origin (default "Tolmo"); set it to the engagement.
tolmo findings create \
  --title "IAM role misconfiguration" \
  --severity critical \
  --description-file ./finding.md \
  --source-name "Pentest Q3 2026" \
  --visibility published \
  --status open

# Record the internal modus operandi (how the finding was produced). Internal
# Tolmo-side triage narrative — never shown to the customer; readable only
# through admin tooling. Requires a super-admin or pentester (a non-privileged
# org token is rejected with 403). MANDATORY when a pentester creates a finding
# — a pentester create that omits it fails with 400; super-admins are exempt.
# Editable ad-hoc later via `findings update --modus-operandi`. Also accepts
# --modus-operandi-file <path> ('-' for stdin).
tolmo findings create \
  --title "IAM role misconfiguration" \
  --severity critical \
  --description-file ./finding.md \
  --modus-operandi "Assumed the CI role via the unscoped trust policy, then enumerated attached policies."

# Update authoring fields (only specified flags are changed; status uses the
# dedicated `findings status` command below)
tolmo findings update <findingId> --severity critical --visibility published
tolmo findings update <findingId> --description-file ./updated.md
tolmo findings update <findingId> --source-name "Pentest Q3 2026"
tolmo findings update <findingId> --modus-operandi "Re-confirmed via the CI role after the Q3 key rotation."

# Transition status (dedicated endpoint — only changes status)
tolmo findings status <findingId> in_review
tolmo findings status <findingId> closed \
  --justification 
tolmo findings status <findingId> closed \
  --justification-file ./closure-note.md
tolmo findings status <findingId> acknowledged
tolmo findings status <findingId> false_positive


tolmo findings  <findingId>


tolmo findings attachments list <findingId>
tolmo findings attachments list <findingId> --json
tolmo findings attachments upload <findingId> ./evidence.png
tolmo findings attachments upload <findingId> ./poc.png --title 
tolmo findings attachments download <findingId> <attachmentId>
tolmo findings attachments download <findingId> <attachmentId> \
  --output ./evidence.png --force
tolmo findings attachments delete <findingId> <attachmentId> --


tolmo findings delete <findingId> --

create prints a shareable app URL for the finding, and get / list --json include it as the url field — link a customer straight to the finding page with it.

findings update authorization: a super-admin may edit any finding; a pentester may edit findings they authored — including after publishing, so you can correct your own work (status still goes through findings status, and --source-name stays super-admin-only). You cannot edit another author's finding. Author self-edits are logged server-side.

Finding attachments are sensitive evidence. They may be any regular file up to 250 MiB and are streamed only through Tolmo's authenticated API; no public object URL is returned. --title is optional at upload; when set, it becomes the primary label reviewers see next to the file name in the app. Attachment commands require an interactive user token for an organization member, an explicitly granted pentester, or a Tolmo admin. Machine organization tokens are rejected. Deleting an attachment additionally requires being its uploader or a Tolmo admin. Finding and attachment IDs both support unambiguous prefix matching. A scoped pentester can manage attachments on a draft they authored without publishing it first. Downloads default to the stored filename, reduce implicit names to a safe basename, refuse to overwrite existing files without --force, and create files with owner-only permissions (0600). With --force, the CLI replaces the destination only after the download completes, so a failed request cannot truncate existing evidence.

Findings field reference

Flag	Values	Default	Notes
--title	any string (max 512)	—	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
--source-name	any string (max 256)	Tolmo	Create/update. Origin label for the finding (e.g. "Pentest Q3 2026", "HackerOne"); shown as Source: in get
--modus-operandi	text	—	Create/update. Internal Tolmo-side notes on how the finding was produced; never shown to the customer; requires super-admin/pentester (non-privileged token → 403). Mandatory when a pentester creates (omitting it → 400); super-admins exempt. Mutually exclusive with --modus-operandi-file
--modus-operandi-file	file path or - for stdin	—	Create/update; mutually exclusive with --modus-operandi
--include	drafts	—	List-only; returns draft findings alongside published findings
--visibility	draft published	draft	Create/update-only; controls the finding publication state
--status	open in_review closed

External findings

External findings are imported from security platforms such as Wiz, Drata, and Aikido. Their provider-native status is kept separate from Tolmo's triage and exploitation lifecycle.

# Browse the current page
tolmo external-findings list

# Filter server-side
tolmo external-findings list \
  --origin wiz \
  --severity high \
  --state needs_exploitation \
  --q "public bucket"

# Continue from the opaque cursor printed after the previous page
tolmo external-findings list --cursor '<cursor>' --limit 50

# Preserve the complete page envelope, including facets and nextCursor
tolmo external-findings list --json

# Inspect the original platform URL/body and assessment report provenance
tolmo external-findings get <externalFindingId>
tolmo external-findings get <externalFindingId> --json

# Import a consolidated DeepSec/Codex Security Markdown report. Reusing the
# same provider, source, and USR-* IDs refreshes those rows idempotently.
tolmo external-findings upload ./security-scan-unified-report.md \
  --provider code-security \
  --source repo-1-security-scans

Supported Tolmo lifecycle states are untriaged, false_positive, needs_exploitation, exploitation_pending, exploited, exploitation_unsuccessful, inconclusive, dismissed, and remediated. inconclusive is a terminal exploitation outcome; an inconclusive false-positive review routes to needs_exploitation instead. remediated is the post-exploitation last mile: proven real by exploitation, then fixed.

The list table explicitly separates ORIGINAL STATUS from STATE, links back to the original platform, and shows the canonical TOLMO FINDING together with its source relationship and Tolmo link. Detail output includes report markdown plus the producing agent-output and workflow-run identifiers, so assessment provenance remains auditable. JSON output preserves the API's canonical reportMarkdown field, its markdown display alias, raw provider payload, rule metadata, source identity, pagination metadata, and facets.

Datadog monitors (managed by the platform)

The monitor subcommand manages Datadog monitors that the platform owns on behalf of the org. The backend decrypts the org's Datadog credentials from the CloudAccount + KMS envelope — the CLI never sees them. Every monitor created here is stamped with the managed-by:tolmo tag, and update/delete refuse with HTTP 403 on any monitor that does not carry that tag.

# Discover what we already manage
tolmo monitor list --tag managed-by:tolmo --json
tolmo monitor get 12345 --json

# Create from a JSON spec (stdin or file). Backend always adds
# `managed-by:tolmo` to the tags before forwarding to Datadog.
tolmo monitor create -f /tmp/cpu-spec.json
cat spec.json | tolmo monitor create -f -

# Update / delete: refused unless the live monitor already carries
# `managed-by:tolmo`. The CLI surfaces the refusal with a clear message.
tolmo monitor update 12345 -f /tmp/patch.json
tolmo monitor delete 12345

# Disambiguate when the org has multiple Datadog integrations
tolmo monitor list --integration <integration-id>

Website data

tolmo website list               # List crawled domains
tolmo website scans              # List scan history

Domain inventory

Canonical customer hostnames from domain_inventory (not crawled websites).

tolmo domains list
tolmo domains list --q api --lifecycle current --dns resolved
tolmo domains list --source cert_spotter --limit 100 --json
tolmo domains list --page 2 --limit 50

Email (pentester mailbox)

For pentesters, the platform provisions per-engagement email aliases (<name>@its-me-tolmo.com) and forwards inbound mail to your real address. These commands let you view those aliases and read the forwarded mail without leaving the terminal. Everything is scoped to your own account. The command is hidden from --help unless you signed in as a pentester or super-admin, but it always operates on your own mail.

tolmo email aliases              # List your alias addresses
tolmo email aliases --json

tolmo email list                 # List inbound emails (newest first)
tolmo email list --alias <id>    # Only mail for one alias
tolmo email list --org <slug>    # Only mail for one organization
tolmo email list --limit 50 --json

tolmo email read <message-id>    # Print the email body (plain text)
tolmo email read <message-id> --html   # Print the raw HTML body instead
tolmo email read <message-id> --json

You can also browse mail interactively in the TUI (tolmo with no args): the Email sidebar entry lists messages and opens each one's body.

Organization management

tolmo org list                   # List organizations
tolmo org switch <slug>          # Switch active organization

Skill management

tolmo skill install installs the Tolmo CLI skill — this file, covering the CLI surface (queries, repos, findings, threat-model, integrations) — into the user-level Claude / agent skill directories.

The CLI skill is written to ~/.claude/skills/tolmo/SKILL.md and ~/.agents/skills/tolmo/SKILL.md.

tolmo skill install              # Install or update the CLI skill
tolmo skill status               # Check installation state

Rules for automation

• Always use --json for machine-readable output when parsing results programmatically.
• Use --org <slug> to override the active organization for a single command.
• Use environment variables (TOLMO_API_TOKEN, TOLMO_ORG_SLUG) in CI/CD pipelines instead of interactive login.
• All query subcommands proxy through the backend — providers are discovered dynamically, so new backend adapters work without a CLI update.
• For query -- gh and query -- aws, the -- separator is mandatory. Without it, cobra strips unknown flags (like --region, --repo) before they reach the underlying CLI.