Verified · 8/11/2026

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 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 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.

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.
```
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.

Run the upgrade command#

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

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

primitive agent-upgrade
Email to confirm:

3
Confirm the verification code#
The command starts the claim and writes a status line to stderr:
```
Verification code sent to you@example.com.
```
It then prompts for the code:
```
Verification code: 482913
```
Pass --code up front to skip the prompt in scripted or CI contexts:
```
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:
```
{
  "plan": "developer"
}
```
```
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.