# vhsm read

The `vhsm read` command retrieves data from vHSM at a specified path. It acts as a wrapper for an HTTP `GET` request, allowing users to:

* Read secrets
* Generate dynamic credentials
* Retrieve configuration details
* Access other stored data in a vHSM

### Usage

```sh
vhsm read [flags] <path>
```

* `<path>`: The path in vHSM where data is stored.

### Examples

#### 1. Read entity details for a given ID

```sh
vhsm read identity/entity/id/2f09126d-d161-abb8-2241-555886491d97
```

#### 2. Generate dynamic AWS credentials for a role

```sh
vhsm read aws/creds/my-role
```

***

### API vs CLI

If the Key/Value (K/V) v2 secrets engine is enabled at `secret/`, the following command reads secrets from `secret/data/customers`:

```sh
vhsm read secret/data/customers
```

This is equivalent to making a direct API request using `curl`:

```sh
curl --request GET --header "X-Vault-Token: $VAULT_TOKEN" \
    $VAULT_ADDR/v1/secret/data/customers
```

However, since the K/V secrets engine is commonly used, vHSM provides a dedicated `kv` command for better handling:

```sh
vhsm kv get -mount=secret customers
```

#### **Comparison of Methods**

| Method                 | Command                               | Output Format                               |
| ---------------------- | ------------------------------------- | ------------------------------------------- |
| **CLI (vault read)**   | `vhsm read secret/data/customers`     | Key-value format                            |
| **API (curl)**         | `curl --request GET ...`              | JSON format                                 |
| **CLI (vault kv get)** | `vhsm kv get -mount=secret customers` | Structured format optimized for K/V secrets |

***

### Flags

#### **Output options**

| Flag             | Default      | Description                                                                                                                                         |
| ---------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-field=<name>`  | `""` (empty) | Prints only the specified field, formatted according to `-format`. No trailing newline (ideal for piping to other processes).                       |
| `-format=<type>` | `"table"`    | Defines the output format. Valid options: `"table"`, `"json"`, `"yaml"`, or `"raw"`. Can also be set using the `VAULT_FORMAT` environment variable. |

***

### Additional information

For a full list of examples and paths, refer to the documentation corresponding to the specific secrets engine in use.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/virtual-hsm/cli/secret-management/vhsm-read.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.