Skip to main content

Using the CLI

This guide shows you how to set up and use the Superface CLI to work with an API provider to generate the Comlinks required to work with OneSDK in Node.js or Python.

Before you start

Superface CLI requires Node.js version 18.0.0 or newer to be installed, and Python 3.8 if generating output for Python projects.

Install & Authorize​

The Superface CLI provides all the tooling needed to author the Comlinks for your integration.

Install with Homebrew
brew install superfaceai/cli/superface

If you don't have a Superface account already, you can sign up here. You can use your account to authenticate the CLI via your browser.

superface login

Prepare a use case​

Superface accepts Open API Specification format documentation, either from local files or remote URLs as well as the URL of any documentation hosted by Readme.io.

superface prepare <url or path to local file> "<optional-provider-name>"

The minimum requirement for prepare is the URL or path to local file, however if you want to control the naming of the provider, you can do so.

Once the documentation has been indexed, you can create a profile for the use case you want to achieve.

superface new <provider-name> "your use case"

If you want to have control over the name of the Comlink profile that is created you can specify the name as part of the new command, for example:

superface new resend "send an email" resend/send-an-email

To convert the profile into the use case map and boilerplate code, run the following command and include the name of the provider and the use case profile you want to use.

By default, Node.js code will be generated, however you can use the additional python option to get Python code instead.

superface map <provider-name> <scope>/<use-case>

Test it​

The resulting code is added to the superface folder in your project. To test it you can use the execute command.

superface execute <provider> <scope>/<use-case>
Provider authentication

In many cases you also need to set up provider credentials. The CLI will inform you of the name of the variable that should be added to your development environment. To learn how to handle API credentials, see Setting provider API keys.

What files are created?​

After running all the above commands, you will find a folder named superface in your current working directory, with the following structure:

superface/
  <provider-name>.provider.json
  <scope>.<use-case>.profile
  <scope>.<use-case>.<provider-name>.map.js
  <scope>.<use-case>.<provider-name>.mjs

These files are used by OneSDK to enabled your application to communicate with the provider you are working with. <provider-name>, <scope>, and <use-case> will be replaced with real values based on the provider and use case you specified.

Additional commands​

superface whoami shows the current logged in user.

superface logout logs out the current user.

--quiet or -q flag will reduce the amount of terminal output you see.

For information on each CLI command you can run superface --help at any time.