CLI

The Evervault CLI allows you to configure your Evervault integration from the terminal. This reference documents every command and flag available in the Evervault CLI.

Installation

Run the following command to install the Evervault CLI. This command can also be used to upgrade from a previous major version of the Evervault CLI.

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

Updating

To update the Evervault CLI to the latest version, run the following command:

1ev update

The update command will not update between major versions of the Evervault CLI. To update to a new major version, you will need to run the installation command again.

Authentication

To authenticate the Evervault CLI configure the following environment variables:

Environment Variables

EV_API_KEYRequiredstring
An API Key with the appropriate permissions, created from the Evervault Dashboard.
EV_APP_UUIDRequiredstring
Your App ID, which can be found in the Evervault Dashboard on the app Settings page.

Global Flags

The following flags can be used on any command within the Evervault CLI.

Flags

--help
Show help for the command.
--verbose
Print verbose logs.
--json
Output the response in JSON format.

encrypt

Encrypt data using the Evervault API. Note, while Strings are valid JSON values they must be enclosed in double quotes.

1ev encrypt --data "Hello, world!"

Options

--dataRequired
The JSON value to be encrypted. This can be any valid JSON value: Objects, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).

decrypt

Decrypt data using the Evervault API.

1ev decrypt --data "ev:Tk9D:GWgxSXezEFNw10..."

Options

--dataRequired
The Encrypted JSON value to be decrypted. This can be any valid JSON value: Objects, Arrays, Numbers, Boolean or Strings (strings should be enclosed in double quotes).

relay

The Evervault CLI can be used to manage your Relays in a continuous integration environment.

relay create

Creates an Evervault Relay and generates a configuration file. You will be prompted to enter the relay destination URL.

1ev relay create

Flags

--outRequired
Path to write relay.json to. Defaults to relay.json

relay deploy

Deploy changes to your Relay based on the relay.json configuration file. This is useful for versioning your Relay configuration by checking your relay.json file into version control.

1ev relay deploy

Flags

--file
The file containing the Relay config you want to use. Defaults to relay.json.

relay.json

The relay.json file is a JSON file that contains the configuration for your Relay. It is used to define the Relay's behavior and how it should interact with data.

1{
2  // The ID of the Relay.
3  "id": "relay_destination_de582ef10c16",
4  // The ID of the App the Relay belongs to.
5  "app": "app_ddfbbn7n841e",
6  // The destination where the Relay will forward requests to.
7  "destinationDomain": "example.com",
8  // The Evervault domain for the Relay.
9  "evervaultDomain": "example-com-app-relay.evervault.app",
10  // Whether to encrypt empty strings.
11  "encryptEmptyStrings": true,
12  // The authentication method to use for the Relay. Set this to 'api-key' to enable API key authentication.
13  "authentication": null,
14  // The route configurations for how the Relay should handle requests.
15  "routes": [
16    {
17      // The HTTP method to match.
18      "method": "POST",
19      // The path to match.
20      "path": "/checkout",
21      // The transformations to apple to the request payload.
22      "request": [
23        {
24          // The action to perform on the request payload. "encrypt" or "decrypt".
25          "action": "encrypt",
26          // The JSON Path expressions to select the fields to encrypt.
27          "selections": [
28            {
29              // The type of data to select. "json", "form" or "header"
30              "type": "json",
31              // The JSON Path expression to select the field to encrypt.
32              "selector": "$.cardNumber"
33            }
34          ]
35        }
36      ],
37      // The transformations to apple to the response payload.
38      "response": [
39        {
40          "action": "decrypt",
41          "selections": [
42            {
43              "type": "json",
44              "selector": "$..*"
45            }
46          ]
47        }
48      ]
49    }
50  ]
51}

function

function init

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

1ev function init

Flags

--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.
--force
Overwrite the existing directory at the location if it exists

function create-toml

Creates a starter function.toml in the current directory.

1ev function create-toml

function deploy

Deploy a Function using the source code of your current working directory. Your current directory must contain a valid function.toml file.

1ev function deploy

Flags

--background
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. This is recommended in a CI/CD environment.
--name
The name of the Function to deploy. If not given, the CLI will look for a function.toml in the current directory.

function env

Manage the environment variables for a Function.

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

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

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 to update.
--value
The value of the environment variable to update.

function delete

Deletes a Function.

1ev function delete [FLAGS] [OPTIONS]

Flags

--force
Force the deletion of the Function. This will prevent any confirmation dialogues.

Options

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

function run

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

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

1ev function run [OPTIONS]

Optins

--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.
--async
Whether to run the Function asynchronously. See the Function Execution Time documentation for more information.

enclave

The Evervault CLI is the primary interface for building and deploying Enclaves.

Create an Enclave and initialize an enclave.toml in the current directory. By default, this will generate a key pair to sign your Enclave image unless a key pair is explicitly provided using --private-keyand--signing-cert.

1ev enclave [FLAGS] init [OPTIONS] --name <ENCLAVE_NAME>

Options

--name
Name of Enclave to deploy
--port
The port that the in-Enclave service listens on. All incoming requests will be forwarded to this port. If unset, it will be taken as last exposed port in the Dockerfile.
--file
Dockerfile to build the Enclave
--healthcheck
The path that should be used for in-Enclave healthchecks. These healthchecks are performed every second and can be used to probe the running process.
--healthcheck-port
The port to perform healthchecks against. If this is unset, then the healthchecks are assumed to be served over the same port as the incoming requests.
--debug
Debug setting for the Enclave. When debug is enabled, you can access logs from within the Enclave.
--egress
Flag to enable network egress from your Enclave, default egress port is 443
--egress-destinations
Comma separated list of domains to allow egress to, default is all (*)
-h, --help
Print help information
-o, --output
Directory to write the enclave.toml to. Defaults to the current directory.
--private-key
Path to the signing key to use for the Enclave.
--signing-cert
Path to the signing cert to use for the Enclave
--disable-api-key-auth
Turn off API key authentication in the Enclave.
--trusted-headers
Trusted headers sent into the Enclave will be persisted without redaction in the Enclave's transaction logs.
--disable-tls-termination
Turn off TLS Termination in the Enclave's data plane process. This will allow you to control TLS termination within your service to enable mTLS or a custom certificate.
--forward-proxy-protocol
When supplied with --disable-tls-termination, the data plane will forward the client IP using the HAProxy Proxy Protocol v2.
--desired-replicas
Define the number of instances to deploy your Enclave to. Defaults to 2.

enclave build

The build command mirrors the docker build command but produces an Enclave Image File (EIF) as output instead of a Docker image. The build command requires a enclave.toml to be available when creating an Enclave Image File. This can be generated using the ev enclave [FLAGS] init command.

1ev enclave [FLAGS] build [OPTIONS] [CONTEXT_PATH]

Arguments

CONTEXT_PATH
Path to use for Docker context, defaults to the current directory.

Options

-c, --config
Path to the enclave.toml file. Defaults to ./enclave.toml
-f, --file
Path to the Dockerfile to use for the Enclave. Defaults to ./Dockerfile
-o, --output
Path to directory to save the processed Dockerfile and EIF.
--private-key
Private key to be used when signing the EIF.
--signing-cert
Certificate corresponding to the private key.
--build-arg
Build time arguments to provide to Docker.
--build-secret
Build time secrets to provide to Docker. These secrets are used during the Docker build process, similar to the Docker --secret flag.
--from-existing
Build from enclave.Dockerfile for build reproducibility
--reproducible
Build enclave with reproducible measures
--forward-proxy-protocol
Enabled forwarding proxy protocol when TLS Termination is disabled
--no-cache
Disables the use of cache during image builds

enclave cert new

Create a new Enclave signing certificate and private key.

1ev enclave [FLAGS] cert new [OPTIONS]

Options

-o, --output
Path to the directory where the credentials will be saved. Defaults to the current directory.
--subj
Defining the certificate’s distinguished name e.g. /CN=EV/C=IE/ST=LEI/L=DUB/O=Evervault/OU=Eng. If not given a generic Enclave subject is given.

enclave cert upload

Upload a signing certificate's metadata to the Evervault API. This cert can then be used in the cert lock command.

Note: Certificate metadata is automatically uploaded to the Evervault API when you deploy an Enclave. This command is only necessary if you want to lock deployments to a certificate before the certificate has been used for a deployment. If you have already deployed with the certifcate, the metadata will be available in the cert lock prompt.

1ev enclave [FLAGS] cert upload [OPTIONS]

Options

-p, --cert_path
Path to directory where the signing cert is. Defaults to the path specified in ./enclave.toml
-c --config
Path to enclave.toml config file. Default: ./enclave.toml

enclave cert lock

Interactive prompt to lock Enclave deployments to specific signing certificates. An Enclave deployment will fail if the signing certificate used is not in specified locked certs. If no certificates are locked to an Enclave, it can be deployed with any certificate. If you want to lock a newly created certifcate, you must first upload it's metadata using the cert upload command. This certificate will then be available in the cert lock prompt.

1ev enclave [FLAGS] cert lock [OPTIONS]

Options

-c --config
Path to enclave.toml config file. Default: ./enclave.toml

enclave delete

Delete the Enclave defined in a given enclave.toml.

1ev enclave [FLAGS] delete [OPTIONS]

Options

-c --config
Path to the enclave.toml config file. Default: ./enclave.toml
--enclave-uuid
Uuid of the Enclave to delete
--background
Perform the Enclave deletion in the background
--force
Prevent confirmation dialogue and proceed with deletion. Use with caution.

enclave deploy

Deploy the Enclave defined in your enclave.toml file. By default, the deploy command will ignore any prebuilt EIFs and begin a fresh Enclave build. You can prevent this by providing a path to an existing EIF using the --eif-path option.

1ev enclave [FLAGS] deploy [OPTIONS] [CONTEXT_PATH]

Arguments

CONTEXT_PATH
Path to use for Docker context, defaults to the current directory.

Options

-c, --config
Path to the enclave.toml config file. Default: ./enclave.toml
--eif-path
Path to EIF for the Enclave. Will skip building if EIF is provided.
-f, --file
Path to Dockerfile for Enclave. Will override any Dockerfile specified in the enclave.toml file
--private-key
Private key used to sign the Enclave Image File.
--signing-cert
Certificate used to sign the Enclave Image File.
--build-arg
Build time arguments to provide to Docker
--build-secret
Build time secrets to provide to Docker. These secrets are used during the Docker build process, similar to the Docker --secret flag.
--from-existing
Build from enclave.Dockerfile for build reproducibility
--reproducible
Build enclave with reproducible measures
--healthcheck
The endpoint to use for healthchecks. See healthchecks for more information.
--no-cache
Disables the use of cache during the image builds

enclave restart

Restart the Enclave defined in your enclave.toml file. This will redeploy the Enclave with the same image as your current Deployment, but with the latest environment variables and secrets. This won't affect your Enclave's PCRs.

1ev enclave [FLAGS] restart [OPTIONS]

Options

-c --config
Path to the enclave.toml config file. Default: ./enclave.toml
--enclave-uuid
Uuid of the Enclave to restart
--background
Perform the Enclave restart in the background

enclave describe

Get the PCRs of an existing EIF.

1ev enclave [FLAGS] describe [OPTIONS] [EIF_PATH]

Arguments

EIF_PATH
Path to the EIF to describe.

Options

-h, --help
Print help information
--no-cache
Disables the use of cache during the image builds

enclave list enclaves

List your enclaves.

1ev enclave [FLAGS] list enclaves [OPTIONS]

Options

-h, --help
Print help information

enclave list deployments

List the deployments for your Enclave.

1ev enclave [FLAGS] list deployments [OPTIONS]

Options

-h, --help
Print help information
--enclave-uuid
Uuid of the Enclave to list deployments for

enclave logs

View the logs for your Enclave. Only available for Enclaves in debug mode.

1ev enclave [FLAGS] logs [OPTIONS]

Options

--enclave-uuid
The uuid of the Enclave to get deployments for.
-c, --config
The local Enclave config.
--end-time
The end time in milliseconds since the unix epoch.
--start-time
The start time in milliseconds since the unix epoch
-h, --help
Print help information

enclave env add

Add environment variable to be used in a Enclave.

1ev enclave [FLAGS] env add [OPTIONS] --key <ENV_KEY> --value <SECRET_VALUE>

Flags

--keyRequired
The key of the environment variable to add.
--valueRequired
The value of the environment variable to add.

Options

-h, --help
Print help information.
--secret
Encrypt the environment variable.

enclave env delete

Permanently delete a environment variable from the Enclave environment.

1ev enclave [FLAGS] env delete [OPTIONS] --key <ENV_KEY>

Flags

--keyRequired
The key of the environment variable to delete.

enclave env get

Get the environment variables in json format.

1ev enclave [FLAGS] env get

CLI

Environment Variables

Flags

Options

Options

Flags

Flags

Flags

Flags

Flags

Options

Flags

Options

Optins

Options

Arguments

Options

Options

Options

Options

Options

Arguments

Options

Options

Arguments

Options

Options

Options

Options

Flags

Options

Flags

On this page