CLI

The Stellate CLI allows you to configure your Stellate service via configuration-as-code. It can both pull the currently active configuration from the Stellate dashboard, as well as (selectively) push configuration from your local TypeScript file to the Stellate web app. It is a great way to make sure you have a backup of your configuration at hand and can follow (and approve) changes made. We recommend using your CI workflow to push changes to your Stellate configuration.

Setup

You can install the Stellate CLI via npm (or a similar package manager like yarn). If you do not have Node.js or npm installed, please take a look at their installation documentation  for how to install those tools.

Install CLI

npm i stellate --global

pnpm add stellate --global

yarn global add stellate

bun add stellate --global

Login to your account

stellate login

Updating the CLI

The CLI currently doesn’t auto-update and doesn’t check for newer available versions. Instead, we rely on you to update to newer versions of the CLI.

If you installed the CLI via the command mentioned above, you can update to the latest available version by re-running that command.

npm i stellate --global

pnpm add stellate --global

yarn global add stellate

bun add stellate --global

Environment Variables

The CLI will also look at your environment variables. Use the STELLATE_ORG environment variable to specify which organization you want to work with, by setting it to the slug of your organization. You can find the slug as part of your <https://stellate.co/dashboard/><slug> dashboard URL.

To specify the access token you can use the STELLATE_TOKEN environment variable.

Commands

login

Login to Stellate. This will open a browser window for you to authenticate with Stellate and store your authentication credentials in ~/.stellate/.

ls

List services belonging to a specific Stellate organization.

stellate ls --org <organization slug>

The organization slug can be set on your organization’s Settings page on the Stellate dashboard.

init

Allows you to create a new Stellate service via the command line. You will be asked a couple of questions about your GraphQL API and will need to have a schema definition available locally. The definition can either be a GraphQL SDL file or as a GraphQL.js schema object.

stellate init [--output-format <ts|js|mjs>]

We would recommend using the Stellate dashboard to set up new services, especially for new users.

pull

Pull the latest service configuration from Stellate.

stellate pull [--service <service name>] [--output-format <ts|js|mjs>]

The --service is optional, as long as you have a stellate.ts configuration in your current directory that specifies which service to use.

push

Once you have a local stellate.ts configuration, you can make changes and sync those changes back via the push command. By default push syncs the complete file with your specified service.

Since this will override your Stellate service configuration with the values from your local environment, we recommend always pulling up-to-date configuration first.

If you want to only push your schema, you can run stellate push schema.

# Make sure your local copy is up to date
stellate pull
 
# Push everything
stellate push
 
# Push schema information only
stellate push schema

If you have multiple environments defined in your stellate.ts you can specify which environment to push via the --env <environment_name> flag.

# Push to the staging environment
stellate push --env staging [--dry]

If you want to see the diff of the environment without pushing you can use push together with the flag --dry this will show the diff with the currently active config but not push any changes.

check

Check if there are breaking schema changes, e.g. removing a field that is still being requested by your clients

$ stellate check
⚠ Heads up, this is in beta.
 
 
Check completed.

• --breaking-limit, Maximum number of requests in the given interval for a change to not be considered breaking
• --time-interval, The time interval in seconds to look at, defaults to 24 hours (86,400 seconds)

Known limitations

We don’t yet cover all possible schema changes that could be breaking. Also, we can only calculate the number of affected requests for a subset of all breaking changes.

These are the breaking changes that we currently discover with numbers about affected requests:

• Removing a type
• Removing a field from an Object Type or Input Object Type
• Changing the output type of a field of an Object Type
• Changing the input type of a field of an Input Object Type

These are the breaking changes that we currently discover without numbers about affected requests:

• Removing an argument from a field of an Object Type
• Removing a value from an Enum Type
• Changing the input type of an argument of a field of an Object Type
• Changing the default value of an argument of a field of an Object Type

serve

Run a development Stellate service pointed at your local GraphQL API. This command will allow you to test your Stellate configuration, as well as test your Purging API integrations with a GraphQL backend running on your local computer.

You will need to have a local stellate.ts configuration available in your working directory. You can either pull the configuration (recommended) as documented above or start with a skeleton configuration:

// Skeleton Stellate configuration
// We recommend you pull your services actual configuration by running
// stellate pull [--service <service name>]
// however, if you want to, you can start with a skeleton configuration as
// well, the values in here do not matter, and you do NOT need to point to
// your actual devlopmen schema or origin
import { Config } from 'stellate'
 
const config: Config = {
  config: {
    name: 'local-dev',
    schema: 'https://dev.end.point',
    originUrl: 'https://dev.end.point',
    passThroughOnly: false,
    rules: [
      {
        description: 'Cache all queries',
        maxAge: 900,
        swr: 900,
        scope: 'PUBLIC',
        types: ['Query'],
      },
    ],
  },
}
 
export default config

Once your local development GraphQL server is up and running, you can create the development environment with the following command. In our example, our local development server listens to GraphQL requests on port 4000 at /graphql. The CLI will print the URLs for the CDN, as well as the Purging API as part of its log output.

$ stellate serve --backend-port 4000 --path /
Using the following local GraphQL endpoint "http://localhost:4000/"
✔ Creating local Stellate dev environment
✔ Stellate is now running at "http://localhost:3010", the Purging API is running at "http://localhost:3011".

In addition to the required --backend-port parameter the serve command also supports the following parameters

• --backend-port, the port your local GraphQL server is running on
• --service, the name of the service if not specified in the stellate.ts file
• --serve-port, the port you want to have the Stellate environment available on, defaults to the first free port greater than 3000 (Optional)
• --watch, whether to watch the stellate.ts file for changes.
• --path, the path your backend GraphQL API is available on, e.g. /graphql (Your Stellate service will always be available on / and /graphql.)
• --org, which organization to create this development service in. You can find the slug as part of your https://stellate.co/dashboard/<slug> dashboard URL.

subset

Schema subsetting allows you to create a new GraphQL schema that is a subset of your existing schema. This can be useful when you want to expose only a portion of the functionality of the original schema to a particular client or when you want to create a specialized schema for a specific use case.

To use the schema subsetting, you can configure types, fields, and interfaces that you want to include and/or exclude in the new schema. With this configuration, a new schema will be created for you.

One of the main benefits of using schema subsetting is that it allows you to customize the API that is exposed to clients, which can make it easier to maintain and evolve the schema over time. It also allows you to create specialized schemas for different clients or use cases, which can improve the performance and scalability of your GraphQL server.

To include and exclude types, etc. from your schema we use the @tag directive, the same way Contracts does it. You then need to define these tags in your Stellate configuration. Based on this a subset schema can be created.

To configure the subset see schemaView in the configuration page.

To illustrate, consider the following example:

import { Config } from 'stellate'
 
const config = {
  config: {
    schema: './schema.graphql',
    schemaView: {
      include: [],
      exclude: ['private'],
    },
  },
}

Example input schema:

directive @tag(
  name: String!
) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION
 
type Query {
  exercises: [Exercise]
  users: [User] @tag(name: "private")
}
 
type Exercise {
  id: ID!
}
 
type User @tag(name: "private") {
  id: ID!
}

Running the command stellate subset > schema-subset.graphql would result in the following output:

type Query {
  exercises: [Exercise]
}
 
type Exercise {
  id: ID!
}

config preview

Preview the impact of new or updated caching rules on your existing operations.

stellate config preview [--service <service name>] [--browser]

This command generates a link to your Stellate dashboard where you can see the impact of your changes on your recent operations. The --browser flag will open the link in your default browser.