Evervault CLI

This reference documents every command and flag available in the Evervault CLI.

The Evervault CLI allows you to configure your Evervault integration from the terminal.

Installation

Install the Evervault CLI.

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

Updating

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

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

To authenticate the Evervault CLI configure the following environment variables:

Variable	Description
`EV_API_KEY`	A Scoped API Key with the appropriate permissions, created from the Evervault Dashboard.
`EV_APP_UUID`	Your App ID, which can be found in the Evervault Dashboard on the app Settings page.

Global Flags

Globally available flags which can be used with all Evervault CLI commands.

Flags

--json

Format any output from the CLI as JSON.

--verbose

Print verbose logs.

--help

Print the helper text for any command

Encrypt & Decrypt

The Encrypt & Decrypt commands allow you to encrypt data using the Evervault API. For details on the API Endpoints see the Evervault API Reference.

Encrypt

Encrypt data using the Evervault API. Note, while Strings are valid JSON values they must be enclosed in double quotes. For example ev encrypt -d "\"encrypt me!\"".

Options

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

Options

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

Create and manage Relays.

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

Create a Relay

Creates an Evervault Relay and generates its configuration file.

Flags

--out

Path to write relay.json to. Defaults to relay.json

Deploy

Deploy changes to your Evervault Relay. ev relay deploy will deploy any changes made to the Relay configuration file.

This is useful for versioning your Relay configuration by checking your relay.json file into version control.

Flags

--file

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

Functions

Use these commands to manage your Functions.

Initialize a new Function

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

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.

Create a new function.toml

Creates a starter function.toml in the current directory.

Deploy

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

Your current directory needs to contain a valid function.toml, created when you run ev function init.
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. This is recommended in a CI/CD environment.

Flags

--background

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

Options

--name

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

Manage Environment Variables

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

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

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 you wish to update.

--value

The value of the environment variable you wish to update.

Delete

Deletes a Function.

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, the CLI will look for a function.toml in the current directory.

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.

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.

--async

Whether to run the Function asynchronously. See the Function Execution Time documentation for more information.

Enclaves

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

Init

Create an Enclave and initialize an enclave.toml in the current directory.

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.

-f, --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-ports

Comma separated list of ports to allow egress on

--egress-destinations

Comma separated list of domains to allow egress to, default is all (*)

-generate-signing

Flag to enable cert generation during initialization. This will use the default certificate.

-h, --help

Print help information

-o, --outputDefault: ./

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.

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 enclav[FLAGS] init command.

Args

CONTEXT_PATH

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

Options

-c, --configDefaults to ./enclave.toml

Path to the enclave.toml file.

-f, --fileDefaults to ./Dockerfile

Path to the Dockerfile to use for the Enclave.

-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

New Certificate

Create a new Enclave signing certificate and private key.

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.

Upload Certificate Metadata

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.

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

Lock Certificates

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.

Options

-c --config

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

Delete

Delete the Enclave defined in a given enclave.toml.

Options

-c, --configDefault to ./enclave.toml

Path to the enclave.toml config file.

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

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.

Args

CONTEXT_PATH

Path to use for the Docker context. Defaults to the current directory.

Options

-c, --configDefault: ./enclave.toml

Path to enclave.toml config file

--eif-path

Path to EIF for the Enclave. Will skip building if EIF is provided.

-f, --fileDefault: ./Dockerfile

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

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

Options

-c, --configDefault to ./enclave.toml

Path to the enclave.toml config file.

--enclave-uuid

Uuid of the Enclave to restart

--background

Perform the Enclave restart in the background

Describe

Get the PCRs of an existing EIF.

Args

EIF_PATHDefault: ./enclave.eif

Path to the EIF to describe.

Options

-h, --help

Print help information

--no-cache

Disables the use of cache during the image builds

List Enclaves

List your Enclaves

Options

-h, --help

Print help information

List Deployments

List the deployments for your Enclave.

Options

--enclave-uuid

The uuid of the Enclave to get deployments for.

-h, --help

Print help information.

Logs

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

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.

Add Environment Variable

Add environment variable to be used in a Enclave.

Flags

--keyRequired

The name of the environment variable.

--valueRequired

The value for the environment variable.

Options

-h, --help

Print help information.

--secret

Encrypt the environment variable.

Delete Environment Variable

Permanently delete a environment variable from the Enclave environment.

Flags

--keyRequired

The name of the environment variable.

Get Environment Variables

Get the environment variables in json format.