CLI Commands

Quickly build, deploy, and test your GraphQL schema

Command Reference

This topic provides information about the following commands:

stepzen help

Displays help for StepZen.

Usage

stepzen help <command>

The available parameters are as follows:

<command> (optional): Command name for which to display help (e.g. stepzen help login).

Usage

stepzen login

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

stepzen logout

Log out of StepZen.

Usage

stepzen logout

The StepZen CLI discards your login information.

stepzen logout

You have been logged out.

stepzen start

Initialize an endpoint.

Usage

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 --dir option) to the specified endpoint on StepZen.
Watches the directory for changes and automatically deploys them to the endpoint specified.
Opens a browser window with StepZen's Schema Explorer that enables you to test your API by exploring the queries and types available and querying the API running on StepZen.

When launched, the command line returns the following information:

Deploying api/sample-api to StepZen... done in 7.9s 🚀

Your API url is  https://mojave.stepzen.net/api/sample-api/__graphql

You can test your hosted API with cURL:

curl https://mojave.stepzen.net/api/sample-api/__graphql \
   --header "Authorization: Apikey {{insert yours from https://stepzen.com/account}}" \
   --header "Content-Type: application/json" \
   --data '{"query": "your graphql query"}'

or explore it with GraphiQL at  http://localhost:5001/api/sample-api

Watching ~/folder/file for GraphQL changes...

Note: The provided endpoint URL is used by your applications to access your StepZen GraphQL API.

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

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

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

Here's another example:

Watching ~/folder for GraphQL changes

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

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

Your local schema has the following GraphQL errors:

Error: Unknown type "Integer".

This error occurs when the GraphQL type is 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>

The available parameters are as follows:

<dir> (optional, default current directory): Working directory for StepZen assets.
<folder>/<endpoint> (optional, will prompt if not supplied): Folder/endpoint to deploy to.
<port> (optional, default 5001): Port number to use for the GraphiQL explorer.

For example:

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

stepzen import

StepZen has a world-class introspection service that generates a schema for a database or a REST endpoint.

Take advantage of this by using the stepzen import command to autogenerate a GraphQL API that uses an external data source or an API endpoint as its data source. This can be a convenient alternative to writing your GraphQL API from scratch.

Usage

Imports a schema.

stepzen import <import option> <URL> <name> -—header <header> --dir=<dir> --prefix=<prefix> --query-name=<query-name> --query-type=<query-type>

The available parameters are as follows:

<import option> (required): curl, graphql, mysql, postgresql.
<name> (optional): Subdirectory inside the workspace directory to save the auto-generated schema files. Use to override the name of the subdirectory created during the generation (defaults to the name of the schema type: curl, mysql, etc.). The command will automatically add a counter to the subdirectory name if a directory with that name already exists (e.g., curl-01/, curl-02/, etc.).
<dir> (optional): StepZen workspace directory (uses the current working directory by default).
<prefix> (optional): curl Prefix to add every type in the generated schema.
<query-name> (optional): curl Property name to add to the Query type as a way to access the imported cURL endpoint.
<query-type> (optional): Name for the type returned by the cURL endpoint in the generated schema. The name specified by --query-type is not prefixed by --prefix if both flags are present.
<URL>: curl URL for the cURL request.
--header: curl HTTP request header (e.g. Content-Type: application/json). Multiple headers can be added to the call.
--root-type: curl Name of the Root type in the generated schema.

For example, running stepzen import mysql results in prompts to provide configuration and auto-generates a schema introspected from the connected database. stepzen import curl results in prompts to provide information to connect to and introspect a schema from a REST API, while stepzen import graphql does the same for a GraphQL API.

stepzen list

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

Usage

stepzen list <type>

The available parameters are as follows:

<type>: Type of asset to list. Can be set to schemas or 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.

stepzen upload

Uploads assets in the current directory to StepZen.

Usage

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

The available parameters are as follows:

<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

stepzen deploy

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

Usage

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

The available parameters are as follows:

<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

For example, stepzen deploy api/foolhardy-puma --schema=api/foolhardy-puma --configurationsets=cat_config,country_config,...

This allows you to tell StepZen to use different schemas or configurationsets when it deploys to your endpoint. Using stepzen start, StepZen continues 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.

Join the
StepZen Discord