Skip to main content

CLI commands explained

The Superface CLI is the starting point for every use case you define, this guide presents an overview of all the commands, what they do and what files they create.

If you don't have the CLI installed yet, you can do so with the commands below. If you aren't on macOS, or you don't use Homebrew, you'll need Node.js version 18 or higher to use it.

Install with Homebrew
brew install superfaceai/cli/superface

After installing the CLI, the first command you should run is:

superface login​

Authenticates the CLI with your Superface account so that you can use the Superface AI engine to create and store your Comlink profiles, as well as track metrics around their usage.

superface prepare​

The prepare command will index the documentation for further AI processing.

It expects either a URL or file path to an Open API Specification document for the API you want to work with.

It will pass the documentation to the Superface AI which will extract key information to create a Comlink provider:

  • The base URL
  • Any parameters required to make an API request
  • What security scheme is required

File created:

superface/<api-name>.provider.json

A new directory named superface will be created at this point, there you will find the first file the CLI creates; the provider.json.

superface new​

The new command creates a new comlink for a provider based on a natural language query provided by you.

It is used when you are ready to define the use case you want to achieve with an API. For example:

superface new resend "send an email"

This command will instruct the Superface AI to look through the documentation you supplied and to work out what requests need to be made in order to achieve your use case. The output will be a Profile file, written in the Comlink language that describes the inputs, outputs and error responses the use case requries.

File created:

superface/<profile-name>.profile

This Comlink profile is completely abstracted from the API, because of this, it can be used with multiple providers of the same type of service.

superface map​

The map command maps a Comlink profile to an API provider.

It takes the Comlink profile (generated by superface new) and your chosen provider, and creates a code template for the API execution of the use case you specified. This is called a Map, and is required later on by the Superface OneSDK.

By default this command will generate Node.js output. If you want Python instead, you can add python to the end of the command.

Files created:

superface/<profile-name>.map.js

superface/<profile-name>.<provider>.mjs or .py

superface/.env

Additionally to the map, .mjs and .env will also be created. .env is a convenience file for environment variables that you will need to use, such as API keys or tokens.

The .mjs file is a runnable code example that demonstrates how to incorporate the Comlink files, and OneSDK into your application. It is also used for testing by the following command.

superface execute​

execute will run the example application created by the CLI to test the Comlink.

It is best used to test the use case implementation for any errors. It expects a provider, and a profile as inputs and will run them with OneSDK.

This command makes real requests

The execute command will run a use case against the target API, so be careful to use non-production data when testing.

The execute command requires an additional python paramter at the end of the command in order to execute Python.

superface whoami​

Displays the user account currently logged into the CLI.

superface logout​

Will log the current user out of the CLI.

--help​

Detailed documentation is available when using the CLI by passing the --help command as a flag to any of the above commands.