Configuring the CLI

Configure the API Connect for GraphQL CLI for testing and deployment.

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

When you run stepzen start to deploy and test your schema, a configuration file named stepzen.config.json is created in your working directory. You typically do not need to modify this file; however, if you want to customize the configuration, you can make the changes described in the following sections.

Modifying the directory name and endpoint name of a deployed schema

When you first run stepzen start for a schema, the CLI prompts for a directory name and endpoint name for the deployed schema, which must be provided using the following the format: directory_name/endpoint_name.

You can choose whatever you like for either value, keeping in mind that this determines the GraphQL endpoint URL that you'll call to access this API. For example, if your account name is brian and you supply a directory name/endpoint name of api/my_first_endpoint, then the GraphQL endpoint URL to query the deployed schema will be https://brian.<domain>/api/my_first_endpoint/__graphql.

The endpoint name is stored in the stepzen.config.json file as the endpoint value:

{
  "endpoint": "api/my_first_endpoint"
}

On subsequent stepzen start runs in the same directory, the CLI will reference this file to get the directory name and endpoint name to deploy to the GraphQL server. To change either of these, manually update the file.

For example, if you change the value to the following:

{
  "endpoint": "api/my_second_endpoint"
}
then running stepzen start will deploy to:
https://brian.<domain>/api/my_second_endpoint/__graphql
Note that:
  • This will not remove the deployed endpoint at api/my_first_endpoint.
  • This will overwrite any existing endpoint at api/my_second_endpoint.

Changing the root directory for GraphQL schema files

By default, stepzen.config.json only contains the endpoint value, but you can add a value for root to customize where the CLI looks for the .graphql schema files.

For example, a common pattern is to build your schema files in a subdirectory of your web application such as /schema or /essentials. If you would like to be able to run stepzen start from the root of your application and you have the schema files in an essentials folder, you can add a root property to

{
  "endpoint": "api/my_first_endpoint",
  "root": "essentials"
}

Running stepzen start from the directory will now look for the .graphql files in the /essentials directory.