# CLI

_The Evervault Command Line Interface allows you to test and manage your Evervault integration from your terminal._

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.

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

### Updating

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

```bash
ev 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_KEY` `string` _(required)_ — An [API Key](/developers/api-keys) with the appropriate permissions, created from the [Evervault Dashboard](https://app.evervault.com).
- `EV_APP_UUID` `string` _(required)_ — Your App ID, which can be found in the [Evervault Dashboard](https://app.evervault.com) 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.

```bash
ev encrypt --data "Hello, world!"
```

**Options**

- `--data` _(required)_ — 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.

```bash
ev decrypt --data "ev:Tk9D:GWgxSXezEFNw10..."
```

**Options**

- `--data` _(required)_ — 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.

```bash
ev relay create
```

**Flags**

- `--out` _(required)_ — Path to write relay.json to. Defaults to relay.json

### relay deploy

Deploy changes to your [Relay](/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.

```bash
ev 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.

```json
{
  // The ID of the Relay.
  "id": "relay_destination_de582ef10c16",
  // The ID of the App the Relay belongs to.
  "app": "app_ddfbbn7n841e",
  // The destination where the Relay will forward requests to.
  "destinationDomain": "example.com",
  // The Evervault domain for the Relay.
  "evervaultDomain": "example-com-app-relay.evervault.app",
  // Whether to encrypt empty strings.
  "encryptEmptyStrings": true,
  // The authentication method to use for the Relay. Set this to 'api-key' to enable API key authentication.
  "authentication": null,
  // The route configurations for how the Relay should handle requests.
  "routes": [
    {
      // The HTTP method to match.
      "method": "POST",
      // The path to match.
      "path": "/checkout",
      // The transformations to apple to the request payload.
      "request": [
        {
          // The action to perform on the request payload. "encrypt" or "decrypt".
          "action": "encrypt",
          // The JSON Path expressions to select the fields to encrypt.
          "selections": [
            {
              // The type of data to select. "json", "form" or "header"
              "type": "json",
              // The JSON Path expression to select the field to encrypt.
              "selector": "$.cardNumber"
            }
          ]
        }
      ],
      // The transformations to apple to the response payload.
      "response": [
        {
          "action": "decrypt",
          "selections": [
            {
              "type": "json",
              "selector": "$..*"
            }
          ]
        }
      ]
    }
  ]
}
```

## function

### function init

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

```bash
ev 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.

```bash
ev 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.

```bash
ev 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.

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

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

```bash
ev 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.

```bash
ev function run [OPTIONS]
```

**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](/functions#executiontime) documentation for more information.

## enclave

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

### enclave init

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-key`and`--signing-cert`.

```bash
ev 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.
- `--max-concurrent-connections` — Enable concurrent request processing by capping the number of connections the data plane handles at once. Must be greater than zero. If unset, the data plane accepts connections serially.
- `--max-concurrent-handshakes` — The maximum number of TLS handshakes the data plane maintains concurrently. Must be greater than zero and must not exceed --max-concurrent-connections.
- `--handshake-timeout` — The timeout for a single TLS handshake, in milliseconds. Stalled handshakes are dropped after the timeout elapses.

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

```bash
ev 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.

```bash
ev 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.

```bash
ev 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.

```bash
ev 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`.

```bash
ev 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.

```bash
ev 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.

```bash
ev 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.

```bash
ev 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.

```bash
ev enclave [FLAGS] list enclaves [OPTIONS]
```

**Options**

- `-h, --help` — Print help information

### enclave list deployments

List the deployments for your Enclave.

```bash
ev 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.

```bash
ev 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 an Enclave.

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

**Flags**

- `--key` _(required)_ — The key of the environment variable to add.
- `--value` _(required)_ — 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.

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

**Flags**

- `--key` _(required)_ — The key of the environment variable to delete.

### enclave env get

Get the environment variables in json format.

```bash
ev enclave [FLAGS] env get
```