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.
Display Help for StepZen
stepzen help <command>
<command> – (optional) is a command name for which to display help, for example,
stepzen help login
Login to StepZen
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 of StepZen
The stepzen cli will discard your login information.
$ stepzen logout $ You have been logged out.
$ stepzen start $ ? What would you like your endpoint to be called? (api/unhinged-toucan)
This command does three things:
- Deploys the code in the current directory (or the directory provided via the
--diroption) to the specified endpoint on StepZen.
- Watches the directory for changes and automatically deploys them to the endpoint specified.
- 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
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>
<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
stepzen start --dir=./ --endpoint=api/unhinged-toucan --port=5000
Import pre-configured schemas to Your API. The list and code for the available schemas can be found on GitHub.
$ stepzen import <name> --dir=<dir>
<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
List the assets of a specified type that are linked to the account currently logged in to the StepZen CLI.
$ stepzen list <type>
<type> – the type of asset to list, one of "schemas", "configurationsets"
$stepzen list configurationsets $[ $ "api-dev/incendiary-shrimp", $ "api-dev/solitary-kudu", $ "api/awesome-condor", $ "api/foolhardy-puma", $ ]
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.
Uploads assets in the current directory to StepZen.
$ stepzen upload <type> <folder>/<name>
<type> – the type of asset to upload. This must be either "schema" or "configurationset"
<folder>/<name> – the destination/name for the asset
$ stepzen upload schema api/foolhardy-puma
Deploys a GraphQL API to StepZen using assets uploaded via
$ stepzen deploy <folder>/<endpoint> --schema=<schema> --configurationsets=<configuration>,<configuration>,...
<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
$ 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.