once query

Query the typed build graph

Synopsis#

plaintext
once query [OPTIONS] [QUERY] <SUBCOMMAND>

Description#

Inspectable-first surface for humans and agents. query targets lists every declared target id with its target kind and capabilities; query capabilities shows what a specific target exposes (build, lint, run, test); query schema returns the typed attribute and provider shape for a target kind; query example returns the files in a chosen starter; query script validates an annotated script contract; query validate-workspace checks the complete loaded graph; and query evidence lists durable action evidence captured from prior executions. A quoted MATCH ... RETURN ... expression can explore the graph through a read-only Cypher-like pattern. All query surfaces respect --format json and --format toon so consumers can plan against the graph without scraping prose.

Query Expressions#

once query '<QUERY>' accepts a read-only subset of Cypher backed by the Cypher tree-sitter grammar. It accepts one MATCH pattern, optional WHERE predicates joined with AND and OR, and explicit RETURN projections.

bash
once query 'MATCH (app:Target {id: "services/api/Api"})-[:DEPENDS_ON*]->(dep:Target) RETURN dep.id, dep.kind'
once query 'MATCH (t:Target)-[:EXPOSES]->(c:Capability {name: "test"}) RETURN t.id'
once query 'MATCH (t:Target) WHERE t.visibility CONTAINS "public" OR t.attrs.tier IN ["core", "shared"] RETURN t.id, t.attrs.tier'

Supported labels are Target, Capability, and Provider. Labels use the :Label form, for example (t:Target). Bare node names without a colon are aliases, so (Target) binds a variable named Target instead of filtering by the Target label. Supported relationships are DEPENDS_ON, EXPOSES, and EMITS. The * suffix on a relationship performs transitive traversal, for example [:DEPENDS_ON*].

Predicates support =, <>, CONTAINS, IN, STARTS WITH, and ENDS WITH. CONTAINS checks a string substring or array membership. IN checks whether a scalar is present in an array literal. Property paths can inspect nested maps, for example t.attrs.bundle_id.

String literals can be quoted with single or double quotes and support \n, \r, \t, \\, \", and \' escapes. Other escape forms, including Unicode escapes, are rejected.

Arguments#

ArgumentRequiredDescription
<QUERY>noRead-only Cypher-like graph query expression

Options#

FlagValueDefaultDescription
-C, --directory<DIR>Project root. Defaults to the current directory; the cache lives under <project>/.once/. Mirrors make -C
--format<FORMAT>humanOutput format for Once's structured data (cache stats, run/exec trailers). Defaults to a human-readable rendering; pass json or toon to get machine-parseable output for scripting and for agent consumers
-v, --verbose(flag)0Increase log verbosity. Repeat for more (-v: info, -vv: debug, -vvv: trace). Overridden by RUST_LOG
-q, --quiet(flag)falseSuppress human-mode success and progress trailers. Errors and the structured envelope of --format json/toon still print. Mirrors the -q flag of common build tools
--list(flag)falsePrint the command surface at the current command depth
--memory-limit<SIZE>Maximum memory scheduling budget for local actions. Defaults to two thirds of the memory visible to the host or container

Subcommands#