The GraphCDN CLI allows you to configure your GraphCDN service via configuration-as-code. It can both pull the currently active configuration from the GraphCDN web app, as well as (selectively) push configuration from your local YAML file to the GrapCDN 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 GraphCDN configuration.


CLI Changelog

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


You can install the GraphCDN 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 GrapCDN CLI via npm
npm install --global graphcdn 

# Login to your account
graphcdn 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 graphcdn 

Environment Variables

The CLI will also look at your environment variables. Use the GRAPHCDN_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<slug> dashboard URL.

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



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


List services belonging to a specific GraphCDN organization.

graphcdn ls --org <organization slug>

The organization slug can be set on your organization's Settings page on the GraphCDN dashboard.


Allows you to create a new GraphCDN 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.

graphcdn init 

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


Pull the latest service configuration from GraphCDN.

graphcdn pull [--service <service name>]

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


Once you have a local 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. You can provide an additional parameter to limit the sections that are getting pushed to GraphCDN. The values for that parameter are the top-level field names in the graphcdn.yml file.

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

# Make sure your local copy is up to date
graphcdn pull 

# Push everything
graphcdn push 

# Push specific sections only
graphcdn push schema
graphcdn push rules

serve [BETA]

Run a development GraphCDN service pointed at your local GraphQL API. This feature is currently in BETA and might change. Please see our Changelog entry for an introduction to this command.

You will need to have a local 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 graphcdn.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

graphcdn serve --backend-port <port>

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 graphcdn.yml file
  • --serve-port, the port you want to have the GraphCDN environment available on, defaults to the first free port greater than 3000 (Optional)
  • --watch, whether to watch the graphcdn.yml file for changes.
  • --path, the path your GraphQL API is available on, e.g. /graphql
  • --org, The slug of the existing organization where to create this dev-service (You can find the slug as part of your<slug> dashboard URL)

Did this page help you?