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


---

# 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/configuration-and-management/vhsm-lease.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.