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

# idyl iam

> Manage identity and access

Manage Identity and Access Management (IAM) resources.

IAM controls who can access what within your accounts. This includes:

* Members: users with access to an account
* Groups: collections of users for easier permission management
* Service Accounts: machine identities for automation
* Policies: permission rules defining allowed/denied actions
* Access Profiles: reusable permission templates
* Assignments: bindings between identities and access profiles
* Personal Access Tokens (PATs): API tokens for your user
* Service Account Tokens (SATs): API tokens for service accounts

## Usage

```bash theme={null}
idyl iam
```

## Commands

| Command                    | Description                   |
| -------------------------- | ----------------------------- |
| `idyl iam access-profile`  | Manage access profiles        |
| `idyl iam assignment`      | Manage access assignments     |
| `idyl iam group`           | Manage groups                 |
| `idyl iam member`          | Manage account members        |
| `idyl iam pat`             | Manage personal access tokens |
| `idyl iam policy`          | Manage policies               |
| `idyl iam service-account` | Manage service accounts       |

## Inherited flags

| Flag                                 | Description                                                        |
| ------------------------------------ | ------------------------------------------------------------------ |
| `-a <string>, --account-id <string>` | Account ID to use, overriding the current context.                 |
| `-c <string>, --context <string>`    | Use the named context for this command.                            |
| `--homedir <string>`                 | Override the configuration directory. Defaults to \~/.config/idyl. |
| `-n <string>, --namespace <string>`  | Namespace to use for this command.                                 |
| `-o <string>, --output <string>`     | Output format (json\|yaml).                                        |
| `-p <string>, --profile <string>`    | Override the access profile for this command.                      |
| `--realm <string>`                   | Override the realm for this command.                               |
| `--subnet <string>`                  | Override the context subnet for this command.                      |

## Examples

```bash theme={null}
# List members in the current account
idyl iam member list

# Create a new group
idyl iam group create developers --description "Development team"

# Create a service account for CI/CD
idyl iam service-account create github-actions

# List policies
idyl iam policy list

# Create an access profile
idyl iam access-profile create dev-readonly

# Assign an access profile to a user
idyl iam assignment create --identity user@example.com --access-profile dev-readonly
```

## Subcommand reference

### `idyl iam access-profile`

Manage access profiles.

Access profiles are reusable permission templates that compose multiple policies.
They can be assigned to identities (users, groups, service accounts) to grant
permissions on specific accounts.

Access profiles can also be used to scope tokens (PATs and SATs) to restrict
the permissions of the token holder.

#### Usage

```bash theme={null}
idyl iam access-profile
```

#### Aliases

* `access-profiles`
* `ap`

#### Commands

| Command                                 | Description                                            |
| --------------------------------------- | ------------------------------------------------------ |
| `idyl iam access-profile attach-policy` | Add a policy to an access profile                      |
| `idyl iam access-profile create`        | Create a new access profile                            |
| `idyl iam access-profile delete`        | Delete an access profile                               |
| `idyl iam access-profile detach-policy` | Remove a policy from an access profile                 |
| `idyl iam access-profile edit`          | Edit an access profile                                 |
| `idyl iam access-profile get`           | Get access profile details or list all access profiles |
| `idyl iam access-profile list-policies` | List policies attached to an access profile            |

#### Examples

```bash theme={null}
# List all access profiles
idyl iam access-profile list

# Get details of an access profile
idyl iam access-profile get dev-readonly

# Create an access profile
idyl iam access-profile create dev-readonly --description "Read-only access to dev"

# Create an access profile with policies
idyl iam access-profile create dev-admin --policy-ids policy-id-1,policy-id-2

# Edit an access profile
idyl iam access-profile edit dev-readonly --set-description "Updated description"

# Delete an access profile
idyl iam access-profile delete dev-readonly

# Manage attached policies
idyl iam access-profile list-policies --access-profile dev-readonly
idyl iam access-profile attach-policy --access-profile dev-readonly --policy <policy-id>
idyl iam access-profile detach-policy --access-profile dev-readonly --policy <policy-id>
```

### `idyl iam access-profile attach-policy`

Add a policy to an access profile.

#### Usage

```bash theme={null}
idyl iam access-profile attach-policy [flags]
```

#### Flags

| Flag                        | Description                          |
| --------------------------- | ------------------------------------ |
| `--access-profile <string>` | Required. Access profile name or ID. |
| `--policy <string>`         | Required. Policy ID.                 |

#### Examples

```bash theme={null}
# Add a policy by ID
idyl iam access-profile attach-policy --access-profile dev-readonly --policy <policy-id>
```

### `idyl iam access-profile create`

Create a new access profile.

#### Usage

```bash theme={null}
idyl iam access-profile create <name> [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--description <string>`         | Description of the access profile.                     |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |
| `--policy-ids <string>`          | Comma-separated list of policy IDs to attach.          |

#### Examples

```bash theme={null}
# Create an access profile
idyl iam access-profile create dev-readonly

# Create an access profile with description
idyl iam access-profile create dev-readonly --description "Read-only access to dev namespace"

# Create an access profile with policies (comma-separated UUIDs)
idyl iam access-profile create dev-admin --policy-ids id1,id2,id3
```

### `idyl iam access-profile delete`

Delete an access profile by name or ID.

System access profiles cannot be deleted.
Deleting an access profile will remove all assignments using it.

#### Usage

```bash theme={null}
idyl iam access-profile delete <name-or-id> [flags]
```

#### Flags

| Flag        | Description                |
| ----------- | -------------------------- |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
# Delete an access profile (with confirmation)
idyl iam access-profile delete dev-readonly

# Delete without confirmation
idyl iam access-profile delete dev-readonly --yes
```

### `idyl iam access-profile detach-policy`

Remove a policy from an access profile.

#### Usage

```bash theme={null}
idyl iam access-profile detach-policy [flags]
```

#### Flags

| Flag                        | Description                          |
| --------------------------- | ------------------------------------ |
| `--access-profile <string>` | Required. Access profile name or ID. |
| `--policy <string>`         | Required. Policy ID.                 |
| `-y, --yes`                 | Skip confirmation prompts.           |

#### Examples

```bash theme={null}
# Remove a policy (with confirmation)
idyl iam access-profile detach-policy --access-profile dev-readonly --policy <policy-id>

# Remove without confirmation
idyl iam access-profile detach-policy --access-profile dev-readonly --policy <policy-id> --yes
```

### `idyl iam access-profile edit`

Edit an access profile's settings.

Only the description can be updated. To modify attached policies, use:
idyl iam access-profile attach-policy/detach-policy

System access profiles cannot be edited.

#### Usage

```bash theme={null}
idyl iam access-profile edit <name-or-id> [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |
| `--set-description <string>`     | Set the access profile description.                    |

#### Examples

```bash theme={null}
# Update description
idyl iam access-profile edit dev-readonly --set-description "Updated description"
```

### `idyl iam access-profile get`

Get details of a specific access profile, or list all access profiles.

With no arguments, lists all access profiles.
With a name or ID argument, gets details of that specific access profile.

#### Usage

```bash theme={null}
idyl iam access-profile get [name-or-id] [flags]
```

#### Aliases

* `list`
* `ls`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List all access profiles
idyl iam access-profile get

# Get access profile by name
idyl iam access-profile get dev-readonly

# Get access profile by ID
idyl iam access-profile get <access-profile-id>

# Get access profile in JSON format
idyl iam access-profile get dev-readonly -o json
```

### `idyl iam access-profile list-policies`

List all policies attached to an access profile.

#### Usage

```bash theme={null}
idyl iam access-profile list-policies [flags]
```

#### Aliases

* `ls-policies`
* `get-policies`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--access-profile <string>`      | Required. Access profile name or ID.                   |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List policies by access profile name
idyl iam access-profile list-policies --access-profile dev-readonly

# List policies by access profile ID
idyl iam access-profile list-policies --access-profile <access-profile-id>
```

### `idyl iam assignment`

Manage access assignments within the current account.

Assignments bind an identity (user, group, or service account) to an access
profile, granting the permissions defined in that profile. The assignment
also specifies a target account where the permissions apply.

Identity formats:

* User email: [user@example.com](mailto:user@example.com)
* Group: group:\{group-id}
* Service Account: sa:\{service-account-id}

#### Usage

```bash theme={null}
idyl iam assignment
```

#### Aliases

* `assignments`

#### Commands

| Command                      | Description          |
| ---------------------------- | -------------------- |
| `idyl iam assignment create` | Create an assignment |
| `idyl iam assignment delete` | Delete an assignment |
| `idyl iam assignment get`    | List assignments     |

#### Examples

```bash theme={null}
# List all assignments
idyl iam assignment list

# Create an assignment for a user
idyl iam assignment create --identity user@example.com --access-profile dev-readonly --target-account-id <account-id>

# Create an assignment for a group
idyl iam assignment create --identity group:<group-id> --access-profile admin --target-account-id <account-id>

# Create an assignment for a service account
idyl iam assignment create --identity sa:<sa-id> --access-profile deploy-only --target-account-id <account-id>

# Delete an assignment
idyl iam assignment delete <assignment-id>
```

### `idyl iam assignment create`

Create a new assignment binding an identity to an access profile.

Identity formats:

* User email: [user@example.com](mailto:user@example.com)
* Group: group:\{group-id}
* Service Account: sa:\{service-account-id}

#### Usage

```bash theme={null}
idyl iam assignment create [flags]
```

#### Flags

| Flag                             | Description                                                         |
| -------------------------------- | ------------------------------------------------------------------- |
| `--access-profile <string>`      | Required. Access profile ID or name.                                |
| `--identity <string>`            | Required. Identity to assign: an email address, group:id, or sa:id. |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`.              |
| `--target-account-id <string>`   | Required. Target account ID where the permissions apply.            |

#### Examples

```bash theme={null}
# Assign a user to an access profile
idyl iam assignment create --identity user@example.com --access-profile dev-readonly --target-account-id <account-id>

# Assign a group to an access profile
idyl iam assignment create --identity group:<group-id> --access-profile admin --target-account-id <account-id>

# Assign a service account to an access profile
idyl iam assignment create --identity sa:<service-account-id> --access-profile deploy-only --target-account-id <account-id>
```

### `idyl iam assignment delete`

Delete an assignment by ID.

This removes the identity's permissions granted by this assignment.

#### Usage

```bash theme={null}
idyl iam assignment delete <assignment-id> [flags]
```

#### Flags

| Flag        | Description                |
| ----------- | -------------------------- |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
# Delete an assignment (with confirmation)
idyl iam assignment delete <assignment-id>

# Delete without confirmation
idyl iam assignment delete <assignment-id> --yes
```

### `idyl iam assignment get`

List all assignments in the current account.

#### Usage

```bash theme={null}
idyl iam assignment get [flags]
```

#### Aliases

* `list`
* `ls`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List all assignments
idyl iam assignment get

# List in JSON format
idyl iam assignment get -o json
```

### `idyl iam group`

Manage groups within the current account.

Groups are collections of users that simplify permission management.
Instead of assigning access profiles to individual users, you can assign
them to a group, and all members inherit those permissions.

#### Usage

```bash theme={null}
idyl iam group
```

#### Aliases

* `groups`

#### Commands

| Command                        | Description                          |
| ------------------------------ | ------------------------------------ |
| `idyl iam group add-member`    | Add a member to a group              |
| `idyl iam group create`        | Create a new group                   |
| `idyl iam group delete`        | Delete a group                       |
| `idyl iam group edit`          | Edit a group                         |
| `idyl iam group get`           | Get group details or list all groups |
| `idyl iam group list-members`  | List members of a group              |
| `idyl iam group remove-member` | Remove a member from a group         |

#### Examples

```bash theme={null}
# List all groups
idyl iam group list

# Get details of a group
idyl iam group get developers

# Create a new group
idyl iam group create developers --description "Development team"

# Edit a group
idyl iam group edit developers --set-description "Updated description"

# Delete a group
idyl iam group delete developers

# Manage group members
idyl iam group list-members --group developers
idyl iam group add-member --group developers --identity user@example.com
idyl iam group remove-member --group developers --identity user@example.com
```

### `idyl iam group add-member`

Add a member to a group.

The identity should be an email address. The user must already be a member
of the account.

#### Usage

```bash theme={null}
idyl iam group add-member [flags]
```

#### Flags

| Flag                  | Description                 |
| --------------------- | --------------------------- |
| `--group <string>`    | Required. Group name or ID. |
| `--identity <string>` | Required. Identity to add.  |

#### Examples

```bash theme={null}
# Add a user to a group
idyl iam group add-member --group developers --identity user@example.com
```

### `idyl iam group create`

Create a new group in the current account.

#### Usage

```bash theme={null}
idyl iam group create <name> [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--description <string>`         | Description of the group.                              |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# Create a group
idyl iam group create developers

# Create a group with description
idyl iam group create developers --description "Development team"
```

### `idyl iam group delete`

Delete a group by name or ID.

This action removes the group and all its member associations.
It does not delete the members themselves.

#### Usage

```bash theme={null}
idyl iam group delete <name-or-id> [flags]
```

#### Flags

| Flag        | Description                |
| ----------- | -------------------------- |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
# Delete a group (with confirmation)
idyl iam group delete developers

# Delete without confirmation
idyl iam group delete developers --yes
```

### `idyl iam group edit`

Edit a group's settings.

Only the specified flags are updated; other settings remain unchanged.

#### Usage

```bash theme={null}
idyl iam group edit <name-or-id> [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |
| `--set-description <string>`     | Set the group description.                             |
| `--set-name <string>`            | Set the group name.                                    |

#### Examples

```bash theme={null}
# Update name
idyl iam group edit developers --set-name dev-team

# Update description
idyl iam group edit developers --set-description "Updated description"

# Update both
idyl iam group edit developers --set-name dev-team --set-description "New description"
```

### `idyl iam group get`

Get details of a specific group, or list all groups.

With no arguments, lists all groups.
With a name or ID argument, gets details of that specific group.

#### Usage

```bash theme={null}
idyl iam group get [name-or-id] [flags]
```

#### Aliases

* `list`
* `ls`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List all groups
idyl iam group get

# Get group by name
idyl iam group get developers

# Get group by ID
idyl iam group get <group-id>

# Get group in JSON format
idyl iam group get developers -o json
```

### `idyl iam group list-members`

List all members of a group.

#### Usage

```bash theme={null}
idyl iam group list-members [flags]
```

#### Aliases

* `ls-members`
* `get-members`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--group <string>`               | Required. Group name or ID.                            |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List members by group name
idyl iam group list-members --group developers

# List members by group ID
idyl iam group list-members --group <group-id>
```

### `idyl iam group remove-member`

Remove a member from a group.

This removes the user from the group but does not remove them from the account.

#### Usage

```bash theme={null}
idyl iam group remove-member [flags]
```

#### Flags

| Flag                  | Description                   |
| --------------------- | ----------------------------- |
| `--group <string>`    | Required. Group name or ID.   |
| `--identity <string>` | Required. Identity to remove. |
| `-y, --yes`           | Skip confirmation prompts.    |

#### Examples

```bash theme={null}
# Remove a user from a group
idyl iam group remove-member --group developers --identity user@example.com

# Remove without confirmation
idyl iam group remove-member --group developers --identity user@example.com --yes
```

### `idyl iam member`

Manage members of the current account.

Members are users who have access to an account. Their permissions are
determined by access profile assignments, not by the membership itself.

#### Usage

```bash theme={null}
idyl iam member
```

#### Aliases

* `members`

#### Commands

| Command                  | Description                      |
| ------------------------ | -------------------------------- |
| `idyl iam member add`    | Add a member to the account      |
| `idyl iam member get`    | List account members             |
| `idyl iam member remove` | Remove a member from the account |

#### Examples

```bash theme={null}
# List all members
idyl iam member list

# Add a member
idyl iam member add user@example.com

# Remove a member
idyl iam member remove user@example.com
```

### `idyl iam member add`

Add a member to the current account.

The identity should be an email address. The user must already exist in the
system (i.e., have logged in before).

#### Usage

```bash theme={null}
idyl iam member add <identity> [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# Add a user as a member
idyl iam member add user@example.com
```

### `idyl iam member get`

List all members of the current account.

#### Usage

```bash theme={null}
idyl iam member get [flags]
```

#### Aliases

* `list`
* `ls`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List all members
idyl iam member get

# List in JSON format
idyl iam member get -o json
```

### `idyl iam member remove`

Remove a member from the current account.

This removes the user's access to the account but does not delete the user.
The user can be re-added later if needed.

#### Usage

```bash theme={null}
idyl iam member remove <identity> [flags]
```

#### Flags

| Flag        | Description                |
| ----------- | -------------------------- |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
# Remove a member
idyl iam member remove user@example.com

# Remove without confirmation
idyl iam member remove user@example.com --yes
```

### `idyl iam pat`

Manage personal access tokens (PATs) for API authentication.

PATs allow you to authenticate to the API without using the interactive login flow.
They are useful for scripts, CI/CD pipelines, and other automation.

Each PAT can optionally be scoped to an access profile for restricted permissions.
If no access profile is specified, the PAT inherits your full permissions.

#### Usage

```bash theme={null}
idyl iam pat
```

#### Aliases

* `pats`

#### Commands

| Command               | Description                    |
| --------------------- | ------------------------------ |
| `idyl iam pat create` | Create a personal access token |
| `idyl iam pat get`    | List personal access tokens    |
| `idyl iam pat revoke` | Revoke a personal access token |

#### Examples

```bash theme={null}
# List all your PATs
idyl iam pat list

# Create a PAT
idyl iam pat create --name "My CLI Token"

# Create a PAT with expiration
idyl iam pat create --name "Temp Token" --expires 24h

# Create a PAT with restricted permissions
idyl iam pat create --name "Read-only Token" --access-profile dev-readonly

# Revoke a PAT
idyl iam pat revoke <pat-id>
```

### `idyl iam pat create`

Create a new personal access token.

The token secret is only shown once at creation time. Store it securely.

#### Usage

```bash theme={null}
idyl iam pat create [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--access-profile <string>`      | Access profile ID that scopes the token.               |
| `--description <string>`         | Description of the token.                              |
| `--expires <string>`             | Token expiration, such as 24h, 7d, 30d, or 365d.       |
| `--name <string>`                | Required. Name for the token.                          |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# Create a PAT
idyl iam pat create --name "My CLI Token"

# Create a PAT with description
idyl iam pat create --name "CI Token" --description "Used by GitHub Actions"

# Create a PAT with expiration (duration format: 24h, 7d, 30d, 365d)
idyl iam pat create --name "Temp Token" --expires 24h

# Create a PAT with restricted permissions
idyl iam pat create --name "Read-only Token" --access-profile dev-readonly
```

### `idyl iam pat get`

List all personal access tokens.

#### Usage

```bash theme={null}
idyl iam pat get [flags]
```

#### Aliases

* `list`
* `ls`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List all PATs
idyl iam pat get

# List in JSON format
idyl iam pat get -o json
```

### `idyl iam pat revoke`

Revoke a personal access token.

This immediately invalidates the token. Any requests using this token will fail.

#### Usage

```bash theme={null}
idyl iam pat revoke <pat-id> [flags]
```

#### Flags

| Flag        | Description                |
| ----------- | -------------------------- |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
# Revoke a PAT (with confirmation)
idyl iam pat revoke <token-id>

# Revoke without confirmation
idyl iam pat revoke <token-id> --yes
```

### `idyl iam policy`

Manage IAM policies within the current account.

Policies define what actions are allowed or denied on which resources.
Each policy contains one or more statements with:

* Effect: "allow" or "deny"
* Actions: what can be done (e.g., "deployment:create", "\*:get")
* Resources: what it applies to (e.g., "namespace:dev/*", "*")

#### Usage

```bash theme={null}
idyl iam policy
```

#### Aliases

* `policies`

#### Commands

| Command                  | Description                             |
| ------------------------ | --------------------------------------- |
| `idyl iam policy create` | Create a new policy                     |
| `idyl iam policy delete` | Delete a policy                         |
| `idyl iam policy edit`   | Edit a policy                           |
| `idyl iam policy get`    | Get policy details or list all policies |

#### Examples

```bash theme={null}
# List all policies
idyl iam policy list

# Get details of a policy
idyl iam policy get dev-readonly

# Create a policy from JSON
idyl iam policy create dev-readonly --statements '[{"effect":"allow","actions":["*:get"],"resources":["namespace:dev/*"]}]'

# Edit a policy
idyl iam policy edit dev-readonly --set-description "Updated description"

# Delete a policy
idyl iam policy delete dev-readonly
```

### `idyl iam policy create`

Create a new policy in the current account.

The --statements flag accepts JSON array of policy statements.

Statement format:
\{
"effect": "allow" or "deny",
"actions": \["action:type", ...],
"resources": \["resource:path", ...]
}

Action wildcards: "deployment:*", "*:get", "*:*"
Resource wildcards: "namespace:dev/*", "namespace:*", "\*"

#### Usage

```bash theme={null}
idyl iam policy create <name> [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--description <string>`         | Description of the policy.                             |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |
| `--statements <string>`          | Required. JSON array of policy statements.             |

#### Examples

```bash theme={null}
# Create a read-only policy for dev namespace
idyl iam policy create dev-readonly \
  --description "Read-only access to dev namespace" \
  --statements '[{"effect":"allow","actions":["*:get","*:list"],"resources":["namespace:dev/*"]}]'

# Create an admin policy
idyl iam policy create admin \
  --statements '[{"effect":"allow","actions":["*:*"],"resources":["*"]}]'
```

### `idyl iam policy delete`

Delete a policy by name or ID.

System policies cannot be deleted.

#### Usage

```bash theme={null}
idyl iam policy delete <name-or-id> [flags]
```

#### Flags

| Flag        | Description                |
| ----------- | -------------------------- |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
# Delete a policy (with confirmation)
idyl iam policy delete dev-readonly

# Delete without confirmation
idyl iam policy delete dev-readonly --yes
```

### `idyl iam policy edit`

Edit a policy's settings.

Only the specified flags are updated; other settings remain unchanged.
System policies cannot be edited.

#### Usage

```bash theme={null}
idyl iam policy edit <name-or-id> [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |
| `--set-description <string>`     | Set the policy description.                            |
| `--set-statements <string>`      | Set the JSON array of policy statements.               |

#### Examples

```bash theme={null}
# Update description
idyl iam policy edit dev-readonly --set-description "Updated description"

# Update statements
idyl iam policy edit dev-readonly --set-statements '[{"effect":"allow","actions":["*:*"],"resources":["namespace:dev/*"]}]'
```

### `idyl iam policy get`

Get details of a specific policy, or list all policies.

With no arguments, lists all policies.
With a name or ID argument, gets details of that specific policy.

#### Usage

```bash theme={null}
idyl iam policy get [name-or-id] [flags]
```

#### Aliases

* `list`
* `ls`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List all policies
idyl iam policy get

# Get policy by name
idyl iam policy get dev-readonly

# Get policy by ID
idyl iam policy get <policy-id>

# Get policy in JSON format (useful for editing)
idyl iam policy get dev-readonly -o json
```

### `idyl iam service-account`

Manage service accounts within the current account.

Service accounts are machine identities used for CI/CD and automation.
Unlike user accounts, they survive employee turnover and provide stable
identities for automated processes.

Permissions are determined by assignments using identity format: sa:\{id}

#### Usage

```bash theme={null}
idyl iam service-account
```

#### Aliases

* `service-accounts`
* `sa`

#### Commands

| Command                                 | Description                                              |
| --------------------------------------- | -------------------------------------------------------- |
| `idyl iam service-account create`       | Create a new service account                             |
| `idyl iam service-account create-token` | Create a service account token                           |
| `idyl iam service-account delete`       | Delete a service account                                 |
| `idyl iam service-account get`          | Get service account details or list all service accounts |
| `idyl iam service-account list-tokens`  | List tokens for a service account                        |
| `idyl iam service-account revoke-token` | Revoke a service account token                           |

#### Examples

```bash theme={null}
# List all service accounts
idyl iam service-account list

# Get details of a service account
idyl iam service-account get github-actions

# Create a new service account
idyl iam service-account create github-actions --description "GitHub Actions CI/CD"

# Delete a service account
idyl iam service-account delete github-actions

# Manage service account tokens
idyl iam service-account list-tokens --service-account github-actions
idyl iam service-account create-token --service-account github-actions --name prod-token
idyl iam service-account revoke-token --service-account github-actions --token <token-id>
```

### `idyl iam service-account create`

Create a new service account in the current account.

#### Usage

```bash theme={null}
idyl iam service-account create <name> [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--description <string>`         | Description of the service account.                    |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# Create a service account
idyl iam service-account create github-actions

# Create a service account with description
idyl iam service-account create github-actions --description "GitHub Actions CI/CD"
```

### `idyl iam service-account create-token`

Create a new token for a service account.

The token secret is only shown once at creation time. Store it securely.

#### Usage

```bash theme={null}
idyl iam service-account create-token [flags]
```

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `--access-profile <string>`      | Access profile ID that scopes the token.               |
| `--expires <string>`             | Token expiration, such as 24h, 7d, or 30d.             |
| `--name <string>`                | Required. Name for the token.                          |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |
| `--service-account <string>`     | Required. Service account name or ID.                  |

#### Examples

```bash theme={null}
# Create a token
idyl iam service-account create-token --service-account github-actions --name prod-token

# Create a token with expiration (duration format: 24h, 7d, 30d)
idyl iam service-account create-token --service-account github-actions --name temp-token --expires 24h

# Create a token with an access profile for restricted permissions
idyl iam service-account create-token --service-account github-actions --name deploy-token --access-profile deploy-only
```

### `idyl iam service-account delete`

Delete a service account by name or ID.

This action is irreversible. All tokens associated with the service account
will be revoked immediately.

#### Usage

```bash theme={null}
idyl iam service-account delete <name-or-id> [flags]
```

#### Flags

| Flag        | Description                |
| ----------- | -------------------------- |
| `-y, --yes` | Skip confirmation prompts. |

#### Examples

```bash theme={null}
# Delete a service account (with confirmation)
idyl iam service-account delete github-actions

# Delete without confirmation
idyl iam service-account delete github-actions --yes
```

### `idyl iam service-account get`

Get details of a specific service account, or list all service accounts.

With no arguments, lists all service accounts.
With a name or ID argument, gets details of that specific service account.

#### Usage

```bash theme={null}
idyl iam service-account get [name-or-id] [flags]
```

#### Aliases

* `list`
* `ls`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |

#### Examples

```bash theme={null}
# List all service accounts
idyl iam service-account get

# Get service account by name
idyl iam service-account get github-actions

# Get service account by ID
idyl iam service-account get <service-account-id>

# Get service account in JSON format
idyl iam service-account get github-actions -o json
```

### `idyl iam service-account list-tokens`

List all tokens for a service account.

#### Usage

```bash theme={null}
idyl iam service-account list-tokens [flags]
```

#### Aliases

* `ls-tokens`
* `get-tokens`

#### Flags

| Flag                             | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `-o <string>, --output <string>` | Output format: table, json, or yaml. Default: `table`. |
| `--service-account <string>`     | Required. Service account name or ID.                  |

#### Examples

```bash theme={null}
# List tokens by service account name
idyl iam service-account list-tokens --service-account github-actions

# List tokens by service account ID
idyl iam service-account list-tokens --service-account <service-account-id>
```

### `idyl iam service-account revoke-token`

Revoke a service account token.

This immediately invalidates the token. Any requests using this token will fail.

#### Usage

```bash theme={null}
idyl iam service-account revoke-token [flags]
```

#### Flags

| Flag                         | Description                           |
| ---------------------------- | ------------------------------------- |
| `--service-account <string>` | Required. Service account name or ID. |
| `--token <string>`           | Required. Token ID.                   |
| `-y, --yes`                  | Skip confirmation prompts.            |

#### Examples

```bash theme={null}
# Revoke a token (with confirmation)
idyl iam service-account revoke-token --service-account github-actions --token <token-id>

# Revoke without confirmation
idyl iam service-account revoke-token --service-account github-actions --token <token-id> --yes
```