@superfaceai/cli

CLI

Superface CLI provides access to superface tooling from the CLI.

Table of Contents

• Background
• Install
• Usage
• Security
• Support
• Development
• Maintainers
• Contributing
• License

Background

Superface (super-interface) is a higher-order API, an abstraction on top of modern APIs like GraphQL and REST. Superface gives you the one interface to discover, connect, and query any capabilities available via conventional APIs.

Through its focus on application-level semantics, Superface decouples the clients from servers, enabling fully autonomous evolution. As such, it minimizes the code base as well as errors and downtimes while providing unmatched resiliency and redundancy.

Superface allows for switching providers at runtime in milliseconds with no development cost. Furthermore, Superface decentralizes the composition and aggregation of integrations, and thus creates an Autonomous Integration Mesh.

Motivation behind Superface is nicely described in this video from APIdays conference.

You can get more information at https://superface.ai and https://superface.ai/docs.

Install

To install this package, just install the cli globally using one of the following commands:

# if using yarn
yarn global add @superfaceai/cli
# otherwise
npm install --global @superfaceai/cli

Or you can use NPX directly with Superface CLI commands:

npx @superfaceai/cli [command]
# eg.
npx @superfaceai/cli install [profileId eg. communication/send-email]

Usage

• superface check
• superface compile
• superface configure PROVIDERNAME
• superface create:map PROFILEID PROVIDERNAME
• superface create:mock-map PROFILEID
• superface create:mock-map-test PROFILEID
• superface create:profile PROFILEID
• superface create:provider PROVIDERNAME
• superface create:test PROFILEID PROVIDERNAME
• superface init [NAME]
• superface install [PROFILEID]
• superface lint
• superface login
• superface logout
• superface publish DOCUMENTTYPE
• superface whoami

superface check

Checks all maps, profiles and providers locally linked in super.json. Also can be used to check specific profile and its maps, in that case remote files can be used.

USAGE
  $ superface check [-q] [--noColor] [--noEmoji] [-h] [--profileId <value>] [--providerName <value>] [-s
    <value>] [-j] [-f]

FLAGS
  -f, --failOnWarning     When true command will fail on warning
  -h, --help              show CLI help
  -j, --json              Formats result to JSON
  -q, --quiet             When set to true, disables the shell echo output of action.
  -s, --scan=<value>      When number provided, scan for super.json outside cwd within range represented by this number.
  --noColor               When set to true, disables all colored output.
  --noEmoji               When set to true, disables displaying emoji in output.
  --profileId=<value>     Profile Id in format [scope/](optional)[name]
  --providerName=<value>  Name of provider.

DESCRIPTION
  Checks all maps, profiles and providers locally linked in super.json. Also can be used to check specific profile and
  its maps, in that case remote files can be used.
  Command ends with non zero exit code if errors are found.

EXAMPLES
  $ superface check

  $ superface check -f

  $ superface check --profileId starwars/character-information

  $ superface check --profileId starwars/character-information --providerName swapi

  $ superface check --profileId starwars/character-information --providerName swapi -j

  $ superface check --profileId starwars/character-information --providerName swapi -s 3

  $ superface check --profileId starwars/character-information --providerName swapi -q

See code: src/commands/check.ts

superface compile

Compiles locally linked maps and profiles in super.json. When running without --profileId flag, all locally linked files are compiled. When running with --profileId, a single local profile source file, and all its local maps are compiled. When running with --profileId and --providerName, a single local profile and a single local map are compiled.

USAGE
  $ superface compile [-q] [--noColor] [--noEmoji] [-h] [--profileId <value>] [--providerName <value>] [-s
    <value>] [--onlyProfile | --onlyMap]

FLAGS
  -h, --help              show CLI help
  -q, --quiet             When set to true, disables the shell echo output of action.
  -s, --scan=<value>      When number provided, scan for super.json outside cwd within range represented by this number.
  --noColor               When set to true, disables all colored output.
  --noEmoji               When set to true, disables displaying emoji in output.
  --onlyMap               Compile only a map/maps
  --onlyProfile           Compile only a profile/profiles
  --profileId=<value>     Profile Id in format [scope/](optional)[name]
  --providerName=<value>  Name of provider. This argument is used to compile map

DESCRIPTION
  Compiles locally linked maps and profiles in `super.json`. When running without `--profileId` flag, all locally linked
  files are compiled. When running with `--profileId`, a single local profile source file, and all its local maps are
  compiled. When running with `--profileId` and `--providerName`, a single local profile and a single local map are
  compiled.

EXAMPLES
  $ superface compile

  $ superface compile --profileId starwars/character-information --profile

  $ superface compile --profileId starwars/character-information --profile -q

  $ superface compile --profileId starwars/character-information --providerName swapi --onlyMap

  $ superface compile --profileId starwars/character-information --providerName swapi --onlyProfile

See code: src/commands/compile.ts

superface configure PROVIDERNAME

Configures new provider and map for already installed profile. Provider configuration is dowloaded from a Superface registry or from local file.

USAGE
  $ superface configure [PROVIDERNAME] -p <value> [-q] [--noColor] [--noEmoji] [-h] [--write-env] [-f]
    [--localProvider <value>] [--localMap <value>] [--mapVariant <value>]

ARGUMENTS
  PROVIDERNAME  Provider name.

FLAGS
  -f, --force              When set to true and when provider exists in super.json, overwrites them.
  -h, --help               show CLI help
  -p, --profile=<value>    (required) Specifies profile to associate with provider
  -q, --quiet              When set to true, disables the shell echo output of action.
  --localMap=<value>       Optional filepath to .suma map file
  --localProvider=<value>  Optional filepath to provider.json file
  --mapVariant=<value>     Optional map variant
  --noColor                When set to true, disables all colored output.
  --noEmoji                When set to true, disables displaying emoji in output.
  --write-env              When set to true command writes security variables to .env file

DESCRIPTION
  Configures new provider and map for already installed profile. Provider configuration is dowloaded from a Superface
  registry or from local file.

EXAMPLES
  $ superface configure twilio -p send-sms

  $ superface configure twilio -p send-sms -q

  $ superface configure twilio -p send-sms -f

  $ superface configure twilio -p send-sms --localProvider providers/twilio.provider.json

  $ superface configure twilio -p send-sms --localMap maps/send-sms.twilio.suma

  $ superface configure twilio -p send-sms --mapVariant generated

See code: src/commands/configure.ts

superface create:map PROFILEID PROVIDERNAME

Prepares map, based on profile and provider on a local filesystem. Created file contains created structure with information from profile and provider files. Before running this command you should have prepared profile (run sf prepare:profile) and provider (run sf prepare:provider)

USAGE
  $ superface create:map [PROFILEID] [PROVIDERNAME] [-q] [--noColor] [--noEmoji] [-h] [-s <value>] [-v <value>]
    [-f] [--station]

ARGUMENTS
  PROFILEID     Profile Id in format [scope](optional)/[name]
  PROVIDERNAME  Name of provider

FLAGS
  -f, --force            When set to true and when profile exists in local filesystem, overwrites them.
  -h, --help             show CLI help
  -q, --quiet            When set to true, disables the shell echo output of action.
  -s, --scan=<value>     When number provided, scan for super.json outside cwd within range represented by this number.
  -v, --variant=<value>  Variant of a map
  --noColor              When set to true, disables all colored output.
  --noEmoji              When set to true, disables displaying emoji in output.
  --station              When set to true, command will create map in folder structure of Superface station

DESCRIPTION
  Prepares map, based on profile and provider on a local filesystem. Created file contains created structure with
  information from profile and provider files. Before running this command you should have prepared profile (run sf
  prepare:profile) and provider (run sf prepare:provider)

EXAMPLES
  $ superface create:map starwars/character-information swapi --force

  $ superface create:map starwars/character-information swapi -s 3

  $ superface create:map starwars/character-information swapi --station

See code: dist/commands/create/map.ts

superface create:mock-map PROFILEID

Prepares map for mock provider on a local filesystem. Created map always returns success result example from profile file. Before running this command you should have created profile file (run sf create:profile).

USAGE
  $ superface create:mock-map [PROFILEID] [-q] [--noColor] [--noEmoji] [-h] [-s <value>] [-f] [--station]

ARGUMENTS
  PROFILEID  Profile Id in format [scope](optional)/[name]

FLAGS
  -f, --force         When set to true and when profile exists in local filesystem, overwrites them.
  -h, --help          show CLI help
  -q, --quiet         When set to true, disables the shell echo output of action.
  -s, --scan=<value>  When number provided, scan for super.json outside cwd within range represented by this number.
  --noColor           When set to true, disables all colored output.
  --noEmoji           When set to true, disables displaying emoji in output.
  --station           When set to true, command will create map in folder structure of Superface station

DESCRIPTION
  Prepares map for mock provider on a local filesystem. Created map always returns success result example from profile
  file. Before running this command you should have created profile file (run sf create:profile).

EXAMPLES
  $ superface create:mock-map starwars/character-information --force

  $ superface create:mock-map starwars/character-information -s 3

  $ superface create:mock-map starwars/character-information --station

See code: dist/commands/create/mock-map.ts

superface create:mock-map-test PROFILEID

Creates test for mock provider map on a local filesystem. Created test expects success result example from profile file. Before running this command you should have created mock provider map (run sf create:mock-map).

USAGE
  $ superface create:mock-map-test [PROFILEID] [-q] [--noColor] [--noEmoji] [-h] [-s <value>] [-f] [--station]

ARGUMENTS
  PROFILEID  Profile Id in format [scope](optional)/[name]

FLAGS
  -f, --force         When set to true and when profile exists in local filesystem, overwrites them.
  -h, --help          show CLI help
  -q, --quiet         When set to true, disables the shell echo output of action.
  -s, --scan=<value>  When number provided, scan for super.json outside cwd within range represented by this number.
  --noColor           When set to true, disables all colored output.
  --noEmoji           When set to true, disables displaying emoji in output.
  --station           When set to true, command will create map in folder structure of Superface station

DESCRIPTION
  Creates test for mock provider map on a local filesystem. Created test expects success result example from profile
  file. Before running this command you should have created mock provider map (run sf create:mock-map).

EXAMPLES
  $ superface create:mock-map-test starwars/character-information --force

  $ superface create:mock-map-test starwars/character-information -s 3

  $ superface create:mock-map-test starwars/character-information --station

See code: dist/commands/create/mock-map-test.ts

superface create:profile PROFILEID

creates profile file on local filesystem and links it to super.json.

USAGE
  $ superface create:profile [PROFILEID] [-q] [--noColor] [--noEmoji] [-h] [-v <value>] [-u <value>] [-s <value>]
    [-f] [--station]

ARGUMENTS
  PROFILEID  Profile Id in format [scope](optional)/[name]

FLAGS
  -f, --force               When set to true and when profile exists in local filesystem, overwrites them.
  -h, --help                show CLI help
  -q, --quiet               When set to true, disables the shell echo output of action.
  -s, --scan=<value>        When number provided, scan for super.json outside cwd within range represented by this
                            number.
  -u, --usecase=<value>...  Usecases that profile contains
  -v, --version=<value>     [default: 1.0.0] Version of a profile
  --noColor                 When set to true, disables all colored output.
  --noEmoji                 When set to true, disables displaying emoji in output.
  --station                 When set to true, command will create profile in folder structure of Superface station

DESCRIPTION
  creates profile file on local filesystem and links it to super.json.

EXAMPLES
  $ superface create:profile starwars/character-information --force

  $ superface create:profile starwars/character-information -s 3

  $ superface create:profile starwars/character-information --station

See code: dist/commands/create/profile.ts

superface create:provider PROVIDERNAME

Prepares provider on a local filesystem and adds it to super.json. You do not have to touch super.json or created provider.json file after running this command.

USAGE
  $ superface create:provider [PROVIDERNAME] [-q] [--noColor] [--noEmoji] [-h] [-s <value>] [-f] [--station]

ARGUMENTS
  PROVIDERNAME  Name of provider

FLAGS
  -f, --force         When set to true and when profile exists in local filesystem, overwrites them.
  -h, --help          show CLI help
  -q, --quiet         When set to true, disables the shell echo output of action.
  -s, --scan=<value>  When number provided, scan for super.json outside cwd within range represented by this number.
  --noColor           When set to true, disables all colored output.
  --noEmoji           When set to true, disables displaying emoji in output.
  --station           When set to true, command will create map in folder structure of Superface station

DESCRIPTION
  Prepares provider on a local filesystem and adds it to super.json. You do not have to touch super.json or created
  provider.json file after running this command.

EXAMPLES
  $ superface prepare:provider swapi --force

  $ superface prepare:provider swapi -s 3

  $ superface prepare:provider swapi --station

See code: dist/commands/create/provider.ts

superface create:test PROFILEID PROVIDERNAME

Creates test file for specified profile and provider. Examples in profile are used as an input and @superfaceai/testing library is used to orchestrate tests.

USAGE
  $ superface create:test [PROFILEID] [PROVIDERNAME] [-q] [--noColor] [--noEmoji] [-h] [-s <value>] [-f]
    [--station]

ARGUMENTS
  PROFILEID     Profile Id in format [scope](optional)/[name]
  PROVIDERNAME  Name of provider

FLAGS
  -f, --force         When set to true and when profile exists in local filesystem, overwrites them.
  -h, --help          show CLI help
  -q, --quiet         When set to true, disables the shell echo output of action.
  -s, --scan=<value>  When number provided, scan for super.json outside cwd within range represented by this number.
  --noColor           When set to true, disables all colored output.
  --noEmoji           When set to true, disables displaying emoji in output.
  --station           When set to true, command will create map in folder structure of Superface station

DESCRIPTION
  Creates test file for specified profile and provider. Examples in profile are used as an input and
  @superfaceai/testing library is used to orchestrate tests.

EXAMPLES
  $ superface create:test starwars/character-information swapi

  $ superface create:test starwars/character-information swapi --station

  $ superface create:test starwars/character-information swapi --force

  $ superface create:test starwars/character-information swapi -q

See code: dist/commands/create/test.ts

superface init [NAME]

Initializes superface local folder structure.

USAGE
  $ superface init [NAME] [-q] [--noColor] [--noEmoji] [-h] [--profiles <value>] [--providers <value>] [-p]

ARGUMENTS
  NAME  Name of parent directory.

FLAGS
  -h, --help              show CLI help
  -p, --prompt            When set to true, prompt will be executed.
  -q, --quiet             When set to true, disables the shell echo output of action.
  --noColor               When set to true, disables all colored output.
  --noEmoji               When set to true, disables displaying emoji in output.
  --profiles=<value>...   Profile identifiers.
  --providers=<value>...  Provider names.

DESCRIPTION
  Initializes superface local folder structure.

EXAMPLES
  $ superface init

  $ superface init foo

  $ superface init foo --providers bar twilio

  $ superface init foo --profiles my-profile@1.1.0 another-profile@2.0 --providers osm gmaps

See code: src/commands/init.ts

superface install [PROFILEID]

Automatically initializes superface directory in current working directory if needed, communicates with Superface Store API, stores profiles and compiled files to a local system. Install without any arguments tries to install profiles and providers listed in super.json

USAGE
  $ superface install [PROFILEID] [-q] [--noColor] [--noEmoji] [-h] [-p <value>] [-f] [-l] [-s <value>]

ARGUMENTS
  PROFILEID  Profile identifier consisting of scope (optional), profile name and its version.

FLAGS
  -f, --force                 When set to true and when profile exists in local filesystem, overwrites them.
  -h, --help                  show CLI help
  -l, --local                 When set to true, profile id argument is used as a filepath to profile.supr file.
  -p, --providers=<value>...  Provider name.
  -q, --quiet                 When set to true, disables the shell echo output of action.
  -s, --scan=<value>          When number provided, scan for super.json outside cwd within range represented by this
                              number.
  --noColor                   When set to true, disables all colored output.
  --noEmoji                   When set to true, disables displaying emoji in output.

DESCRIPTION
  Automatically initializes superface directory in current working directory if needed, communicates with Superface
  Store API, stores profiles and compiled files to a local system. Install without any arguments tries to install
  profiles and providers listed in super.json

EXAMPLES
  $ superface install

  $ superface install sms/service@1.0

  $ superface install sms/service@1.0 --providers twilio tyntec

  $ superface install sms/service@1.0 -p twilio

  $ superface install --local sms/service.supr

See code: src/commands/install.ts

superface lint

Lints all maps and profiles locally linked in super.json. Also can be used to lint specific profile and its maps, in that case remote files can be used.Outputs the linter issues to STDOUT by default.

USAGE
  $ superface lint [-q] [--noColor] [--noEmoji] [-h] [--providerName <value>] [--profileId <value>] [-o
    <value>] [--append] [-f long|short|json] [-s <value>]

FLAGS
  -f, --outputFormat=<option>  [default: short] Output format to use to display errors and warnings.
                               <options: long|short|json>
  -h, --help                   show CLI help
  -o, --output=<value>         [default: -] Filename where the output will be written. `-` is stdout, `-2` is stderr.
  -q, --quiet                  When set to true, disables the shell echo output of action.
  -s, --scan=<value>           When number provided, scan for super.json outside cwd within range represented by this
                               number.
  --append                     Open output file in append mode instead of truncating it if it exists. Has no effect with
                               stdout and stderr streams.
  --noColor                    When set to true, disables all colored output.
  --noEmoji                    When set to true, disables displaying emoji in output.
  --profileId=<value>          Profile Id in format [scope/](optional)[name]
  --providerName=<value>       Provider name

DESCRIPTION
  Lints all maps and profiles locally linked in super.json. Also can be used to lint specific profile and its maps, in
  that case remote files can be used.Outputs the linter issues to STDOUT by default.
  Linter ends with non zero exit code if errors are found.

EXAMPLES
  $ superface lint

  $ superface lint -f long

  $ superface lint --profileId starwars/character-information

  $ superface lint --profileId starwars/character-information --providerName swapi

  $ superface lint -o -2

  $ superface lint -f json

  $ superface lint -s 3

See code: src/commands/lint.ts

superface login

Login to superface server

USAGE
  $ superface login [-q] [--noColor] [--noEmoji] [-h] [-f]

FLAGS
  -f, --force  When set to true user won't be asked to confirm browser opening
  -h, --help   show CLI help
  -q, --quiet  When set to true, disables the shell echo output of action.
  --noColor    When set to true, disables all colored output.
  --noEmoji    When set to true, disables displaying emoji in output.

DESCRIPTION
  Login to superface server

EXAMPLES
  $ superface login

  $ superface login -f

See code: src/commands/login.ts

superface logout

Logs out logged in user

USAGE
  $ superface logout [-q] [--noColor] [--noEmoji] [-h]

FLAGS
  -h, --help   show CLI help
  -q, --quiet  When set to true, disables the shell echo output of action.
  --noColor    When set to true, disables all colored output.
  --noEmoji    When set to true, disables displaying emoji in output.

DESCRIPTION
  Logs out logged in user

EXAMPLES
  $ superface logout

See code: dist/commands/logout.ts

superface publish DOCUMENTTYPE

Uploads map/profile/provider to Store. Published file must be locally linked in super.json. This command runs Check and Lint internaly to ensure quality

USAGE
  $ superface publish [DOCUMENTTYPE] --profileId <value> --providerName <value> [-q] [--noColor] [--noEmoji]
    [-h] [--dryRun] [-f] [-s <value>] [-j]

ARGUMENTS
  DOCUMENTTYPE  (map|profile|provider) Document type of published file

FLAGS
  -f, --force             Publishes without asking for any confirmation.
  -h, --help              show CLI help
  -j, --json              Formats result to JSON
  -q, --quiet             When set to true, disables the shell echo output of action.
  -s, --scan=<value>      When a number is provided, scan for super.json outside cwd within the range represented by
                          this number.
  --dryRun                Runs without sending the actual request.
  --noColor               When set to true, disables all colored output.
  --noEmoji               When set to true, disables displaying emoji in output.
  --profileId=<value>     (required) Profile Id in format [scope/](optional)[name]
  --providerName=<value>  (required) Name of the provider. This argument is used to publish a map or a provider.

DESCRIPTION
  Uploads map/profile/provider to Store. Published file must be locally linked in super.json. This command runs Check
  and Lint internaly to ensure quality

EXAMPLES
  $ superface publish map --profileId starwars/character-information --providerName swapi -s 4

  $ superface publish profile --profileId starwars/character-information --providerName swapi -f

  $ superface publish provider --profileId starwars/character-information --providerName swapi -q

  $ superface publish profile --profileId starwars/character-information --providerName swapi --dryRun

See code: src/commands/publish.ts

superface whoami

Prints info about logged in user

USAGE
  $ superface whoami [-q] [--noColor] [--noEmoji] [-h]

FLAGS
  -h, --help   show CLI help
  -q, --quiet  When set to true, disables the shell echo output of action.
  --noColor    When set to true, disables all colored output.
  --noEmoji    When set to true, disables displaying emoji in output.

DESCRIPTION
  Prints info about logged in user

EXAMPLES
  $ superface whoami

  $ sf whoami

See code: src/commands/whoami.ts

Security

Superface is not man-in-the-middle so it does not require any access to secrets that are needed to communicate with provider API. Superface CLI only prepares super.json file with authorization fields in form of environment variable. You just set correct variables and communicate directly with provider API.

You can find more information in SDK repository.

Support

If you need any additional support, have any questions or you just want to talk you can do that through our documentation page.

Development

When developing, start with cloning the repository using git clone https://github.com/superfaceai/cli.git (or git clone [e-mail]:superfaceai/cli.git if you have repository access).

After cloning, the dependencies must be downloaded using yarn install or npm install.

Now the repository is ready for code changes.

The package.json also contains scripts (runnable by calling yarn <script-name> or npm run <script-name>):

• test - run all tests
• lint - lint the code (use lint --fix to run autofix)
• format - check the code formatting (use firmat:fix to autoformat)
• prepush - run test, lint and format checks. This should run without errors before you push anything to git.

Lastly, to build a local artifact run yarn build or npm run build.

To install a local artifact globally, symlink the binary (ln -s bin/superface <target>) into one of the following folders:

• ~/.local/bin - local binaries for your user only (may not be in PATH yet)
• /usr/local/bin - system-wide binaries installed by the system administrator
• output of yarn global bin - usually the same as /use/local/bin

Note: The project needs to be built (into the dist folder) to run cli commands.

Note: You can change url of API requests by setting SUPERFACE_API_URL environment variable to desired base url.

Maintainers

• @Lukáš Valenta
• @Edward
• @Vratislav Kalenda
• @Z

Contributing

Please open an issue first if you want to make larger changes

Feel free to contribute! Please follow the Contribution Guide.

Licenses of node_modules are checked during CI/CD for every commit. Only the following licenses are allowed:

• 0BDS
• MIT
• Apache-2.0
• ISC
• BSD-3-Clause
• BSD-2-Clause
• CC-BY-4.0
• CC-BY-3.0;BSD
• CC0-1.0
• Unlicense

Note: If editing the README, please conform to the standard-readme specification.

License

The Superface is licensed under the MIT. © 2021 Superface

Changelog

[3.0.0] - 2023-02-08

Added

• New create:map command
• New create:mock-map command
• New create:profile command
• New create:test command
• New create:mock-map-test command
• New create:provider command