The StepZen CLI (Command Line Interface) is the primary way to build, deploy and test your schemas on StepZen. It is available via npm:

npm install -g stepzen

Once installed, the stepzen command allows you use to manage your StepZen schemas, configurations, and endpoints. The CLI also comes with a built-in Schema Explorer that allows you to explore and test the API you've deployed locally from your browser.

Command Reference

stepzen help

Display Help for StepZen

Usage

stepzen help <command>

where

<command> – (optional) is a command name for which to display help, for example, stepzen help login

stepzen login

Login to StepZen

Usage

stepzen login

The stepzen cli will prompt you for your account name and admin key.

$ stepzen login
$ What is your account name?: happy-llama
$ What is your admin key?: *********************************
$ You have successfully logged in.

Logout

Logout of StepZen

Usage

stepzen logout

The stepzen cli will discard your login information.

$ stepzen logout
$ You have been logged out.

Start

Usage

$ stepzen start
$ ? What would you like your endpoint to be called? (api/unhinged-toucan)

This command does three things:

1. Deploys the code in the current directory (or the directory provided via the --dir option) to the specified endpoint on StepZen.
2. Watches the directory for changes and automatically deploys them to the endpoint specified.
3. Opens a browser window with the StepZen Schema Explorer that will allow you to test your API by exploring the queries and types available and querying the API running on StepZen.

When launched, the command line will return the following information:

Watching ~/folder for GraphQL changes

http://localhost:5000/api/unhinged-toucan

File changed: /Users/username/folder/index.graphql
Deploying to StepZen...... done

Successfully deployed api/unhinged-toucan at 11:29:44 AM

Your endpoint is available at https://username.stepzen.net/api/unhinged-toucan/__graphql

Note that endpoint URL provided as this is the URL your applications will need to call to access your StepZen GraphQL API.

The CLI will also let you know if something is wrong with your graphql. Here are examples of some common errors:

$ Watching ~/folder for GraphQL changes
$ http://localhost:5000/api/unhinged-toucan
$ File changed: /Users/username/folder/config.yaml
$ Deploying to StepZen...... !
$ Error: Schemas must include an `index.graphql` file

This error fires when there's no index.graphql file to list the schema files.

Here's another example:

Watching ~/folder for GraphQL changes

http://localhost:5000/api/unhinged-toucan

File changed: /Users/username/folder/breed.graphql

Your local schema has the following GraphQL errors:

Error: Unknown type "Integer".

This error was thrown because the GraphQL type was unknown (GraphQL integers are specified by Int rather than Integer).

Instead of following the command line prompts, you can also specify your own directory, folder/endpoint, and port.

$ stepzen start --dir=<dir> --endpoint=<folder>/<endpoint> --port=<port>

where <dir> – (optional, default current directory) the working directory for stepzen assets.

<folder>/<endpoint> – (optional, will prompt if not supplied) the folder/endpoint to deploy to.

<port> – (optional, default 5000) the port number to use for the graphiql explorer

For example:

stepzen start --dir=./ --endpoint=api/unhinged-toucan --port=5000

Import

Import pre-configured schemas to Your API. The list and code for the available schemas can be found on GitHub.

Usage $ stepzen import <name> --dir=<dir>

where <name> – the name of the generator to import <dir> – (optional) the directory to which the schema will be imported

For example, running stepzen import cloudinary results in prompts to provide configuration and imports a schema that connects to Cloudinary for media.

? What would you like your endpoint to be called? api/suggestion-here
Created /Users/username/foldername/stepzen.config.json
Downloading from StepZen...... done
? What is the api_key for your cloudinary API? [input is hidden]
? What is the api_secret for your cloudinary API? [input is hidden]
? What is the cloud_name for your cloudinary API? [input is hidden]
Successfully imported 1 schemas from StepZen

Your stepzen folder will then look something like:

🐒➔ tree
    .
    ├── index.graphql
    ├── stepzen.config.json
    ├── config.yaml
    └── cloudinary
        ├── cloudinary.graphql
        └── README.md

    1 directories, 4 files

For more information on using StepZen templates with stepzen import, check out our docs on templates.

List

List the assets of a specified type that are linked to the account currently logged in to the StepZen CLI.

Usage $ stepzen list <type>

where <type> – the type of asset to list, one of "schemas", "configurationsets"

For example,

$stepzen list configurationsets
$[
$  "api-dev/incendiary-shrimp",
$  "api-dev/solitary-kudu",
$  "api/awesome-condor",
$  "api/foolhardy-puma",
$ ]

Advanced

The following commands can be used in place of the automatic upload and deploy integrated into stepzen start when more fine-grained control is required.

Upload

Uploads assets in the current directory to StepZen.

Usage $ stepzen upload <type> <folder>/<name>

where

<type> – the type of asset to upload. This must be either "schema" or "configurationset" <folder>/<name> – the destination/name for the asset

For example, $ stepzen upload schema api/foolhardy-puma

Deploy

Deploys a GraphQL API to StepZen using assets uploaded via stepzen upload.

Usage $ stepzen deploy <folder>/<endpoint> --schema=<schema> --configurationsets=<configuration>,<configuration>,...

where <folder> – the name of the folder to deploy to <endpoint> – the endpoint name <schema> – the named schema to deploy <configuration> – a named configuration to use for the deployment

E.g., $ stepzen deploy api/foolhardy-puma --schema=api/foolhardy-puma --configurationsets=cat_config,country_config,...

This allows you can tell StepZen to use different schemas or configurationsets when it deploys to your endpoint. Using stepzen start, StepZen will continue using the original assets you first deployed to the endpoint on every file save. This allows you to specify the assets rather than StepZen introspecting the assets.