---
title: "Agent Account Upgrade from the CLI"
canonical: "https://test.abhinandan.one/cli-agent-upgrade"
markdown_url: "https://test.abhinandan.one/cli-agent-upgrade.md"
publisher: "Primitive SDKs"
kind: "guide"
content_type: "reference"
category: "CLI"
description: "Run primitive agent-upgrade to confirm an email and turn a zero-touch agent account into a full developer account from the terminal."
keywords: ["primitive agent-upgrade", "agent account upgrade CLI", "email-claim flow", "PRIMITIVE_API_KEY agent", "agent claim verify", "developer plan upgrade"]
last_modified: "2026-08-11T18:55:03.863156+00:00"
published_at: "2026-08-11T18:55:03.719915+00:00"
source_files:
  - "cli-node/src/oclif/commands/agent-upgrade.ts"
sections:
  - {anchor: "prerequisites", title: "Prerequisites"}
  - {anchor: "upgrade-an-agent-account", title: "Upgrade an agent account"}
  - {anchor: "step-set-the-agents-api-key", title: "Set the agent's API key"}
  - {anchor: "step-run-the-upgrade-command", title: "Run the upgrade command"}
  - {anchor: "step-confirm-the-verification-code", title: "Confirm the verification code"}
  - {anchor: "step-verify-the-result", title: "Verify the result"}
  - {anchor: "flags", title: "Flags"}
  - {anchor: "troubleshooting", title: "Troubleshooting"}
  - {anchor: "next-steps", title: "Next steps"}
---

> Documentation index: https://test.abhinandan.one/llms.txt

# Agent Account Upgrade from the CLI

Upgrade a zero-touch agent account to a full developer account from the terminal with primitive agent-upgrade, an interactive wrapper around the SDKs' email-claim flow.

`primitive agent-upgrade` confirms an email address for an [agent account](https://test.abhinandan.one/node-sdk-agent-accounts.md) and upgrades it to the `developer` plan, all from one interactive command. Use it when a zero-touch agent account (created without an API key) needs to lift its reply-only send cap and become a normal, fully-authenticated developer account.

The command is a terminal wrapper around the same [email-claim flow](https://test.abhinandan.one/node-sdk-agent-accounts.md) the SDKs expose as `claimStart`/`claimVerify` (Node), and the equivalent Python/Go agent operations: it starts the claim, prompts for the code that lands in your inbox, and verifies it in one run.

> **Note:** This page covers the CLI command only. For the underlying API shape, request/response fields, and the concept of an agent account itself, see [Agent Accounts](https://test.abhinandan.one/node-sdk-agent-accounts.md).

## Prerequisites

- An existing agent account and its API key (the one returned when the account was created with `createAccount`/`create_account`/`CreateAccount`, or via the CLI's zero-touch signup path).
- Access to the inbox for the email address you want to confirm, the verification code is sent there.

## Upgrade an agent account

### 1. Set the agent's API key

Export the agent's API key so the command authenticates as that account. The org that receives the upgrade is resolved from this key.

```bash
export PRIMITIVE_API_KEY=prim_test
```

Pass `--api-key` explicitly instead when you need to override the environment for a single run; the CLI otherwise falls back to saved credentials.

### 2. Run the upgrade command

```bash
primitive agent-upgrade --email you@example.com
```

Omit `--email` and the command prompts for it interactively:

```bash
primitive agent-upgrade
Email to confirm:
```

### 3. Confirm the verification code

The command starts the claim and writes a status line to stderr:

```text
Verification code sent to you@example.com.
```

It then prompts for the code:

```text
Verification code: 482913
```

Pass `--code` up front to skip the prompt in scripted or CI contexts:

```bash
primitive agent-upgrade --email you@example.com --code 482913
```

### 4. Verify the result

On success the command prints the claim verification result as JSON to stdout, and a plain-language confirmation to stderr. The result includes the account's new `plan`:

```json
{
  "plan": "developer"
}
```

```text
Upgraded to developer. Your API key and managed inbox carry over; the send cap is lifted.
```

The account's API key and managed inbox are unchanged by the upgrade, only the plan and its send limits change.

## Flags

`primitive agent-upgrade` accepts four flags; `--email` and `--code` are prompted for interactively when omitted.

| Flag | Description |
|---|---|
| `--email` | Email to confirm. Prompted if omitted. |
| `--code` | Verification code from the email. Prompted if omitted. |
| `--api-key` | Agent API key. Defaults to `PRIMITIVE_API_KEY` or saved credentials. |
| `--api-base-url` | Override the API base URL. |

> **Tip:** Prompts are written to stderr, so stdout stays clean for the final JSON payload, pipe it straight into `jq` even when running interactively.

> **Warning:** The command authenticates with the *agent's own* API key, not your operator/developer credentials. Running it against the wrong key upgrades the wrong org.

## Troubleshooting

If the claim-start or claim-verify call fails, the command prints the API error payload and exits non-zero. Common causes:

- **Verification code expired or wrong**: re-run the command without `--code` to start a fresh claim and get a new code emailed.
- **Unauthorized**: the `--api-key` (or `PRIMITIVE_API_KEY`) doesn't belong to a valid agent account. Re-check the key you saved when the agent account was created.