---
title: "agents create"
description: "Issue a new agent credential"
canonical: "https://pgbeam.com/docs/cli/agents/create"
last-updated: "2026-10-29T19:01:20.000Z"
---

# agents create

> Issue a new agent credential

URL: https://pgbeam.com/docs/cli/agents/create

{/* Auto-generated from CLI commands. Do not edit. Run `pnpm generate:cli-docs` to regenerate. */}

Issue a scoped Postgres login and hosted MCP token for an AI agent. The connection string and MCP token are shown once and cannot be retrieved again. Store them securely. A ready-to-paste MCP client config (Claude Code, Claude Desktop, Cursor, VS Code, Cline, or Windsurf) is printed alongside the secrets.

## Usage

```bash
pgbeam agents create [flags]
```

## Options

| Option                     | Description                                                                                              | Required | Default  |
| -------------------------- | -------------------------------------------------------------------------------------------------------- | -------- | -------- |
| `--name <value>`           | Human-readable label for the credential                                                                  | Yes      | -        |
| `--policy <value>`         | Policy profile ID to enforce                                                                             | Yes      | -        |
| `--client <value>`         | MCP client to emit config for: claude (default), claude-desktop, cursor, vscode, cline, windsurf, or all | No       | `claude` |
| `--expires <value>`        | Credential lifetime: a duration like 30d/12h/90m, or an absolute ISO 8601 timestamp. Omit for no expiry. | No       | -        |
| `--principal-type <value>` | Whether the credential represents an autonomous agent (default) or a human operator: agent or human      | No       | -        |

> **Global options**
>
> All [global options](/docs/cli/global-options) (`--token`, `--profile`,
> `--project`, `--org`, `--json`, `--no-color`, `--no-trunc`, `--debug`) are
> also available on this command.

## Examples

```bash
# Create a credential bound to a policy profile
pgbeam agents create --name "Claude Code" --policy pol_xxx

# Create and emit a Cursor MCP config
pgbeam agents create --name agent --policy pol_xxx --client cursor

# Create a credential that expires in 30 days
pgbeam agents create --name agent --policy pol_xxx --expires 30d

# Mint a human-operator credential
pgbeam agents create --name "Data analyst" --policy pol_xxx --principal-type human

# Create and capture secrets as JSON
pgbeam agents create --name ci --policy pol_xxx --json
```

## Output

Prints the connection string, MCP URL, MCP token, and a ready-to-paste MCP client config once. With --json, returns the full secrets object.