> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plerion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# plerion access-grants

> List and review AWS resource access grants.

With **plerion access-grants**, you can list who has access to your AWS resources, see counts and external principals, and record review decisions on each grant.

<Tip>
  For more about access grants in the Plerion dashboard, see [Resource access grants](/guides/platform/resource-access-grants/overview).
</Tip>

***

## Synopsis

```bash theme={"system"}
plerion access-grants <subcommand> [options]
```

***

## Subcommands

### list

List access grants with filtering. Newest grants come first.

```bash theme={"system"}
plerion access-grants list [options]
```

#### Options

| Flag | Type | Description |
| - | - | - |
| `--ids` | string | Filter by grant IDs (comma-separated) |
| `--grant-origin` | string | `external` (outside your AWS organization) or `internal` |
| `--trust-statuses` | string | `trusted`, `untrusted` (comma-separated) |
| `--grant-scopes` | string | `cross-org`, `federated`, `public`, `same-account`, `same-org`, `aws-service` (comma-separated) |
| `--mechanisms` | string | How the access is granted: `resource_policy`, `trust_policy`, `ram_share`, `attribute_share` (comma-separated) |
| `--principal-types` | string | Filter by principal type, such as `aws_account`, `aws_role`, or `public` (comma-separated) |
| `--resource-types` | string | Filter by resource type (e.g. `AWS::S3::Bucket`, comma-separated) |
| `--integration-ids` | string | Filter by integration IDs (comma-separated) |
| `--aws-account-ids` | string | AWS accounts that own the granting resource (comma-separated 12-digit IDs) |
| `--principal-account-ids` | string | AWS accounts of the principal (comma-separated 12-digit IDs) |
| `--asset-name` | string | Substring match on the resource name or asset ID |
| `--principal` | string | Substring match on the principal |
| `--search` | string | Substring match across the principal, resource name, and asset ID |
| `--review-decisions` | string | `keep`, `remove`, `review_later`, `trust_until_review` (comma-separated). Grants with no decision are excluded |
| `--grantee` | string | Case-insensitive substring match on the recorded grantee |
| `--next-review-at-end` | string | Only grants due for review by this ISO 8601 date-time |
| `--per-page` | number | Results per page, 1 to 1000 (default: 50) |
| `--all` | flag | Fetch all pages automatically |

### get

```bash theme={"system"}
plerion access-grants get <id>
```

Grant IDs are UUIDs, as returned by `list`.

### stats

```bash theme={"system"}
plerion access-grants stats
```

Returns access grant counts for the tenant.

### external-principals

```bash theme={"system"}
plerion access-grants external-principals
```

Lists the external principals holding access, with the number of grants each holds.

### update

```bash theme={"system"}
plerion access-grants update <id> [options]
```

Records a review decision on a grant. Pass at least one option. Options you leave out keep their current value.

| Flag | Type | Description |
| - | - | - |
| `--review-decision` | string | `keep`, `remove`, `review_later`, or `trust_until_review`. `trust_until_review` also needs `--next-review-at` |
| `--review-comment` | string | Free-text review comment |
| `--next-review-at` | string | When the grant is next due for review (ISO 8601 date-time) |
| `--grantee` | string | The team, person or service accountable for this access (up to 256 characters) |
| `--clear-review-decision` | flag | Clear the review decision. Can't be combined with `--review-decision` |
| `--clear-review-comment` | flag | Clear the review comment. Can't be combined with `--review-comment` |
| `--clear-next-review-at` | flag | Clear the next review date. Can't be combined with `--next-review-at` |
| `--clear-grantee` | flag | Clear the grantee. Can't be combined with `--grantee` |

***

## Examples

```bash theme={"system"}
# Untrusted external grants
plerion access-grants list --grant-origin external --trust-statuses untrusted

# Public grants on S3 buckets, across all pages
plerion access-grants list --grant-scopes public --resource-types AWS::S3::Bucket --all --output json

# Grants due for review by the end of the year
plerion access-grants list --next-review-at-end 2026-12-31T23:59:59Z

# Counts and external principals
plerion access-grants stats
plerion access-grants external-principals

# Mark a grant for removal with a comment
plerion access-grants update 0f9a1c3e-5b7d-4c21-9e8f-2a6b4d10c7f3 \
  --review-decision remove --review-comment "Vendor contract ended"

# Clear the next review date
plerion access-grants update 0f9a1c3e-5b7d-4c21-9e8f-2a6b4d10c7f3 --clear-next-review-at
```

***

## Output columns

| Column | Description |
| - | - |
| ID | Grant ID |
| RESOURCE TYPE | Resource type of the granting resource |
| ASSET NAME | Name of the granting resource |
| AWS ACCOUNT ID | AWS account that owns the resource |
| REGION | Region of the resource (`global` for resources such as IAM roles) |
| SERVICE | AWS service |
| MECHANISM | How the access is granted |
| PRINCIPAL | Principal holding the access |
| PRINCIPAL TYPE | Principal type |
| SCOPE | Trust boundary, such as `cross-org` or `public` |
| ORIGIN | `external` or `internal` |
| TRUST STATUS | `trusted` or `untrusted` |
| BLOCKED BY RCP | Whether a resource control policy (RCP) blocks the access |
| REVIEW DECISION | Recorded review decision |
| GRANTEE | Recorded grantee |
| NEXT REVIEW AT | Next review date |
| REVIEWED BY | User who last reviewed the grant |
| REVIEWED AT | Review timestamp |
| FIRST OBSERVED AT | First observed timestamp |
| LAST OBSERVED AT | Last observed timestamp |

### Stats output columns

| Column | Description |
| - | - |
| TOTAL | All grants |
| EXTERNAL | Grants to principals outside your AWS organization |
| UNTRUSTED EXTERNAL | External grants that aren't trusted |
| CROSS ORG | Grants that cross an organization boundary |

### External principals output columns

| Column | Description |
| - | - |
| PRINCIPAL | External principal |
| PRINCIPAL TYPE | Principal type |
| PRINCIPAL ACCOUNT ID | AWS account of the principal |
| GRANT COUNT | Number of grants the principal holds |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.