SDL export — `export_schema_sdl` and `nestrs-cli graphql sdl`

nestrs ships two complementary paths for exporting your GraphQL schema as SDL — the canonical GraphQL Schema Definition Language text that Apollo Router, GraphOS Studio, GraphQL Code Generator, and federation gateways consume.

At build time: `export_schema_sdl`

The primary path is a runtime helper that lives in nestrs-graphql. It wraps async-graphql’s built-in SDL printer (Schema::sdl()).

use nestrs::prelude::*;
use nestrs::graphql::{export_schema_sdl, export_sdl_to_file, SDLExportOptions};

#[tokio::main]
async fn main() {
    let schema = Schema::build(Query, Mutation, EmptySubscription).finish();
    let sdl = export_schema_sdl(&schema);
    println!("{sdl}");

    // Or write directly to disk:
    export_sdl_to_file(&schema, "schemas/v1/schema.graphql")
        .expect("write");
}

For federation v2 subgraphs, pass SDLExportOptions::default() .federation().compose_directive():

let options = SDLExportOptions::default()
    .federation()
    .compose_directive();
export_sdl_with_options_to_file(&schema, options, "schemas/v1/user.graphql")?;

The output SDL includes @link / @key directives and the _Entity / _service plumbing an Apollo Router expects.

At runtime: `nestrs-cli graphql sdl`

For CI jobs that hit a running federation subgraph, the CLI ships a thin exporter. It POSTs the standard federation introspection query ({_service{sdl}}) and writes the response to disk.

nestrs-cli graphql sdl \
    --url http://localhost:3000/graphql \
    --out schemas/v1/user.graphql

With an auth bearer token:

nestrs-cli graphql sdl \
    --url https://api.example.com/graphql \
    --out user.graphql \
    --bearer-token "$PROD_GRAPHQL_TOKEN"

Flags:

--url <http> — required. The GraphQL endpoint.
--out <path> — required. Output file. Parent directories are created automatically.
--bearer-token <token> — optional. Adds an Authorization: Bearer <token> header.
--federation (default) — query {_service{sdl}} (Apollo Federation v2 introspection).
--no-federation — query standard introspection instead.

--no-federation does not return SDL. Standard GraphQL introspection is a type graph, not Schema Definition Language. Use it only to confirm the endpoint is alive. For SDL, use build-time export_schema_sdl / export_sdl_to_file, or keep --federation against a subgraph that implements _service { sdl }.

When to use which

Build-time (export_sdl_to_file) — when you control the schema construction code. Use this in your binary’s startup or in a dedicated bin/print_schema.rs so cargo run --bin print_schema regenerates SDL on every change.
Runtime (nestrs-cli graphql sdl) — when you need SDL from a service you don’t own (a remote federation subgraph, a staging environment) or when you want to verify that the live schema still matches what you expected.

The CLI shells out to curl rather than pulling a Rust HTTP client, so the CLI stays light. curl is on every macOS / Linux dev box.

Programmatic access

The same parser the CLI uses (parse_sdl_body) is exposed for embedding in custom tooling:

use nestrs_cli::graphql_sdl;

let sdl = graphql_sdl::parse_sdl_body(response_body)?;
fs::write("schema.graphql", sdl)?;

Get Started

Core Concepts

API Development

Security & Auth

Transports & Protocols

Reliability & agents

Operations

SDL export — `export_schema_sdl` and `nestrs-cli graphql sdl`

At build time: `export_schema_sdl`

At runtime: `nestrs-cli graphql sdl`

When to use which

Programmatic access

See also

At build time: export_schema_sdl

At runtime: nestrs-cli graphql sdl

When to use which

Programmatic access

See also

At build time: `export_schema_sdl`

At runtime: `nestrs-cli graphql sdl`