# Nitro Enclaves Command Line Interface reference
Nitro CLI Reference

The following commands are available in the Nitro CLI. All of the Nitro CLI commands start with `nitro-cli`, followed by one of the following subcommands. To view the command line help for a command, add the `--help` option.

**Topics**
+ [

# nitro-cli build-enclave
](cmd-nitro-build-enclave.md)
+ [

# nitro-cli run-enclave
](cmd-nitro-run-enclave.md)
+ [

# nitro-cli describe-enclaves
](cmd-nitro-describe-enclaves.md)
+ [

# nitro-cli console
](cmd-nitro-console.md)
+ [

# nitro-cli describe-eif
](cmd-nitro-describe-eif.md)
+ [

# nitro-cli sign-eif
](cmd-nitro-sign-eif.md)
+ [

# nitro-cli pcr
](cmd-nitro-pcr.md)
+ [

# nitro-cli terminate-enclave
](cmd-nitro-terminate-enclave.md)

# nitro-cli build-enclave


Converts a Docker image into an enclave image file (`.eif`). You can specify either a local directory containing a Dockerfile, or a Docker image in a Docker repository.

**Important**  
This command is not supported on Windows. If you are using a Windows parent instance, you must run this command on a Linux computer and then transfer the enclave image file (`.eif`) to the Windows parent instance.  
You can build enclave images files using the Nitro CLI on any Linux environment, including outside of AWS. To manage the lifecycle of an instance—such as with the `run-enclave` command—you will need to use the Nitro CLI on a parent instance (EC2 instance with Nitro Enclave enabled).

The command returns a set of measurements (SHA384 hashes) that are unique to the enclave image file. These measurements are provided in the form of platform configuration registers (PCRs). The PCRs are used during the enclave's attestation process. For more information, see [Nitro Enclaves concepts](nitro-enclave-concepts.md).

For example, when using Nitro Enclaves with AWS Key Management Service (AWS KMS), you can specify these PCRs in condition keys for customer managed keys policies. When an application in the enclave performs an AWS KMS operation, AWS KMS compares the PCRs in the enclave's signed attestation document with the PCRs specified in the condition keys of the KMS key policy before allowing the operation.

## Syntax


```
nitro-cli build-enclave 
    --docker-uri repository:tag 
    [--docker-dir /path_to/dockerfile_directory ]
    --output-file file-location 
    [--private-key key]
    --signing-certificate certificate.pem
    [--name image_name]
    [--version image_version]
```

## Options


**`--docker-uri`**  
The uniform resource identifier (URI) of a Docker image in a Docker repository. The URI is specified using the `repository`:`tag` format.   
Type: String  
Required: Yes

**`--docker-dir`**  
The path to a local directory containing a Dockerfile.  
Type: String  
Required: No

**`--output-file`**  
The file name of the enclave image file that is created.  
Type: String  
Required: Yes

**`--private-key `**  
The private key to use to sign the enclave image file. This can be a KMS key ARN, or a path to a local private key file. For more information, see [Key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).  
Only ECDSA keys are supported for code for signing. If you specify `--private-key` then you must also specify `--signing-certificate`. If you specify this parameter, the command creates a signed enclave image file. The command output will include an additional PCR, `PCR8`, which can be used in condition keys for KMS key policies. For more information, see [Where to get an enclave's measurements](set-up-attestation.md#where).  
Type: String  
Required: No

**`--signing-certificate`**  
The signing key to use to sign the enclave image file. If you specify `--signing-certificate` then you must also specify `--private-key`. If you specify these parameters, the command creates a signed enclave image file. The command output will include and additional PCR, `PCR8`, which can be used in condition keys for KMS key policies. For more information, see [Where to get an enclave's measurements](set-up-attestation.md#where).  
Ensure that the specified certificate is still valid. If you attempt to start an enclave with an enclave image file that is signed with a certificate that is no longer valid, the `nitro-cli run-enclave` fails with errors `E36`, `E39`, and `E11`.
Type: String  
Required: No

## Output


**`Measurements`**  
The cryptographic measurements (SHA384 hashes) that are unique to the enclave image file.  
Type: String

## Example


The following example converts a Docker image with a URI of `sample:latest` to an enclave image file named `sample.eif`.

**Command**

```
nitro-cli build-enclave --docker-uri sample:latest --output-file sample.eif
```

**Output**

```
Enclave Image successfully created.
{
  "Measurements": {
    "HashAlgorithm": "Sha384 { ... }",
    "PCR0": "EXAMPLE59044e337c00068c2c033546641e37aa466b853ca486dd149f641f15071961db2a0827beccea9cade3EXAMPLE",
    "PCR1": "EXAMPLE7783d0c23167299fbe5a69622490a9bdf82e94a0a1a48b0e7c56130c0c1e6555de7c0aa3d7901fbc58EXAMPLE",
    "PCR2": "EXAMPLE4b51589e8374b7f695b4649d1f1e9b528b05ab75a49f9a0a4a1ec36be81280caab0486f660b9207ac0EXAMPLE"
  }
}
```

The following example converts a Docker image with a URI of `sample:latest` to an enclave image file named `sample.eif`, and signs it using a KMS key.

**Command**

```
nitro-cli build-enclave --docker-uri sample:latest --output-file sample.eif --private-key arn:aws:kms:eu-west-1:123456789321:key/abcdef12-3456-789a-bcde-111122223333 --signing-certificate certificate.pem
```

**Output**

```
Enclave Image successfully created.{
"Measurements": {
"HashAlgorithm": "Sha384 { ... }",
    "PCR0": "EXAMPLE59044e337c00068c2c033546641e37aa466b853ca486dd149f641f15071961db2a0827beccea9cade3EXAMPLE",
    "PCR1": "EXAMPLE7783d0c23167299fbe5a69622490a9bdf82e94a0a1a48b0e7c56130c0c1e6555de7c0aa3d7901fbc58EXAMPLE",
    "PCR2": "EXAMPLE4b51589e8374b7f695b4649d1f1e9b528b05ab75a49f9a0a4a1ec36be81280caab0486f660b9207ac0EXAMPLE",
    "PCR8": "EXAMPLEdcca7f74398ae152d6ee245d8ac2cd430fb63644b46bf47b7d36b53b91c7597edda2d5df772cc81b72EXAMPLE"
  }
}
```

# nitro-cli run-enclave


Launches a new enclave. This command partitions the specified number of vCPUs and the amount of memory from the Amazon EC2 parent instance to create the enclave. You also need to provide an enclave image file (`.eif`) that contains the operating system and the applications that you want to run inside the enclave.

**Important**  
If you attempt to start an enclave with an enclave image file that is signed with a certificate that is no longer valid, the `nitro-cli run-enclave` command fails with errors `E36`, `E39`, and `E11`.

## Syntax


```
nitro-cli run-enclave 
    [--enclave-name enclave_name] 
    [--cpu-count number_of_vcpus 
    --cpu-ids list_of_vcpu_ids] 
    --memory amount_of_memory_in_MiB 
    --eif-path path_to_enclave_image_file 
    [--enclave-cid cid_number] 
    [--debug-mode]
    [--attach-console]
```

Alternatively, pass the enclave settings using a JSON file as follows.

```
nitro-cli run-enclave --config config_file.json
```

The following is an example JSON file.

```
{
    "enclave_name": enclave_name,
    "cpu_count": number_of_vcpus,
    "cpu_ids": list_of_vcpu_ids,
    "memory_mib": amount_of_memory_in_MiB,
    "eif_path": "path_to_enclave_image_file",
    "enclave_cid": cid_number,
    "debug_mode": true|false,
    "attach_console": true|false
}
```

## Options


**`--enclave-name`**  
A unique name for the enclave. You can use this name to reference the enclave when using the `nitro-cli console` and `nitro-cli terminate-enclave` commands.  
If you do not specify a name, the name of the enclave image file (.eif) is used as the enclave name.  
  
Type: String  
Required: No

**`--cpu-count`**  
The number of vCPUs to allocate to the enclave.  
+ Amazon EC2 instances support multithreading, which enables multiple threads to run concurrently on a single CPU core. Each thread is represented as a virtual CPU (vCPU) on the instance. For more information about vCPUs, see [Optimize CPU options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) in the *Amazon EC2 User Guide*.
+ If the parent instance is enabled for multithreading, you must specify an even number of vCPUs.
The number of vCPUs that you can allocate to an enclave depends on the size and configuration of the parent instance. If the parent instance is enabled for multithreading, you must leave at least 2 vCPUs for the parent instance. If multithreading is not enabled, you must leave at least 1 vCPU for the parent instance. For example, if your parent instance has 4 vCPUs and it is enabled for multithreading, you can allocate up to 2 vCPUs to the enclave.  
You must specify either `--cpu-count` or `--cpu-ids`. If you specify this option, omit `--cpu-ids`.  
Type: Integer  
Required: Conditional

**`--cpu-ids`**  
The IDs of the vCPUs to allocate to the enclave.  
+ Amazon EC2 instances support multithreading, which enables multiple threads to run concurrently on a single CPU core. Each thread is represented as a virtual CPU (vCPU) on the instance. For more information about vCPUs, see [Optimize CPU options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) in the *Amazon EC2 User Guide*.
+ If the parent instance is enabled for multithreading, you must specify an even number of vCPUs.
The number of vCPUs that you can allocate to an enclave depends on the size and configuration of the parent instance. If the parent instance is enabled for multithreading, you must leave at least 2 vCPUs for the parent instance. If multithreading is not enabled, you must leave at least 1 vCPU for the parent instance. For example, if your parent instance has 4 vCPUs and it is enabled for multithreading, you can allocate up to 2 vCPUs to the enclave.  
You must specify either `--cpu-count` or `--cpu-ids`. If you specify this option, omit `--cpu-count`.  
Type: String  
Required: Conditional

**`--memory`**  
The amount of memory (in MiB) to allocate to the enclave.  
The amount of memory that you can allocate to an enclave depends on the size of the parent instance and the applications that you intend to run on it. The specified amount of memory cannot exceed the amount of memory provided by the parent instance. You must leave enough memory for the applications running on the parent instance. You must allocate a minimum of `64` MiB of memory to the enclave.  
Type: Integer (MiB)  
Required: Yes

**`--eif-path`**  
The path to the enclave image file.  
Type: String  
Required: Yes

**`--enclave-cid`**  
The context identifier (CID) for the enclave. The CID is the socket address used by the *vsock* socket. Only CIDs of `4` and higher can be specified. If you omit this option, a random CID is allocated to the enclave.  
Type: Integer  
Required: No

**`--debug-mode`**  
Indicates whether to run the enclave in debug mode. Specify this option to enable debug mode, or omit it to disable debug mode.  
If you enable debug mode, you can view the enclave's console in read-only mode using the `nitro-cli console` command. Enclaves booted in debug mode generate attestation documents with PCRs that are made up entirely of zeros.  
Required: No

**`--attach-console`**  
Attach the enclave console immediately after starting the enclave.

**`--config`**  
The path to a .json configuration file that specifies the parameters for the enclave. If you specify `--config`, the specified JSON file must include the required and optional parameters as described above, and you must not specify any other parameters in the command itself.  
Type: String  
Required: No

## Output


**`EnclaveName`**  
The unique name of the enclave.  
Type: String

**`EnclaveID`**  
The unique ID of the enclave.  
Type: String

**`ProcessID`**  
The process identifier (PID) of the process holding the enclave's resources.  
Type: String

**`EnclaveCID`**  
The context ID (CID) of the enclave.  
Type: Integer

**`NumberOfCPUs`**  
The number of vCPUs allocated to the enclave from the parent instance.  
Type: Integer

**`CPUIDs`**  
The IDs of the vCPUs allocated to the enclave from the parent instance.  
Type: String

**`MemoryMiB`**  
The amount of memory (in MiB) allocated to the enclave from the parent instance.  
Type: Integer

## Examples


### Example 1: Inline parameters


The following example creates an enclave with `2` vCPUs, `1600` MiB of memory, and a context ID of `10`. It also uses an enclave image file named `sample.eif`, which is located in the same directory from which the command is being run.

**Command**

```
nitro-cli run-enclave --enclave-name my-enclave --cpu-count 2 --memory 1600 --eif-path sample.eif --enclave-cid 10
```

**Output**

```
Start allocating memory...
Started enclave with enclave-cid: 10, memory: 1600 MiB, cpu-ids: [1, 3]
{
    "EnclaveName": "my_enclave",
    "EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
    "ProcessID": 12345,
    "EnclaveCID": 10,
    "NumberOfCPUs": 2,
    "CPUIDs": [
        1,
        3
    ],
    "MemoryMiB": 1600
}
```

### Example 2: Config file


The following example creates an enclave with `2` vCPUs, `1600` MiB of memory, and a context ID of `10`. It also uses an enclave image file named `sample.eif`, which is located in the same directory from which the command is being run.

**Command**

```
nitro-cli run-enclave --config enclave_config.json
```

The following is an example of the `enclave_config.json` file.

```
{
    "enclave_name": "my_enclave",
    "cpu_count": 2,
    "memory_mib": 1600,
    "eif_path": "sample.eif",
    "enclave_cid": 10,
    "debug_mode": true
}
```

**Output**

```
Start allocating memory...
Started enclave with enclave-cid: 10, memory: 1600 MiB, cpu-ids: [1, 3]
{
    "EnclaveName": "my_enclave",
    "EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
    "ProcessID": 12345,
    "EnclaveCID": 10,
    "NumberOfCPUs": 2,
    "CPUIDs": [
        1,
        3
    ],
    "MemoryMiB": 1600
}
```

# nitro-cli describe-enclaves


Describes an enclave.

## Syntax


```
nitro-cli describe-enclaves
```

## Options


This command has no options.

## Output


**`EnclaveName`**  
The unique name of the enclave.  
Type: String

**`EnclaveID`**  
The unique ID of the enclave.  
Type: String

**`ProcessID`**  
[Linux parent instances only] The process identifier (PID) of the process holding the enclave's resources.  
Type: String

**`EnclaveCID`**  
The unique context ID (CID) of the enclave. The CID is the socket address used by the *vsock* socket.  
Type: Integer

**`NumberOfCPUs`**  
The number of vCPUs allocated to the enclave from the parent instance.  
Type: Integer

**`CPUIDs`**  
[Linux parent instances only] The IDs of the vCPUs allocated to the enclave from the parent instance.  
Type: Integer

**`MemoryMiB`**  
The amount of memory (in MiB) allocated to the enclave from the parent instance.  
Type: Integer

**`State`**  
The current status of the enclave.  
Possible values: `running` \$1 `terminating`  
Type: String

**`Flags`**  
Indicates if the enclave is in debug mode. `None` indicates that debug mode is disabled. `Debug` indicates that debug mode is enabled.  
Possible values: `None` \$1 `Debug`  
Type: String

## Example


The following example describes an enclave.

**Command**

```
nitro-cli describe-enclaves
```

**Output**

```
[
    {
        "EnclaveName": "my_enclave",
        "EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
        "ProcessID": 12345,
        "EnclaveCID": 10,
        "NumberOfCPUs": 2,
        "CPUIDs": [
            1,
            3
        ],
        "MemoryMiB": 1600,
        "State": "RUNNING",
        "Flags": "NONE"
    }
]
```

# nitro-cli console


Enters a read-only console for the specified enclave. This enables you to view the enclave's console output to assist with troubleshooting. You can use this command only on an enclave that was launched with the `--debug-mode` option.

## Syntax


```
nitro-cli console 
    [--enclave-name enclave_name]
    [--enclave-id enclave_id] 
    [--disconnect-timeout number_of_seconds]
```

## Options


**`--enclave-name`**  
The unique name of the enclave. You must specify either `--enclave-name` or `--enclave-id`.  
Type: String  
Required: Conditional

**`--enclave-id`**  
The unique ID of the enclave. You must specify either `--enclave-id` or `--enclave-name`.  
Type: String  
Required: Conditional

**`--disconnect-timeout`**  
The number of seconds after which to automatically disconnect idle console sessions.  
Type: Integer  
Required: No

## Example


The following command enters a read-only console for an enclave with an ID of `i-05f6ed443ae428c95-enc173dfe3e2b1c87b`. The session automatically disconnects if the connection is idle for `60` seconds.

**Command**

```
nitro-cli console --enclave-id i-05f6ed443ae428c95-enc173dfe3e2b1c87b --disconnect-timeout 60
```

# nitro-cli describe-eif


Describes the specified enclave image file (`.eif`). The output is a static description of the enclave image file that includes the enclave image file version, build measurements, signing certificate information, the result of the CRC and signature check, and the metadata added at build time.

## Syntax


```
nitro-cli describe-eif 
    --eif-path path_to_enclave_image_file
```

## Options


**`--eif-path`**  
The path to the enclave image file.  
Type: String  
Required: Yes

## Output


**`Measurements`**  
The cryptographic measurements (SHA384 hashes) that are unique to the enclave image file.  
Type: String

## Example


The following example describes an enclave image file named `sample.eif`.

**Command**

```
nitro-cli describe-eif --eif-path image.eif
```

**Output**

```
{
  "Measurements": {
    "HashAlgorithm": "Sha384 { ... }",
    "PCR0": "EXAMPLE59044e337c00068c2c033546641e37aa466b853ca486dd149f641f15071961db2a0827beccea9cade3EXAMPLE",
    "PCR1": "EXAMPLE7783d0c23167299fbe5a69622490a9bdf82e94a0a1a48b0e7c56130c0c1e6555de7c0aa3d7901fbc58EXAMPLE",
    "PCR2": "EXAMPLE4b51589e8374b7f695b4649d1f1e9b528b05ab75a49f9a0a4a1ec36be81280caab0486f660b9207ac0EXAMPLE"
  }
}
```

# nitro-cli sign-eif


Signs an existing enclave image file (`.eif`). You must specify a private key and a signing certificate. For the private key, you can use a KMS key ARN or a local private key file.

The signature is added to the enclave image file (`.eif`). The signature is updated if it already exists in the enclave image file.

The command returns a set of measurements (SHA384 hashes) that are unique to the enclave image file. These measurements are provided in the form of platform configuration registers (PCRs). The PCRs are used during the enclave's attestation process. For more information, see [Nitro Enclaves concepts](nitro-enclave-concepts.md).

For example, when using Nitro Enclaves with AWS Key Management Service (AWS KMS), you can specify these PCRs in condition keys for customer managed keys policies. When an application in the enclave performs an AWS KMS operation, AWS KMS compares the PCRs in the enclave's signed attestation document with the PCRs specified in the condition keys of the KMS key policy before allowing the operation.

## Syntax


```
nitro-cli sign-eif
    --eif-path /path/to/eif
    --private-key key
    --signing-certificate certificate.pem
```

## Options


**`--eif-path`**  
The path to the enclave image file.  
Type: String  
Required: Yes

**`--private-key`**  
The private key to use to sign the enclave image file. This can be a KMS key ARN, or a path to a local private key file. Only ECDSA keys are supported for signing.  
Type: String  
Required: Yes

**`--signing-certificate`**  
The signing key to use to sign the enclave image file.  
Type: String  
Required: Yes

**Important**  
Ensure that the specified certificate is valid. If you start an enclave with an invalid certificate, then the `nitro-cli run-enclave` command fails with errors `E36`, `E39`, and `E11`. For more information, see [Nitro Enclaves CLI error codes](https://docs.aws.amazon.com/enclaves/latest/user/cli-errors.html).

## Output


**`Measurements`**  
The cryptographic measurements (SHA384 hashes) that are unique to the enclave image file. The command output includes an additional PCR, `PCR8` that can be used in condition keys for KMS key policies. For more information, see [Where to get an enclave's measurements](https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html#where).  
Type: String

## Example


The following example signs the enclave image file `sample.eif` with the given KMS key.

**Command**

```
nitro-cli sign-eif --eif-path sample.eif --private-key arn:aws:kms:eu-west-1:123456789321:key/abcdef12-3456-789a-bcde-111122223333 --signing-certificate certificate.pem
```

**Output**

```
Enclave Image successfully signed.{
"Measurements": {
"HashAlgorithm": "Sha384 { ... }",
    "PCR0": "EXAMPLE59044e337c00068c2c033546641e37aa466b853ca486dd149f641f15071961db2a0827beccea9cade3EXAMPLE",
    "PCR1": "EXAMPLE7783d0c23167299fbe5a69622490a9bdf82e94a0a1a48b0e7c56130c0c1e6555de7c0aa3d7901fbc58EXAMPLE",
    "PCR2": "EXAMPLE4b51589e8374b7f695b4649d1f1e9b528b05ab75a49f9a0a4a1ec36be81280caab0486f660b9207ac0EXAMPLE",
    "PCR8": "EXAMPLEdcca7f74398ae152d6ee245d8ac2cd430fb63644b46bf47b7d36b53b91c7597edda2d5df772cc81b72EXAMPLE"
  }
}
```

# nitro-cli pcr


Returns the platform configuration register (PCR) value for a specified input file or PEM certificate. You can use this command to identify the files and signing certificate that were used to sign an enclave by comparing the command output with PCR values in the enclave's build measurements.

## Syntax


```
nitro-cli pcr 
    [--input path_to_file]
    [--signing-certificate path_to_certificate]
```

## Options


**`--input`**  
The path to the file for which to generate the platform configuration register (PCR) value.  
You must specify either `--input` or `--signing-certificate`.  
Type: String  
Required: Conditional

**`--signing-certificate`**  
The path to the PEM certificate for which to generate PCR8. This option is used to specifically request the PCR8 value by performing deserialisation of the certificate and PEM format validation.  
You must specify either `--input` or `--signing-certificate`.  
Type: String  
Required: Conditional

## Output


**`PCR`**  
The platform configuration register (PCR) value for the specified input file or PEM certificate.  
Type: String

## Example


The following example generates the PCR8 value for a PEM certificate named `cert.pem`.

**Command**

```
nitro-cli pcr --signing-certificate cert.pem
```

**Output**

```
{
    "PCR8": "example39de75e8ed2939e95examplea96f2c79eaf5d5ac3bacf2cb76c75a31f9examplef55b29f0acd256b8example"
}
```

# nitro-cli terminate-enclave


Terminates a specific enclave or all enclaves owned by the current user.

To terminate a specific enclave, specify `--enclave-name` or `--enclave-id`. To terminate all enclaves, specify `--all`.

## Syntax


```
nitro-cli terminate-enclave 
    [--enclave-id enclave_id]
    [--enclave-name enclave_name]
    [--all]
```

## Options


**`--enclave-name`**  
The unique name of the enclave to terminate. You must specify either `--enclave-name` or `--enclave-id`.  
Type: String  
Required: Conditional

**`--enclave-id`**  
The unique ID of the enclave to terminate. You must specify either `--enclave-id` or `--enclave-name`.  
Type: String  
Required: Conditional

**`--all`**  
Indicates whether to terminate all of the enclaves owned by the current user. If you specify this option, omit `--enclave-id` and `--enclave-name`.  
Required: No

## Example


### Example: Terminate specific enclave


The following example terminates an enclave with an ID of `i-abc12345def67890a-enc9876abcd543210ef12`.

**Command**

```
nitro-cli terminate-enclave --enclave-id i-abc12345def67890a-enc9876abcd543210ef12
```

**Output**

```
Successfully terminated enclave i-abc12345def67890a-enc9876abcd543210ef12.
{
  "EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
  "Terminated": true
}
```

### Example: Terminate all running enclaves


The following example terminates all of the enclaves owned by the current user.

**Command**

```
nitro-cli terminate-enclave --all
```

**Output**

```
Successfully terminated enclave i-abc12345def67890a-enc9876abcd543210ef12.
{
  "EnclaveID": "i-abc12345def67890a-enc9876abcd543210ef12",
  "Terminated": true
}
```