Skip to main content

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.

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"

​
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.
ElementKey propertiesDescription
GraphNoderesourceType, resourceKeyRepresents a single infrastructure resource (e.g. an S3 bucket, an IAM role, a GitHub repository).
GRAPH_EDGEtypeA directed relationship between two nodes (e.g. HAS_ROLE, OWNS, CONNECTS_TO).
Both nodes and edges carry temporal tracking fields:
FieldTypeDescription
firstSeenAtepoch millisecondsWhen the crawler first discovered this resource or relationship.
lastSeenAtepoch millisecondsThe 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:
ModeFlagDescription
Table(default)Human-readable, column-aligned output. Best for interactive use.
JSON--jsonRaw 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.