A full reference for the Evervault Command Line Interface (CLI). The Evervault CLI allows you to test and manage your Evervault integration from your terminal.

Setup

The latest version of the Evervault CLI can be downloaded and automatically installed using the following command. This command can also be used to upgrade from a previous major version of the Evervault CLI.

shamir:~$

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

Next you’ll need to sign in. You can switch teams and apps with the team switch and app switch commands.

shamir:~$

ev login

Authentication

The Evervault CLI supports two main authorization methods. The ev login command logs you in to the CLI using your Evervault Account and gives you the same access as you would have through the Dashboard.

The other method is API Key Authorization. It is supported on a select few commands that developers may use in CI/CD pipelines, such as ev function deploy.

Global Flags

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

Flags

--json

Format any output from the CLI as JSON.

--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

General

Use these commands to manage your installation of the Evervault CLI.

Connect the CLI to your Evervault account by authenticating with a browser.

shamir:~$

ev login

logout

Log out from the Evervault CLI. This will remove all stored credentials linking the CLI to your Evervault account.

shamir:~$

ev logout

update

Update the Evervault CLI to the latest version. Note: The update command will not update between major versions of the Evervault CLI.

shamir:~$

ev update

Teams

Use these commands to manage the Teams that you’re a member of.

team list

List the teams that you are a member of.

shamir:~$

ev team list

team switch

Switch the currently active team in your Evervault CLI

shamir:~$

ev team switch

Apps

Use these commands to manage the Apps that belong to your currently selected Team

app list

List the apps in your currently selected Team.

shamir:~$

ev app list

app switch

Switch the currently active app in your Evervault CLI.

shamir:~$

ev app switch

Functions

Use these commands to manage your Functions.

function deploy

Deploy a Function using the source code of your current working directory.

shamir:~$

ev function deploy [flags]

Your current directory needs to contain a valid function.toml . You can generate one using the ev function create-toml command.
Your Function will use the name set in the function.toml
By default, the CLI will wait for the Function deployment to complete. If you only want to begin the deployment and then exit, you can pass in the --background flag.
If you want to deploy your Function in a CI pipeline, you can set the EV_API_KEY environment variable to an API key with function:deploy permissions, and pass the --api-key-auth flag.

Flags

--api-key-auth

Authenticate the deployment using an API key. The EV_API_KEY environment variable must be set to an Evervault API key with function:deploy permissions.

--background

Don’t wait for the Function to complete its deployment.

--quiet

Only print essential logs.

function env

Manage the environment variables of the Function in your current directory.

Note: Some environment variables are reserved for our use and therefore are immutable.

shamir:~$

ev function env (get|set|delete) [flags] [options]

Flags

--secret

Mark the environment variable as a secret. This encrypts it and makes it irretrievable. All secrets are decrypted when your function is run.

--api-key-auth

Authenticate the request using an API key. The EV_API_KEY environment variable must be set to an Evervault API key with function:update permissions.

Options

--name

The name of the Function to interact with. If not given, then the CLI will look for a function.toml in the current directory.

--key

The key of the environment variable you wish to update.

--value

The value of the environment variable you wish to update.

function init

Initialize a sample “hello world” Function either in your current directory, or the directory provided

shamir:~$

ev function init [flags] [options]

Flags

--force

Overwrite the existing directory at the location if it exists

Options

--dir

The directory to initialize the function into. If not given, the Function will be created in a subdirectory of the current directory using the name of the Function.

function create-toml

Creates a starter function.toml in the current directory.

Note: This command will not work in a tty environment.

shamir:~$

ev function create-toml

function list

Lists all of the currently selected App’s Functions.

shamir:~$

ev function list

function delete

Deletes a Function.

shamir:~$

ev function delete

Flags

--use-current-directory

Use the function.toml in the current directory to determine which Function to delete.

--api-key-auth

Authenticate the request using an API key. The EV_API_KEY environment variable must be set to an Evervault API key with function:delete permissions.

Options

--name

The name of the Function you wish to delete.

function run

Run a named Function from the command line using a JSON Payload.

Note: This command does not encrypt your data before sending it to the Function.

shamir:~$

ev function run [flags] [options]

Flags

--local

run this Function locally. Note: Must be run in the directory containing the Function.

--api-key-auth

Authenticate the request using an API key. The EV_API_KEY environment variable must be set to an Evervault API key with function:run permissions.

Options

--name

The name of the Function you wish to invoke. If not provided the CLI will attempt to run the Function defined in a function.toml in the current working directory.

--data

The JSON Payload to send to the Function.

--in

Path to a file containing the JSON payload to send to the Function, can't be used at the same time as --data.

Locally running functions can only decrypt debug encrypted strings.

Relay

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.

Note: Interfacing with outbound relay, such as cloning, creating or deleting outbound destinations is not currently implemented in the evervault CLI.

Relay Configuration File

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.

Note: It is not possible to have both a destionationDomain and dnsTargets set.

Examples

A Relay on an Evervault domain with a specified destination domain:

1
{
2
  "<Relay Domain>": {
3
    "destinationDomain": "<Relay Destination>",
4
    "fieldsToEncrypt": [
5
      {
6
        "route": <The route to apply this configuration to>,
7
        "method": <GET|POST|PUT|PATCH|DELETE|*>,
8
        "fields": <A list of fields to encrypt. JSON Path is supported here>
9
      }
10
    ]
11
  }
12
}

A Relay on a custom domain with specified DNS targets:

1
{
2
  "<Relay Domain>": {
3
    "dnsTargets": [
4
      {
5
        "type": <A|CNAME>,
6
        "address": <A valid hostname>
7
      }
8
    ],
9
    "fieldsToEncrypt": [
10
      {
11
        "route": <The route to apply this configuration to>,
12
        "method": <GET|POST|PUT|PATCH|DELETE|*>,
13
        "fields": <A list of fields to encrypt. JSON Path is supported here>
14
      }
15
    ]
16
  }
17
}

relay create

Creates a Relay configuration file that you can push to Evervault.

shamir:~$

ev relay create [flags] [options]

Flags

--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.

--dns-target

A list of DNS targets as JSON objects for Relay to forward requests to. Each target requires 'type' and 'address' keys.

Options

--destination-domain

A single domain for Relay to forward requests to.

--custom-domain

Your own custom domain where the Relay will be accessible.

--relay-type

Can be set to either AUTO, CUSTOM, or DNS . An AUTO relay creates a relay hosted on an Evervault domain. A CUSTOM or DNScreates a relay on one of your own domains, configured either with a static Domain target or DNS targets respectively.

--file

The destination for this Relay configuration. This is the file you will edit to configure your relay. Defaults to relay-config.json

relay clone

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

shamir:~$

ev relay clone [flags] [options]

Flags

--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.

Options

--domain

The domain of the Relay to clone.

--file

The destination for this Relay configuration. This is the file you will edit to configure your relay. Defaults to relay-config.json

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.

shamir:~$

ev relay dev [options]

Options

--portRequired

The port to forward traffic to.

--hostDefault: 127.0.0.1

The host to forward traffic to.

--fileDefault: relay-config.json

The Relay configuration file to be applied to this Relay.

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 configuration file.

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

shamir:~$

ev relay push [options]

Options

--fileDefault: relay-config.json

The Relay configuration file to be applied to this Relay.

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.

shamir:~$