📘

Renaming of the CLI

With the name change from GraphCDN to Stellate, we also renamed the CLI. For the time being the CLI will work with both STELLATE_ and GRAPHCDN_ prefixes for any environment variables.

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 YAML 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.

📘

CLI Changelog & Bug Reports

The current version of the CLI is 1.12.0, the full changelog for the CLI is available at Stellate CLI Changelog for the changes implemented in each version.

If you find bugs with the CLI, feel free to reach out via the in-app messenger, or file them directly on the public GitHub repository.

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 the Stellate CLI via npm
npm install --global stellate 

# 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.

# Update to the latest available version
npm install --global stellate 

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/.

📘

We'll automatically move over your configuration from ~/.graphcdn/ to ~/.stellate/ when you run the Stellate CLI and don't have the corresponding configuration directory yet.

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 

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>]

The --service is optional, as long as you have a stellate.yml (or graphcdn.yml) configuration in your current directory that specifies which service to use.

push

Once you have a local stellate.yml (or graphcdn.yml) 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.yml you can specify which environment to push via the --env <environment_name> flag.

# Push to the staging environment
stellate push --env staging

check

🚧

[Beta]

This is a beta feature, released with version 1.12.0 of the CLI

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 in 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)

serve

Run a development Stellate service pointed at your local GraphQL API. This command will make 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.yml (or graphcdn.yml) configuration available in your working directory. You can either pull the configuration (recommended) as documented above or start with a skeleton configuration:

# Skeleton stellate.yml
# If you're using the skeleton, the values provided do not matter and
# you do not need to point your schema or origin URL to your actual
# development service
name: local-dev
app: local-dev
schema: http://graphql.local
originUrl: http://graphql.local

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.yml 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.yml 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.

Did this page help you?