StepZen is now part of IBM. For the most recent product information and updates go to
https://www.ibm.com/products/stepzen

CLI Commands

Quickly build, deploy, and test your GraphQL schema

Command Reference

This topic provides information about the following commands:

stepzen deploy

Deploy a GraphQL API to StepZen.

Usage

stepzen deploy [ENDPOINT] [--config=<config>] [--dir=<dir>]

The available parameters are as follows:

  • <ENDPOINT> – name of the GraphQL endpoint in the folder/name format (by default, uses the endpoint name from the StepZen workspace).
  • <config> – override the StepZen workspace configuration (by default, uses the config.yaml file from the StepZen workspace).
  • <dir> - path to a StepZen workspace directory (uses the current working directory by default).

For example, stepzen deploy

Another example: stepzen deploy api/foolhardy-puma --dir stepzen/workspaces/puma

Deprecated --schema and --configurationsets flags

stepzen deploy has an alternative (deprecated) form to deploy a GraphQL API from the assets earlier uploaded with stepzen upload. The StepZen CLI is moving away from the two-step "upload" + "deploy" flow to a single-step "deploy" flow, and this alternative stepzen deploy semantics will be removed in one of the future versions.

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, earlier uploaded with stepzen upload
  • <configuration> – a named configuration to use for the deployment, earlier uploaded with stepzen upload

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.

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

stepzen import

StepZen has a world-class introspection service that generates a schema for a database, a REST endpoint, or a GraphQL 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: Importing a REST endpoint

stepzen import curl [[<CURLOPTS>] <URL>] [--prefix=<prefix>] 
  [--header=<header>] [--header-param=<header-param>] 
  [--query-name=<query-name>] [--query-type=<query-type>] 
  [--path-params=<path-params>]

This command makes a request to a REST endpoint similarly to the curl utility, and creates a GraphQL schema from the response. Parameters:

  • <CURLOPTS>: curl options; the following are supported: --data, --data-raw, --data-ascii, --data-binary, --method, -X, --request, and --url.
  • <URL>: REST endpoint URL; prompted interactively if not specified.
  • <prefix>: Prefix to add to every type in the generated schema.
  • <header>: Specifies a request header to pass (e.g. -H "Authorization: apikey SecretAPIKeyValue")
  • <header-param>: Specifies a parameter in a header value. Can be formed by taking a -H, --header flag and replacing the variable part of the header value with a $paramName placeholder. Repeat this flag once for each header with a parameter. Example: 
    stepzen import curl https://example.com/api/customers \
  -H "Authorization: apikey SecretAPIKeyValue" \
  --header-param 'Authorization: apikey $apikey'
  • <query-name>: Field to add to the Query type as a way to access the imported curl endpoint.
  • <query-type>: 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.
  • <path-params> Specifies path parameters in the URL path. Can be formed by taking the original path and replacing the variable segments with $paramName placeholders. Example: 
    stepzen import curl https://example.com/users/jane/posts/12  \
  --path-params '/users/$userId/posts/$postId'

Usage: Importing a GraphQL endpoint

stepzen import graphql [ENDPOINT] [--prefix=PREFIX] 
  [--header=HEADER] [--header-param=HEADER-PARAM]

This command introspects a GraphQL endpoint and re-creates the corresponding GraphQL schema locally. Parameters:

  • <prefix>: Prefix to add to every type in the generated schema.
  • <header>: Specifies a request header to pass.
  • <header-param>: Specifies a parameter in a header value. Can be formed by taking a -H, --header flag and replacing the variable part of the header value with a $paramName placeholder. Repeat this flag once for each header with a parameter. See the previous section for an example.

Usage: Importing a SQL database

stepzen import mysql://[<USER>:<PASSWORD>@]<HOST>[:<PORT>][/<DATABASE>] 
  [--db-link-types] [--db-include=<db-include>]
 stepzen import postgresql://[<USER>:<PASSWORD>@]<HOST>[:PORT][/<DATABASE>] 
   [--db-link-types] [--db-include=<db-include>] 
   [--db-schema=<db-schema>]
 stepzen import snowflake://[<USER>:<PASSWORD>@]<SNOWFLAKE-ACCOUNT-ID>[/DATABASE][?warehouse=<WAREHOUSE>]
   [--db-link-types] [--db-include=<db-include>]
   [--db-schema=<db-schema>]

This command introspects the tables of a MySQL, PostgreSQL or Snowflake database, and creates the corresponding GraphQL schema. Parameters:

  • <USER>: Database user name.
  • <PASSWORD>: Database password.
  • <HOST>: Database host.
  • <PORT>: Database port (default for MySQL/PostgreSQL if omitted).
  • <SNOWFLAKE-ACCOUNT-ID>: Snowflake account identifier in the org.account or org-account format. Check the Snowflake documentation for details.
  • <DATABASE>: Database name.
  • <WAREHOUSE>: Snowflake warehouse.
  • --db-link-types Automatically link types based on foreign key relationships using @materializer
  • <db-include>: Whether to introspect tables, views, or both; one of tables-only, views-only or tables-and-views.
  • <db-schema>: PostgreSQL schema to import tables from.

<USER>, <PASSWORD>, <HOST> and <DATABASE> are required for access to the database. (When importing a Snowflake database a <SNOWFLAKE-ACCOUNT-ID> and <WAREHOUSE> are required instead of <HOST>). If any one is omitted from the command line, they will be prompted for interactively.

Common parameters

In addition to the above schema-specific parameters, the following are available for all import schemas:

  • --name=<name>: 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=<dir>: StepZen workspace directory (uses the current working directory by default).

stepzen init

Initialize a StepZen workspace in the current directory.

Usage

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

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:

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

stepzen login

Log in to StepZen.

Usage

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

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

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

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

stepzen logout

Log out of StepZen.

Usage

stepzen logout

The StepZen CLI discards your login information.

stepzen logout
You have been logged out.

stepzen request

Send a GraphQL request to a StepZen endpoint and print the response, using the API key and the target endpoint from the current StepZen workspace.

We use the shorthand term query as it is commonly used. However, a request consists of a GraphQL document, optional variables, and an optional operation name. The document passed in the QUERY argument may contain either a single anonymous or named GraphQL query, mutation, or subscription operation, or multiple named query, mutation, and/or subscription operations. In the latter case an operation name is required to select the operation to be executed.

Usage

stepzen request QUERY [-H,--header=<header>] [--dir=<dir>] [--endpoint=<endpoint>] [--operation-name=<operation-name>] [--var=<var>] [--var-file=<var-file>]

For example:

stepzen request '{ user(id: "u123") { email } }'

The available parameters are as follows:

  • <QUERY>: GraphQL document containing either a single anonymous or named GraphQL query, mutation, or subscription operation, or multiple named query, mutation, and/or subscription operations.
  • <header> (optional): Add an additional HTTP header to the request. This is useful for schemas where @rest or @graphql directives enable header forwarding with forwardheaders (e.g. -H "X-API-Token: SecretAPIToken").
  • <dir>(optional): Path to a StepZen workspace directory (uses the current working directory by default).
  • <endpoint> (optional): Name of the GraphQL endpoint in the folder/name format (by default, uses the endpoint name from the StepZen workspace).
  • <operation-name>: Name of the GraphQL operation to execute (required if QUERY contains multiple named operations).
  • <var> (optional): Add a GraphQL request variable in the name=value format (e.g. --var 'search=space ninja' --var limit=5).
  • <var-file> (optional): Add a GraphQL request variables from a JSON file (e.g. --var-file variables.json).

Examples

Execute an inline query with 2 variables:

stepzen request 'query OrdersQuery(
    $search: String!,
    $limit: Int
  ) {
    orders(search: $search, limit: $limit) {
      id createdAt
    }
  }' \
  --var 'search=space ninja' \
  --var limit=5

Execute the AuthQuery operation from a local request.graphql file, using the variables from a vars.json file:

stepzen request "$(cat request.graphql)" \
  --operation-name AuthQuery \
  --var-file vars.json

stepzen service

Manage the local StepZen service instance (requires Docker).

You can use a local StepZen service instance instead of the StepZen cloud to develop and test GraphQL endpoints locally. This way you can try StepZen out without giving the StepZen cloud access to your data sources and API endpoints.

Local StepZen service instances are not suitable for production use. See Run StepZen in Docker for Local Development for more information and examples.

Usage

stepzen service [<action>] [--dsn=<DSN>] [--port=<port>] [--prompt] [--reset-auto]

For example:

stepzen service start

The available parameters are as follows:

  • <action> (optional): action on the local StepZen service instance: start, stop, upgrade. If no action is provided, print the service status and exit.
    • start start a local StepZen service instance in a Docker container This command pulls the latest StepZen service instance Docker image so that the version of StepZen you run locally is the same as the one running on stepzen.net.
    • stop stop the local StepZen service instance (if running) This command deletes the Docker container with the StepZen service instance, but all your endpoints are persistently stored in the metadata database. They remain available when running stepzen service start next time.
    • upgrade upgrade the local StepZen service instance if it is running This command checks if a newer version of the StepZen service instance Docker image is available, and if it is then stops and deletes the currently running container, pulls the latest image, and starts it. All endpoints are preserved.
  • <DSN> (optional): a Data Source Name (DSN) string of a StepZen metadata database, e.g. postgres://user:password@172.17.0.1:5432/zenctl. If not provided, StepZen CLI automatically creates a local Docker container with a clean PostgreSQL database and uses it as a metadata storage.
  • <port> (optional): override the TCP port on which the local StepZen service instance listens for connections (the default is 9000).
  • --prompt (optional): when no DSN is provided, open an interactive prompt for metadata database connection details instead of automatically creating a local Docker container for metadata storage.
  • --reset-auto (optional): Recreate the automatically-managed local Docker container for metadata storage. Note: all existing endpoints will be deleted and you will be 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 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:

Deploying api/endpoint-name to StepZen... done in 2.3s 🚀
  ✓ 🔐 https://username.stepzen.net/api/sample-api/__graphql
  ✓ 🔐 wss://username.stepzen.net/stepzen-subscriptions/api/sample-api/__graphql (subscriptions)

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
   https://dashboard.stepzen.com/explorer?endpoint=api%2Fsample-api

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

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, port, and the type of dashboard.

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

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.
  • --dashboard=web|local|none (optional, default web): Which GraphiQL dashboard to use to explore the deployed endpoint: start, stop, upgrade. If no action is provided, print the service status and exit.
    • web (default) uses the web-based GraphiQL dashboard at https://dashboard.stepzen.com/explorer
    • local starts a local GraphiQL dashboard on localhost:5001 (change the port with the --port flag)
    • none do not use a local GraphiQL at all

For example:

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

This will deploy and run the GraphQL API in the directory ./ on the endpoint api/unhinged-toucan, and expose a local GraphiQL dashboard on http://localhost:5005.

stepzen upload

Upload a schema or a configuration set to StepZen.

NOTE stepzen upload is deprecated in favor of stepzen deploy. StepZen CLI is moving away from a two-step "upload" + "deploy" flow to a single-step "deploy" flow.

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 whoami

View your StepZen credentials.

Usage

stepzen whoami

The StepZen CLI displays your credentials.

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