toc

Evervault CLI

Manage Evervault from your terminal.

These docs are for the v2 CLI. You can find the docs for the deprecated v1 CLI here. Follow the migration guide to upgrade from the v1 CLI at your earliest convenience.

Installation

The latest version of the Evervault CLI can be downloaded and automatically installed using the following command:

bash
sh <(curl https://cli.evervault.com/v2/install -sL)

Globally Available Flags

There are some globally available flags which can be used with almost any command within the Evervault CLI.

  • --json: Any output from the CLI should be JSON formatted
  • --no-color: Disable coloured output. Note: the CLI will also respect the NO_COLOR and EV_NO_COLOR environment variables to disable colour.
  • --help: Print the helper text for any command

Commands

The Evervault CLI supports commands related to:

  1. Authentication →
  2. Cages →
  3. Relay →
  4. Teams →
  5. Apps →
  6. Support →
  7. Misc. →

Authentication

Use these commands to login and logout of the Evervault CLI.

Login

Log in to the Evervault CLI to get started:

bash
ev login
  • The CLI must be able to launch a browser to log you in.

Logout

Log out from the Evervault CLI:

bash
ev logout

Cages

Use the following commands to manage your Cages.

cage deploy

Deploy a Cage using the source code of your current directory:

bash
ev cage deploy [Flags]
  • Your current directory needs to contain a package.json and an index.js with an exported handler function.
  • Your Cage will use the name from the directory’s package.json.
  • By default, the CLI will wait for the Cage deployment to complete. If you only want to begin the deployment, you can use the --background flag.
  • If you want to deploy your Cage in a CI pipeline, you can set the EV_API_KEY environment variable to your team's API key, and pass the --api-key-auth flag.

Flags

  • --background - don’t wait for the Cage to complete its deployment.
  • --quiet - only print essential logs.
  • --api-key-auth - authenticate the deployment using the EV_API_KEY environment variable

cage clone

Clone an existing Cage in your current directory.

bash
ev cage clone [Flags] [Options] --name <cage_name>
  • If something already exists at the directory, you will have to confirm that you wish to overwrite it. This confirmation can be prevented using the --force flag.

Options

  • --name <cage_name> - the name of the Cage from your current Team to clone.
  • --dir <directory> - specify a directory to clone the Cage into.

Flags

  • --force - force the cage clone to continue without prompting (note: this will overwrite existing directories).

cage delete

Delete a Cage:

bash
ev cage delete [Flags] [Options]

Options

  • --name - the name of the Cage to delete. To use your current directory to specify the Cage, you must pass the --use-current-dir flag.

Flags

  • --force - force the cage to be deleted without a confirmation dialogue.
  • --use-current-dir - use the package.json in the current directory to identify the Cage to delete.

cage edit

Edit a Cage:

bash
ev cage edit [Flags] [Options] --name <new_cage_name>
  • The name field of the package.json in the current directory will be updated to reflect the new Cage name. Before updating the package.json, you will be asked to confirm the update. You can use the --force flag to prevent the confirmation.

Options

  • --name - the new name for the Cage.

Flags

  • --force - force the package.json name field to be updated without prompting.

cage env

Interact with the environment variables of the Cage in the current directory:

bash
ev cage env (get|set|delete) [Flags] [Options]

Options

  • --name <cage_name> - the name of the Cage to interact with. If not given, the CLI will look for a package.json in the current directory.
  • --key <env_key> - the environment variable key to get, set or delete.
  • --value <env_val> - the value to set for the environment variable.
  • --secret - encrypt and mask the value in the dashboard.
  • --api-key-auth - authenticate operations on your Cage's environment variables using the EV_API_KEY environment variable.

cage init

Initialize a simple “hello world” Cage either in your current directory, or the directory provided:

bash
ev [cage] init [Flags] [Options]

Options

  • --name <cage_name> - the name of the Cage to create. If not given, the cage will be created with the name hello-cage.
  • --dir <directory> - the directory to create the Cage in. If not given, the Cage will be created in a subdirectory of the current directory using the name of the Cage.

cage list

List all of the current team’s Cages:

bash
ev cage list

cage logs

Open the Cage logs screen in the Evervault Dashboard for the named Cage:

bash
ev cage logs --name <cage_name>
  • The CLI must be able to launch a browser to open the logs screen.

cage run

Run a named Cage from the command line using provided flags as a payload:

bash
ev [cage] run [Flags] [Options] --name <cage_name>
  • This command does not encrypt the data before running the Cage.

Options

  • --name <cage_name> - the name of the Cage to run
  • --data <value> - the JSON payload to send to the Cage.

Relays

Use the following commands to manage your Relays. All of the interactions with Relay through the CLI are done using a Relay configuration file, the name of this file is relay-config.json by default.

relay create

Creates a Relay configuration file that can be pushed to an app in your Evervault team:

bash
ev relay create [Flags]

Options

  • --destination-domain <target> - A single domain for Relay to forward requests to.
  • --custom-domain <custom-domain> Your own custom domain where the Relay will be accessible.
  • --dns-targets A list of DNS targets as JSON objects for Relay to forward requests to. Each target requires 'type' and 'address' keys.
  • --relay-type <type> - AUTO, CUSTOM, or DNS. An Auto relay creates a relay hosted on an Evervault domain. A Custom or Dns creates a relay on one of your own domains, configured either with a static Domain target or Dns targets respectively.
  • --file <file> - The destination for this Relay configuration. This is the file you will edit to configure your relay. Defaults to relay-config.json.
  • --force - Force the creation of the relay configuration file. If this flag is set, running the command will overwrite any existing Relay configuration file at the specified path.

Examples

bash
ev relay create

Using --dns-targets:

bash
ev relay create --dns-targets='[{"type": "CNAME", "address": "example.herokudns.com"}, {"type": "A", "address":"123.123.123.123"}]''

Using --file:

bash
ev relay create --file ./relay-conf.json

relay clone

Copies the configuration of a deployed Relay into a Relay configuration file.

bash
ev relay clone [Flags]

Options

  • --domain <relay> - The domain of the relay to clone.
  • --file <file> - The file to clone the relay into. Defaults to relay-config.json.
  • --force - Force the creation of the relay configuration file. If this flag is set, running the command will overwrite any existing Relay configuration file at the specified path.

relay dev

Runs a Relay configuration locally. This command is to be used for testing Relay configurations locally and for assisting with local development using Evervault. When this command is running it listens for changes in the Relay configuration file and applies updates as the file is updated.

bash
ev relay dev --port <port> [Flags] [Options]

Options

  • --port <port> - The port to forward traffic to. (Required)
  • --host <host> - The host to forward traffic to. Defaults to 127.0.0.1.
  • --file <file> - The Relay configuration file to be applied to this relay. Defaults to relay-config.json.

relay delete

Delete a Relay:

bash
ev relay delete [Flags] [Options]

Options

  • --domain <domain> - The domain of the relay to be deleted.

relay list

List your Relays:

bash
ev relay list [Flags]

relay push

Push the contents of a Relay configuration file to your currently selected app on Evervault. If the relay does not yet exist it will create a new one, if it does exist then it will be updated with the parameters as specified in the relay configration file.

Note: A summary of the changes to be performed will be displayed followed by a confirmation.

bash
ev relay push [FLAGS] [OPTIONS]

Options

relay diff

Shows the difference between the contents of your relay-config.json file and the relay actively deployed on Evervault to allow you to preview the changes that would be applied by running a relay push

bash
ev relay push [FLAGS] [OPTIONS]

Options

Teams

Use the following commands to manage the teams that you’re a member of.

team list

List all teams that your account has access to:

bash
ev team list

team switch

Switch the team you’re working on in the CLI:

bash
ev team switch [Flags] [Options]

Options

  • --uuid <uuid> - The uuid of the team to switch to

Apps

Use the following commands to manage the apps of your currently selected team.

app list

List all apps that belong to your active team:

bash
ev app list

app switch

Switch the app you’re working on in the CLI:

bash
ev app switch [Flags] [Options]

Options

  • --uuid <uuid> - The uuid of the app to switch to

Support

help

Display help for the Evervault CLI:

bash
ev [Subcommand] help

info

View information about your current session in the Evervault CLI:

bash
ev info [Flags]

reset

Factory reset of the Evervault CLI:

bash
ev reset [Flags]
  • reset will wipe all local data.

Misc.

dash

Open your browser on the Evervault dashboard:

bash
ev dash
  • The CLI must be able to launch a browser to bring you to the dashboard.

docs

Open your browser on the Evervault documentation site:

bash
ev docs

Relay Configuration File

The relay configuration file is used to create and update Evervault Relays using the CLI. The expected structure of the file is below:

With a destination domain:

json
{
"<Relay Domain>": {
"destinationDomain": "<Relay Destination>",
"fieldsToEncrypt": [
{
"route": <The route to apply this configuration to>,
"method": <GET|POST|PUT|PATCH|DELETE|*>,
"fields": <A list of fields to encrypt. JSON Path is supported here>
}
]
}
}

With DNS Targets:

json
{
"<Relay Domain>": {
"dnsTargets": [
{
"type": <A|CNAME>,
"address": <A valid hostname>
}
],
"fieldsToEncrypt": [
{
"route": <The route to apply this configuration to>,
"method": <GET|POST|PUT|PATCH|DELETE|*>,
"fields": <A list of fields to encrypt. JSON Path is supported here>
}
]
}
}

Please note that it is not possible to set both a destinationDomain and dnsTargets.

Upgrading from the v1 CLI

Recently, Evervault released a UI overhaul alongside the introduction of Apps. The concept of Apps allows users to create multiple tenants (Apps) within a single team. Along with this change, comes a change to how our CLI works.

If you had created a team with Evervault prior to the release of Apps, a default App has been created for you and all your existing resource will live inside that app. This is for backwards compatibility and will not break existing CLI workflows.

If you wish to use the CLI with Apps (excluding the default App created for you), you will need to upgrade to the latest version of the CLI!
  1. Download the latest v2 CLI using the below command: sh <(curl https://cli.evervault.com/v2/install -sL)

  2. If you are using the CLI outside of a CI pipeline, you should log in in the usual way using the ev login command. During the execution of this command you will be prompted to select a team as usual. In addition to this you will now need to select an app in which you want to perform actions in. You can list apps using the ev app list command. You can switch to an app using the ev app switch command.

  3. If you are using the CLI in a CI pipeline, you will need to update your EV_API_KEY environment variable to use the API key of the app you want to perform actions in. You can find your app API key by navigating to app.evervault.com → select your team → select your app → settings → App API Key.


Was this page useful?