> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/virtual-hsm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/virtual-hsm/cli/configuration-and-management/vhsm-lease.md).

# vhsm lease

The `vhsm lease` command groups subcommands for interacting with leases attached to secrets. For leases attached to tokens, use the `vhsm token` subcommand.

{% hint style="info" %}
Ensure that you have the id of the lease that you would like to interact with. 
{% endhint %}

### Usage

```
vhsm lease <subcommand> [options] [args]
```

#### Subcommands

| Command                         | Description                             |
| ------------------------------- | --------------------------------------- |
| [`lookup`](#vault-lease-lookup) | Retrieve lease information by lease ID. |
| [`renew`](#vault-lease-renew)   | Renew the lease of a secret.            |
| [`revoke`](#vault-lease-revoke) | Revoke leases and secrets.              |

***

### `vhsm lease lookup`

The `lookup` command retrieves information on the lease of a secret.

#### Example

```
vhsm lease lookup database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
```

**Output**

```
Key             Value
---             -----
expire_time     2021-03-17T11:55:50.755313-05:00
id              database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
issue_time      2021-03-17T11:45:50.755312-05:00
last_renewal    <nil>
renewable       true
ttl             9m52s
```

***

### `vhsm lease renew`

Renews the lease on a secret, extending its usage before revocation by vHSM. Renewing a lease does not change the contents of the secret.

#### Example

```
vhsm lease renew database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
```

**Output**

```
Key                Value
---                -----
lease_id           database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
lease_duration     5m
lease_renewable    true
```

#### Options

| Flag                    | Description                                                               |
| ----------------------- | ------------------------------------------------------------------------- |
| `-increment <duration>` | Request a specific increment in seconds. vHSM may not honor this request. |

***

### `vhsm lease revoke`

Revokes the lease on a secret, invalidating the underlying secret.

**Example 1: Revoke a specific lease**

```
vhsm lease revoke database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
```

**Output**

```
Success! Revoked lease: database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
```

**Example 2: Revoke leases with a specific prefix**

```
vhsm lease revoke -prefix database/creds
```

**Output**

```
Success! Revoked any leases with prefix: database/creds
```

#### Options

| Flag            | Description                                                                                                      |
| --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `-force` (`-f`) | Delete the lease from vHSM even if secret engine revocation fails. Requires `-prefix`. Default: `false`.         |
| `-prefix`       | Treat the ID as a prefix instead of an exact lease ID, allowing multiple leases to be revoked. Default: `false`. |
| `-sync`         | Make the operation synchronous instead of queuing revocations in the background. Default: `false`.               |