Command Reference

This topic provides information about the following commands:

• stepzen help
• stepzen login
• stepzen logout
• stepzen start
• stepzen import
• stepzen init
• stepzen list
• stepzen upload
• stepzen deploy
• stepzen whoami

stepzen help

Displays help for StepZen.

Usage

Copy
stepzen help <command>

The available parameters are as follows:

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

stepzen login

Log in to StepZen.

Usage

Copy
stepzen login

• <public> (optional): Logs user into an anonymous account.

Without the --public flag, the cli prompts for your account name and admin key.

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

Non-interactive login (CI/CD)

For authentication without interactive prompts, the stepzen login command has a non-interactive mode

Copy
stepzen login --account <account name> --adminkey <admin key>

stepzen logout

Log out of StepZen.

Usage

Copy
stepzen logout

The StepZen CLI discards your login information.

Copy
stepzen logout

Copy
You have been logged out.

stepzen start

Initialize an endpoint.

Usage

Copy
stepzen start

Copy
? 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 flag) 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:

Copy
Deploying api/endpoint-name to StepZen... done in 2.4s 🚀

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

You can test your hosted API with curl:

curl https://username.stepzen.net/api/endpoint-name/__graphql \
   --header "Authorization: Apikey $(stepzen whoami --apikey)" \
   --header "Content-Type: application/json" \
   --data '{"query": "your graphql query"}'

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

Your API url is https://username.stepzen.net/api/endpoint-name/__graphql

Watching ~/folder 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:

Copy
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:

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

Copy
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:

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

Copy
stepzen import <import option> <URL> <name> -—header <header> --dir=<dir> --prefix=<prefix> --query-name=<query-name> --query-type=<query-type> --db-include=<tables-only | views-only | tables-and-views>

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.
• <db-include> (optional): Should the generated GraphQL schema be based only on database views, only on tables or on both.
• <URL>: [curl] URL for the curl request.
• <header-param> (optional): Parameters in an HTTP header value (e.g. Authorization: $apikey)
• <path-params> (optional): Parameters in the curl endpoint pathname (e.g. /users/$userId/posts)
• --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 init

Initialize a StepZen workspace in the current directory.

Usage

Copy
stepzen init

stepzen list

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

Usage

Copy
stepzen list <type>

The available parameters are as follows:

<type>: Type of asset to list. Can be set to endpoints, schemas or configurationsets.

For example:

Copy
stepzen list endpoints

Copy
[
  "api-dev/incendiary-shrimp",
  "api-dev/solitary-kudu",
  "api/awesome-condor",
  "api/foolhardy-puma",
]

stepzen whoami

View your StepZen credentials.

Usage

Copy
stepzen whoami

The StepZen CLI displays your credentials.

Copy
Account: public3***9b
Admin key: public3c***9b::stepzen.io+1000::f1************************************************************a4
API key: public3***9b::stepzen.net+1000::3c************************************************************9b

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

Copy
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

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