@superfaceai/cli
Advanced tools
Superface CLI provides access to superface tooling from the CLI.
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.
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]
superface checksuperface compilesuperface configure PROVIDERNAMEsuperface createsuperface init [NAME]superface install [PROFILEID]superface lintsuperface loginsuperface logoutsuperface prepare:mapsuperface prepare:mock-mapsuperface publish DOCUMENTTYPEsuperface whoamisuperface checkChecks 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
OPTIONS
-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=scan 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=profileId Profile Id in format [scope/](optional)[name]
--providerName=providerName Name of provider.
DESCRIPTION
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 compileCompiles 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
OPTIONS
-h, --help show CLI help
-q, --quiet When set to true, disables the shell echo output of action.
-s, --scan=scan 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=profileId Profile Id in format [scope/](optional)[name]
--providerName=providerName Name of provider. This argument is used to compile map
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 PROVIDERNAMEConfigures new provider and map for already installed profile. Provider configuration is dowloaded from a Superface registry or from local file.
USAGE
$ superface configure PROVIDERNAME
ARGUMENTS
PROVIDERNAME Provider name.
OPTIONS
-f, --force When set to true and when provider exists in super.json, overwrites them.
-h, --help show CLI help
-p, --profile=profile (required) Specifies profile to associate with provider
-q, --quiet When set to true, disables the shell echo output of action.
--localMap=localMap Optional filepath to .suma map file
--localProvider=localProvider Optional filepath to provider.json file
--mapVariant=mapVariant 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
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 createCreates empty map, profile or/and provider on a local filesystem.
USAGE
$ superface create
OPTIONS
-h, --help show CLI help
-i, --interactive When set to true, command is used in interactive mode.
-p, --path=path Base path where files will be created
-q, --quiet When set to true, disables the shell echo output of action.
-s, --scan=scan When number provided, scan for super.json outside cwd within range represented by
this number.
-t, --variant=variant Variant of a map
-u, --usecase=usecase Usecases that profile or map contains
-v, --version=version [default: 1.0.0] Version of a profile
--init When set to true, command will initialize Superface
--map Create a map
--mapFileName=mapFileName Name of map file
--no-init When set to true, command won't initialize Superface
--no-super-json When set to true, command won't change SuperJson file
--noColor When set to true, disables all colored output.
--noEmoji When set to true, disables displaying emoji in output.
--profile Create a profile
--profileFileName=profileFileName Name of profile file
--profileId=profileId Profile Id in format [scope](optional)/[name]
--provider Create a provider
--providerFileName=providerFileName Name of provider file
--providerName=providerName Names of providers. This argument is used to create maps and/or providers
EXAMPLES
$ superface create --profileId sms/service --profile
$ superface create --profileId sms/service --profile -v 1.1-rev133 -u SendSMS ReceiveSMS
$ superface create --profileId sms/service --providerName twilio --map
$ superface create --profileId sms/service --providerName twilio --map -t bugfix
$ superface create --providerName twilio tyntec --provider
$ superface create --providerName twilio --provider --providerFileName my-provider -p my/path
$ superface create --profileId sms/service --providerName twilio --provider --map --profile -t bugfix -v 1.1-rev133 -u
SendSMS ReceiveSMS
$ superface create -i
See code: src/commands/compile.ts
superface init [NAME]Initializes superface local folder structure.
USAGE
$ superface init [NAME]
ARGUMENTS
NAME Name of parent directory.
OPTIONS
-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=profiles Profile identifiers.
--providers=providers Provider names.
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]
ARGUMENTS
PROFILEID Profile identifier consisting of scope (optional), profile name and its version.
OPTIONS
-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=providers Provider name.
-q, --quiet When set to true, disables the shell echo output of action.
-s, --scan=scan 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.
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 lintLints 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
OPTIONS
-f, --outputFormat=long|short|json [default: short] Output format to use to display errors and warnings.
-h, --help show CLI help
-o, --output=output [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=scan 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=profileId Profile Id in format [scope/](optional)[name]
--providerName=providerName Provider name
DESCRIPTION
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 loginLogin to superface server
USAGE
$ superface login
OPTIONS
-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.
EXAMPLES
$ superface login
$ superface login -f
See code: src/commands/login.ts
superface logoutLogs out logged in user
USAGE
$ superface logout
OPTIONS
-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.
EXAMPLE
$ superface logout
See code: dist/commands/logout.ts
superface prepare:mapPrepares map, based on profile and provider on a local filesystem. Created file contains prepared 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 prepare:map
OPTIONS
-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=scan 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=profileId (required) Profile Id in format [scope](optional)/[name]
--providerName=providerName (required) Name of provider.
--station When set to true, command will create map in folder structure of Superface station
See code: dist/commands/prepare/map.ts
superface prepare:mock-mapPrepares 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 prepared profile file (run sf prepare:profile).
USAGE
$ superface prepare:mock-map
OPTIONS
-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=scan 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=profileId (required) Profile Id in format [scope](optional)/[name]
--station When set to true, command will create map in folder structure of Superface station
See code: src/commands/prepare/mock-map.ts
superface publish DOCUMENTTYPEUploads 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
ARGUMENTS
DOCUMENTTYPE (map|profile|provider) Document type of published file
OPTIONS
-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=scan 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=profileId (required) Profile Id in format [scope/](optional)[name]
--providerName=providerName (required) Name of the provider. This argument is used to publish a map or a provider.
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 whoamiPrints info about logged in user
USAGE
$ superface whoami
OPTIONS
-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.
EXAMPLES
$ superface whoami
$ sf whoami
See code: src/commands/whoami.ts
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.
If you need any additional support, have any questions or you just want to talk you can do that through our documentation page.
When developing, start with cloning the repository using git clone https://github.com/superfaceai/cli.git (or git clone git@github.com: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 testslint - 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 administratoryarn global bin - usually the same as /use/local/binNote: 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.
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:
Note: If editing the README, please conform to the standard-readme specification.
The Superface is licensed under the MIT. © 2021 Superface
FAQs
Superface CLI utility
The npm package @superfaceai/cli receives a total of 2 weekly downloads. As such, @superfaceai/cli popularity was classified as not popular.
We found that @superfaceai/cli demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Newly introduced telemetry in devenv 1.4 sparked a backlash over privacy concerns, leading to the removal of its AI-powered feature after strong community pushback.
Security News
TC39 met in Seattle and advanced 9 JavaScript proposals, including three to Stage 4, introducing new features and enhancements for a future ECMAScript release.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.