> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Service key commands
description: Reference for creating, rotating, and revoking service keys used for programmatic API authentication.
category: CLI
last_verified: 2026-07-24
hideRightSidebar: true
---

**`agnt5 service-keys`** manages service keys — programmatic, project-scoped credentials for authenticating API calls outside the interactive CLI login flow, such as from CI/CD. A key can be scoped to an environment or pinned to a specific deployment.


**Commands**: `agnt5 service-keys list`, `create`, `get <id>`, `revoke <id>`, `rotate <id>`, `delete <id>`
**Aliases**: `agnt5 keys`, `agnt5 api-keys` for `agnt5 service-keys`
**Required**: `--project`/`-p` on `list` and `create`; `--name`/`-n` and `--project` on `create`
**Side effects**: `create` and `rotate` mint new key material (shown once); `revoke` and `delete` are irreversible


## Command summary

| Command | Purpose |
| --- | --- |
| `service-keys list` | List service keys for a project. |
| `service-keys create` | Create a new service key. |
| `service-keys get <id>` | Get details of a service key. |
| `service-keys revoke <id>` | Revoke a service key. |
| `service-keys rotate <id>` | Rotate a service key, issuing new material. |
| `service-keys delete <id>` | Permanently delete a service key. |

## `agnt5 service-keys list`

```bash
agnt5 service-keys list [options]
```

| Flag | Description |
| --- | --- |
| `--project <id>`, `-p` | Project ID. **Required.** |
| `--environment <id>`, `-e` | Filter by environment ID. |
| `--include-revoked` | Include revoked keys in the results. |

```bash
agnt5 service-keys list --project proj_9f2a
agnt5 service-keys list --project proj_9f2a --include-revoked
```

## `agnt5 service-keys create`

```bash
agnt5 service-keys create --name <name> --project <id> [options]
```

`--environment` and `--deployment` are mutually exclusive — scope a key to one environment, or pin it to a single deployment, not both.

| Flag | Description |
| --- | --- |
| `--name <name>`, `-n` | Name for the key. **Required.** |
| `--project <id>`, `-p` | Project ID. **Required.** |
| `--environment <id>`, `-e` | Environment ID. Mutually exclusive with `--deployment`. |
| `--deployment <id>` | Deployment ID to pin the key to. Mutually exclusive with `--environment`. |
| `--scopes <scope,...>`, `-s` | Permission scopes: `run`, `entity`, `workflow`, or `admin` (includes all). Default: `run`. |
| `--description <text>`, `-d` | Description. |
| `--expires-in <duration>` | Expiration, parsed as a Go duration — `h`/`m`/`s` units only, e.g. `24h`, `168h` (7 days), `720h` (30 days). No `d`/`w` day/week units. Default: never. |
| `--dry-run` | Show the request that would be sent without creating the key. |

```bash
agnt5 service-keys create --name ci-deploy --project proj_9f2a --scopes run,workflow
agnt5 service-keys create --name preview-runner --project proj_9f2a --environment env_preview --expires-in 168h
```

## `agnt5 service-keys get`

```bash
agnt5 service-keys get <key-id>
```

Gets details of a service key. No flags.

```bash
agnt5 service-keys get key_7c1e
```

## `agnt5 service-keys revoke`

```bash
agnt5 service-keys revoke <key-id> [options]
```

| Flag | Description |
| --- | --- |
| `--dry-run` | Show what would be revoked without executing. |

```bash
agnt5 service-keys revoke key_7c1e
```

## `agnt5 service-keys rotate`

```bash
agnt5 service-keys rotate <key-id> [options]
```

Issues new key material for the same key ID and invalidates the old material.

| Flag | Description |
| --- | --- |
| `--dry-run` | Show what would be rotated without executing. |

```bash
agnt5 service-keys rotate key_7c1e
```

## `agnt5 service-keys delete`

```bash
agnt5 service-keys delete <key-id> [options]
```

Permanently deletes a service key. This cannot be undone.

| Flag | Description |
| --- | --- |
| `--force`, `-f` | Skip the confirmation prompt. |
| `--dry-run` | Show what would be deleted without executing. |

```bash
agnt5 service-keys delete key_7c1e --force
```

## Next steps

- [Secrets](/docs/cli/secrets.md): store credentials your workers read at runtime, distinct from API service keys.
- [Deploy commands](/docs/cli/deploy.md): pin a key to a deployment for scoped CI access.
- [Auth commands](/docs/cli/auth.md): interactive login for local development instead of a service key.
- [Configuration](/docs/cli/configuration.md): environment and project resolution rules.