CLI command reference

Use the CLI (command line interface) to build, deploy, and test GraphQL schemas.

Note: StepZen was acquired by IBM in 2023 and renamed to API Connect for GraphQL. Some artifacts still use the StepZen name.

stepzen deploy

Deploy a GraphQL API or schema to the API Connect for GraphQL GraphQL server.

Deploying a GraphQL API

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

The available parameters are as follows:

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

For example, stepzen deploy

Another example:

stepzen deploy api/foolhardy-puma --dir stepzen/workspaces/puma

Deploying a schema

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 name of the schema to deploy
<configuration> – the name of the 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 use different schemas or configuration sets when it deploys to your endpoint. Using stepzen start, API Connect for GraphQL continues using the original assets you first deployed to the endpoint on every file save. This allows you to specify the assets rather than API Connect for GraphQL introspecting the assets.

`stepzen help`

stepzen help <command>

Displays help for the API Connect for GraphQL CLI.

The available parameters are as follows:

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

`stepzen import`

Introspect a backend data source and generate a schema for a database, a REST endpoint, or a GraphQL endpoint.

Use the stepzen import command to generate 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 own GraphQL API.

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'
```

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.

Importing a SQL database

MySQL:

stepzen import mysql://[<USER>:<PASSWORD>@]<HOST>[:<PORT>][/<DATABASE>] 
  [--db-link-types] [--db-include=<db-include>]

PostgreSQL:

 stepzen import postgresql://[<USER>:<PASSWORD>@]<HOST>[:<PORT>][/<DATABASE>] 
   [--db-link-types] [--db-include=<db-include>] 
   [--db-schema=<db-schema>]

Db2:

stepzen import db2 jdbc:db2://<host>:<port>/<database>:user=<user>;password=<password>;sslConnection=<true/false>;currentSchema=<schema>;

Snowflake:

 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, Db2, PostgreSQL or Snowflake database, and creates the corresponding GraphQL schema. Parameters:

<USER>: Database user name.
<PASSWORD>: Database password.
<HOST>: Database host.
<PORT>: Database port (uses the default for MySQL/PostgreSQL/Db2 if omitted).
<SNOWFLAKE-ACCOUNT-ID>: Snowflake account identifier in the org.account or org-account format. See 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 of these values is omitted from the command line, it will be prompted for interactively.

Common 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 for example, curl-01/, curl-02/, and so on).
--dir=<dir>: The workspace directory (uses the current working directory by default).

`stepzen init`

stepzen init

Initialize a workspace in the current directory.

`stepzen list`

stepzen list <type>

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

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`

stepzen login -a <account> <domain>

where:

<account> is the username of the account you want to log in to.
<domain> is the domain where is installed.

For example, if the account is production and the domain is graphserver.apps.my-rosa-cluster.abcd.p1 then the login command looks like the following example:

stepzen login -a production graphserver.apps.my-rosa-cluster.abcd.p1

When prompted, enter the admin key for the account you are logging into.

The CLI will log in to the following URL: https://stepzen.<domain>

For example: https://stepzen.graphserver.apps.my-rosa-cluster.abcd.p1

By default, API Connect for GraphQL uses a public introspection service, hosted by IBM. If your administrator deployed an on-premises introspection service, pass it as a parameter to the login command as in the following example:

stepzen login -a <account> <domain> --introspection stepzen-introspection.<domain>

While you remained logged in, all introspection requests (stepzen import commands) will go to your on-premises service instead of to the public service.

`stepzen logout`

stepzen logout

Log out of API Connect for GraphQL.

The CLI discards your login information.

stepzen logout

You have been logged out.

`stepzen request`

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

Send a GraphQL request to an endpoint and print the response, using the API key and the target endpoint from the current 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 might contain either a single anonymous or named GraphQL query, mutation, or subscription operation, or multiple named query, mutation, or subscription operations.

If the document includes multiple operations, then an operation name is required to select the operation to be executed; 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 for example, -H "X-API-Token: SecretAPIToken").
<dir>(optional): Path to a 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 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).

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

Example: 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`

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

Manage a local GraphQL server running in Docker.

You can use a local server to develop and test GraphQL endpoints locally. This way you can try API Connect for GraphQL with locally controlled data sources and API endpoints. The local server is only for testing and cannot be used for production. See Using Docker for local API development for more information and examples.

For example:

stepzen service start

The available parameters are as follows:

<action> (optional): action on the local GraphQL server: start, stop, upgrade. If no action is provided, print the server status and exit.
- start: starts a local GraphQL server in a Docker container. This command pulls the latest local GraphQL server Docker image so your local server matches the current version of API Connect for GraphQL deployment.
- stop: stops the local GraphQL server instance (if running) This command deletes the Docker container with the local GraphQL server, but all your endpoints are persistently stored in the metadata database. They remain available when you next start the local GraphQL server.
- upgrade: upgrades the local GraphQL server if it is running. This command checks if a newer version of the local GraphQL server Docker image is available, and if it is: stops and deletes the currently running container, pulls the latest image, and starts it. All endpoints are preserved.
- If no action is provided, print the service status and exit.
Flags
- -h, --help
  shows CLI help
- --driver-path=<value> (optional) : mounts a local directory containing additional JDBC drivers to the API Connect for GraphQL container for the introspection service. This setup is necessary when JDBC driver licenses prevent the distribution of certain drivers (such as those for Db2 and Oracle) with the API Connect for GraphQL Docker image.
  Example:
```
stepzen service start --driver-path "path1" --driver-path "path2"
```
- --<dsn>=<value> (optional): a Data Source Name (DSN) string of an API Connect for GraphQL metadata database, such as:
```
postgres://user:password@172.17.0.1:5432/zenctl
```
  If not provided, the CLI automatically creates a local Docker container with a clean PostgreSQL database and uses it as a metadata storage.
- --non-interactive: disables all interactive prompts
- --<port>=<value> (optional): override the TCP port on which the local GraphQL server listens for connections (the default is 9000).
- --prompt (optional): when no DSN is provided, opens 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`

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

Initialize an endpoint. 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 the API Connect for GraphQL server.
Watches the directory for changes and automatically deploys them to the endpoint specified.
Opens a browser window with the embedded GraphiQL tool, which enables you to test your API by exploring the queries and types available and querying the API running on API Connect for GraphQL.

The available parameters are as follows:

<dir> (optional, default current directory): Working directory for API Connect for GraphQL 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 is web): Which GraphiQL dashboard to use to explore the deployed endpoint.
- 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.

When you run this command, it 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...

The displayed endpoint URL is used by your applications to access your 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.

(Deprecated) `stepzen upload`

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

Upload a schema or a configuration set to the GraphQL server.

Note: stepzen upload is deprecated in favor of stepzen deploy, which includes the upload operation instead of requiring a separate upload step.

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`

stepzen whoami

View your Admin key and API key.

The 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

CLI command reference

stepzen deploy

stepzen help

stepzen import

stepzen init

stepzen list

stepzen login

stepzen logout

stepzen request

stepzen service

stepzen start

(Deprecated) stepzen upload

stepzen whoami

`stepzen help`

`stepzen import`

`stepzen init`

`stepzen list`

`stepzen login`

`stepzen logout`

`stepzen request`

`stepzen service`

`stepzen start`

(Deprecated) `stepzen upload`

`stepzen whoami`