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.

Setup

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

Commands

login

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

ls

List services belonging to a specific GraphCDN organization.

graphcdn ls --org <organization slug>

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

init

Allows you to create a new GraphCDN service via the command line. You will be asked a couple of question 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
Please answer a few questions about your API to setup your GraphCDN service.
...

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

pull

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.

push

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 on your local host your 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