Run SQL and Cypher Queries Against Your Infrastructure

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.

# 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.

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.

# 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.

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"

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

# 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`	Raw JSON array of result rows. Best for scripting and automation.

Always pass --json when parsing output programmatically. Table formatting can vary across CLI versions, while the JSON schema is stable and easy to process with tools like jq.

Get Started

Core Commands

Platform Features

Security Agents

Configuration

Guides

Run SQL and Cypher Queries Against Your Infrastructure

SQL queries

Cypher (graph) queries

Record why you’re running a query

Graph data model

Output formats

​SQL queries

​Cypher (graph) queries

​Record why you’re running a query

​Graph data model

​Output formats

SQL queries

Cypher (graph) queries

Record why you’re running a query

Graph data model

Output formats