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