speakeasy-api
diff --git a/‎AGENTS.md‎
Lines changed: 9 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 8 additions & 0 deletions b/‎README.md‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎cmd/openapi/commands/openapi/README.md‎
Lines changed: 58 additions & 0 deletions b/‎cmd/openapi/commands/openapi/README.md‎
Lines changed: 58 additions & 0 deletions
diff --git a/‎cmd/openapi/commands/openapi/query.go‎
Lines changed: 59 additions & 54 deletions b/‎cmd/openapi/commands/openapi/query.go‎
Lines changed: 59 additions & 54 deletions
@@ -138,6 +138,15 @@ If you add new packages to the root module (e.g., `oq/`, `graph/`) that `cmd/ope
 
 This gives `cmd/openapi/go.mod` a pseudo-version (e.g., `v1.19.6-0.20260312183335-395c19cd8edd`) that resolves correctly both locally and in CI. Each subsequent push that changes the root module requires repeating step 2 with the new commit SHA.
 
+## CLI Documentation
+
+When adding or modifying subcommands under `openapi spec`, you **must** update both:
+
+1. `README.md` (root) — the command list and Quick Examples section
+2. `cmd/openapi/commands/openapi/README.md` — detailed command documentation with examples, flags, and usage patterns
+
+The command README (`cmd/openapi/commands/openapi/README.md`) serves as the primary reference for each subcommand and should include usage examples, flag tables, and before/after demonstrations where applicable.
+
 ## Linter Rules
 
 This project uses `golangci-lint` with strict rules. Run `mise lint` to check. The most common violations are listed below. **When you encounter a new common lint pattern not documented here, add it to this section so future sessions avoid the same mistakes.**
 
@@ -134,6 +134,8 @@ The CLI provides four main command groups:
   - `snip` - Remove selected operations from an OpenAPI specification (interactive or CLI)
   - `upgrade` - Upgrade an OpenAPI specification to the latest supported version
   - `validate` - Validate an OpenAPI specification document
+  - `query` - Query an OpenAPI specification using the [oq pipeline language](./oq/README.md) to answer structural and semantic questions about schemas and operations
+  - `query-reference` - Print the complete oq query language reference
 
 - **`openapi swagger`** - Commands for working with Swagger 2.0 documents ([documentation](./cmd/openapi/commands/swagger/README.md))
   - `validate` - Validate a Swagger 2.0 specification document
@@ -179,6 +181,12 @@ openapi swagger validate ./api.swagger.yaml
 
 # Upgrade Swagger 2.0 to OpenAPI 3.0
 openapi swagger upgrade ./api.swagger.yaml ./openapi.yaml
+
+# Query schema graph — find deeply nested components
+openapi spec query 'schemas | select(is_component) | sort_by(depth; desc) | first(10) | pick name, depth' ./spec.yaml
+
+# Query schema graph — blast radius of a schema change
+openapi spec query 'schemas | select(name == "Error") | blast-radius | length' ./spec.yaml
 ```
 
 For detailed usage instructions for each command group, see the individual documentation linked above.
 
@@ -24,6 +24,8 @@ OpenAPI specifications define REST APIs in a standard format. These commands hel
   - [`localize`](#localize)
   - [`explore`](#explore)
   - [`snip`](#snip)
+  - [`query`](#query)
+  - [`query-reference`](#query-reference)
 - [Common Options](#common-options)
 - [Output Formats](#output-formats)
 - [Examples](#examples)
@@ -1196,6 +1198,62 @@ components:
 - You want to reduce the size and complexity of a specification
 - You need to create different API variants from a single source
 
+### `query`
+
+Query an OpenAPI specification using the oq pipeline language to answer structural and semantic questions about schemas and operations.
+
+```bash
+# Find deeply nested components
+openapi spec query 'schemas | select(is_component) | sort_by(depth; desc) | first(10) | pick name, depth' ./spec.yaml
+
+# OneOf unions missing discriminator
+openapi spec query 'schemas | select(is_component and union_width > 0 and not has_discriminator) | pick name, union_width' ./spec.yaml
+
+# Schemas missing descriptions
+openapi spec query 'schemas | select(is_component and not has_description) | pick name, type' ./spec.yaml
+
+# Operations missing error responses
+openapi spec query 'operations | select(not has_error_response) | pick name, method, path' ./spec.yaml
+
+# Blast radius — what breaks if I change a schema?
+openapi spec query 'schemas | select(name == "Error") | blast-radius | length' ./spec.yaml
+
+# Duplicate inline schemas
+openapi spec query 'schemas | select(not is_component) | group_by(hash) | select(count > 1)' ./spec.yaml
+
+# Navigate to a single schema by name
+openapi spec query 'schemas | select(name == "Pet") | explain' ./spec.yaml
+
+# List all enum schemas
+openapi spec query 'schemas | select(is_component and enum_count > 0) | pick name, enum_count' ./spec.yaml
+
+# Pipe from stdin
+cat spec.yaml | openapi spec query 'schemas | length'
+
+# Read query from file
+openapi spec query -f analysis.oq ./spec.yaml
+
+# Output as JSON
+openapi spec query --format json 'schemas | select(is_component) | first(5)' ./spec.yaml
+```
+
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--format` | | Output format: `table` (default), `json`, `markdown`, or `toon` |
+| `--file` | `-f` | Read query from file instead of argument |
+
+For the full query language reference, run `openapi spec query-reference`.
+
+### `query-reference`
+
+Print the complete reference for the oq pipeline query language, including all sources, stages, fields, operators, and examples.
+
+```bash
+openapi spec query-reference
+```
+
 ## Common Options
 
 All commands support these common options:
 
@@ -17,60 +17,39 @@ var queryCmd = &cobra.Command{
 	Use:   "query <query> [input-file]",
 	Short: "Query an OpenAPI specification using the oq pipeline language",
 	Long: `Query an OpenAPI specification using the oq pipeline language to answer
-structural and semantic questions about schemas and operations.
-
-The query argument comes first, followed by an optional input file. If no file
-is given, reads from stdin.
-
-Examples:
-  # Deeply nested components (jq-style syntax)
-  openapi spec query 'schemas.components | sort_by(depth; desc) | first(10) | pick name, depth' petstore.yaml
-
-  # Pipe from stdin
-  cat spec.yaml | openapi spec query 'schemas | count'
-
-  # Explicit stdin
-  openapi spec query 'schemas | count' -
-
-  # Filter with select()
-  openapi spec query 'schemas | select(union_width > 0) | sort_by(union_width; desc) | first(10)' petstore.yaml
-
-  # Dead components (no incoming references)
-  openapi spec query 'schemas.components | select(in_degree == 0) | pick name' petstore.yaml
-
-  # Variable binding — exclude seed from reachable results
-  openapi spec query 'schemas | select(name == "Pet") | let $pet = name | reachable | select(name != $pet)' petstore.yaml
-
-  # User-defined functions
-  openapi spec query 'def hot: select(in_degree > 5); schemas.components | hot | pick name' petstore.yaml
-
-  # Alternative operator — fallback for null/falsy values
-  openapi spec query 'schemas | select(name // "none" != "none")' petstore.yaml
-
-  # If-then-else conditional
-  openapi spec query 'schemas | select(if is_component then depth > 3 else true end)' petstore.yaml
-
-  # Blast radius
-  openapi spec query 'schemas.components | select(name == "Error") | blast-radius | length' petstore.yaml
-
-  # Explain a query plan
-  openapi spec query 'schemas.components | select(depth > 5) | sort_by(depth; desc) | explain' petstore.yaml
-
-Pipeline stages (jq-style):
-  Source:     schemas, schemas.components, schemas.inline, operations
-  Traversal:  refs-out, refs-in, reachable, ancestors, properties, union-members, items,
-              ops, schemas, path(A; B), connected, blast-radius, neighbors(N)
-  Analysis:   orphans, leaves, cycles, clusters, tag-boundary, shared-refs
-  Filter:     select(expr), pick <fields>, sort_by(field; desc), first(N), last(N),
-              sample(N), top(N; field), bottom(N; field), unique, group_by(field), length
-  Variables:  let $var = expr
-  Functions:  def name: body;  def name($p): body;  include "file.oq";
-  Meta:       explain, fields, format(table|json|markdown|toon)
-
-  Legacy syntax (where, sort, take, head, select fields, group-by, count) is still supported.
-
-Expression operators: ==, !=, >, <, >=, <=, and, or, not, //, has(), matches,
-                      if-then-else-end, string interpolation \(expr)`,
+structural and semantic questions about schemas, operations, parameters,
+responses, content types, and headers.`,
+	Example: `Queries are pipelines: source | stage | stage | ...
+
+Pipeline stages:
+  Source:      schemas, operations, components.schemas, components.parameters,
+               components.responses, components.request-bodies, components.headers,
+               components.security-schemes
+  Navigation:  parameters, responses, request-body, content-types, headers,
+               schema, operation, security
+  Traversal:   refs-out, refs-in, reachable, reachable(N), ancestors, properties,
+               union-members, items, parent, ops, schemas, path(A; B), connected,
+               blast-radius, neighbors(N)
+  Analysis:    orphans, leaves, cycles, clusters, tag-boundary, shared-refs
+  Filter:      select(expr), pick <fields>, sort_by(field; desc), first(N), last(N),
+               sample(N), top(N; field), bottom(N; field), unique,
+               group_by(field), group_by(field; name_field), length
+  Variables:   let $var = expr
+  Functions:   def name: body;  def name($p): body;  include "file.oq";
+  Output:      emit, format(table|json|markdown|toon)
+  Meta:        explain, fields
+
+Operators: ==, !=, >, <, >=, <=, and, or, not, //, has(), matches, contains,
+           if-then-else-end, \(interpolation), lower(), upper(), len(), split()
+
+  openapi spec query 'operations | responses | content-types | select(media_type == "text/event-stream") | operation | unique' spec.yaml
+  openapi spec query 'operations | security | group_by(scheme_type; operation)' spec.yaml
+  openapi spec query 'schemas | select(is_component) | sort_by(depth; desc) | first(10) | pick name, depth' spec.yaml
+  openapi spec query 'operations | select(name == "createUser") | request-body | content-types | schema | reachable(2) | emit' spec.yaml
+  openapi spec query 'components.security-schemes | pick name, type, scheme' spec.yaml
+  cat spec.yaml | openapi spec query 'schemas | length'
+
+For the full query language reference, run: openapi spec query-reference`,
 	Args: queryArgs(),
 	Run:  runQuery,
 }
@@ -81,6 +60,25 @@ var queryFromFile string
 func init() {
 	queryCmd.Flags().StringVar(&queryOutputFormat, "format", "table", "output format: table, json, markdown, or toon")
 	queryCmd.Flags().StringVarP(&queryFromFile, "file", "f", "", "read query from file instead of argument")
+
+	// Custom help template: Usage + Flags together, then Examples last
+	queryCmd.SetUsageTemplate(`Usage:{{if .Runnable}}
+  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]{{end}}{{if gt (len .Aliases) 0}}
+
+Aliases:
+  {{.NameAndAliases}}{{end}}{{if .HasAvailableLocalFlags}}
+
+Flags:
+{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
+
+Global Flags:
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasExample}}
+
+{{.Example}}{{end}}{{if .HasAvailableSubCommands}}
+
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}
+`)
 }
 
 func runQuery(cmd *cobra.Command, args []string) {
@@ -146,6 +144,13 @@ func queryOpenAPI(ctx context.Context, processor *OpenAPIProcessor, queryStr str
 		return fmt.Errorf("query error: %w", err)
 	}
 
+	// Emit stage outputs raw YAML nodes, bypassing format selection
+	if result.EmitYAML {
+		output := oq.FormatYAML(result, g)
+		fmt.Fprint(processor.stdout(), output)
+		return nil
+	}
+
 	// Format and output — inline format stage overrides CLI flag
 	format := queryOutputFormat
 	if result.FormatHint != "" {