---
title: "agent-registrations"
description: "Agent registrations bound to the organization. The `machinemail agent-registrations` commands: arguments, flags, examples and the API routes they call."
canonical: "https://machinemail.dev/docs/cli/commands/agent-registrations"
---

# agent-registrations

> Agent registrations bound to the organization. The `machinemail agent-registrations` commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/agent-registrations

Agent registrations bound to the organization. Also spelled `agents`.

| Command                                                     | Summary                   |
| ----------------------------------------------------------- | ------------------------- |
| [`agent-registrations delete`](#agent-registrations-delete) | Revoke agent registration |
| [`agent-registrations get`](#agent-registrations-get)       | Get agent registration    |
| [`agent-registrations list`](#agent-registrations-list)     | List agent registrations  |

Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags).

## agent-registrations delete

Revoke agent registration.

Also: `machinemail agent-registrations rm`.

Revokes the registration; its tokens stop working immediately. Returns the registration with status: revoked (revoking twice is not an error). Requires an organization-scoped credential with api\_key\_delete.

```bash
machinemail agent-registrations delete <agent-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<agent-id>` | `string` | required | ID of the registration. |

#### Examples

```bash
machinemail agent-registrations delete reg_01m4fykg1y0000pkp9n2xbbzhg
```

#### API

- [`DELETE /v0/agent-registrations/{agent_id}`](https://machinemail.dev/docs/reference/api/agent-registrations#revoke-agent-registration)

## agent-registrations get

Get agent registration.

Requires an organization-scoped credential with api\_key\_read.

```bash
machinemail agent-registrations get <agent-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<agent-id>` | `string` | required | ID of the registration. |

#### Examples

```bash
machinemail agent-registrations get reg_01m4fykg1y0000pkp9n2xbbzhg
```

#### API

- [`GET /v0/agent-registrations/{agent_id}`](https://machinemail.dev/docs/reference/api/agent-registrations#get-agent-registration)

## agent-registrations list

List agent registrations.

Also: `machinemail agent-registrations ls`.

Agent registrations bound to the organization. Requires an organization-scoped credential with api\_key\_read; pod, inbox and sandbox credentials get 403.

```bash
machinemail agent-registrations list [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--limit <n>` | `integer` |  | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>` | `string` |  | next_page_token from the previous page. |
| `--ascending` | `boolean` |  | Sort oldest first. |
| `--status` | `pending_claim \| claimed \| revoked` |  | Only registrations with this status. |
| `--all` | `boolean` |  | Follow next_page_token and return every page. |

#### Examples

```bash
machinemail agent-registrations list
machinemail agent-registrations list --all --json | jq '.agent_registrations | length'
```

#### API

- [`GET /v0/agent-registrations`](https://machinemail.dev/docs/reference/api/agent-registrations#list-agent-registrations)