Introducing local composition using the Grafbase CLI

Today, we're excited to introduce a new command in the Grafbase CLI: grafbase compose. This command allows you to easily compose a federated GraphQL schema from your subgraphs without starting a development server.

The compose command brings the power of GraphQL federation to your local development workflow. It lets you:

• Combine multiple subgraphs into a unified federated schema
• Mix local subgraphs with those from your Grafbase cloud graphs
• Override remote subgraphs with local versions during development
• Output the resulting schema to stdout or a file

The compose command is particularly useful when you want to:

• Generate a federated schema for validation or inspection
• Use the composed schema in other tooling
• Check that your subgraph changes will compose without conflicts
• Create snapshots of your schema for version control

Unlike the dev command, compose only generates the federated schema and does not start a server or UI, making it perfect for CI/CD pipelines, code generators, or any workflow that needs the raw schema.

Basic usage is straightforward:

grafbase compose

This will compose all local subgraphs defined in your grafbase.toml configuration.

To include subgraphs from an existing graph in the Grafbase platform:

grafbase compose --graph-ref my-org/my-graph@main

You can also mix remote subgraphs with local overrides:

# grafbase.toml
[subgraphs.products]
introspection_url = "http://localhost:4000/graphql"

grafbase compose --graph-ref my-org/my-graph@main --config grafbase.toml

The command supports custom authentication headers for introspection:

# grafbase.toml
[subgraphs.products.introspection_headers]
authorization = "Bearer {{ env.PRODUCTS_ACCESS_TOKEN }}"

And you can easily redirect the output to a file:

grafbase compose --graph-ref my-org/my-graph@main > federated-schema.graphql

See the reference docs for more information.

The compose command is just one of many improvements we're making to the Grafbase CLI to enhance your GraphQL federation workflow. Stay tuned for more features that will make working with federated graphs even more seamless.

We'd love to hear how you're using the compose command and what other CLI features would help your federation journey. Join us on Discord to share your feedback!