{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/cli-agent-upgrade","markdown_url":"https://test.abhinandan.one/cli-agent-upgrade.md","article":{"id":"bbf1f0fb-a2b7-449f-bfc4-c3f055398e67","article_slug":"cli-agent-upgrade","parent_article_slug":null,"parent_article_title":null,"kind":"guide","published_at":"2026-08-11T18:55:03.719915+00:00","keywords":["primitive agent-upgrade","agent account upgrade CLI","email-claim flow","PRIMITIVE_API_KEY agent","agent claim verify","developer plan upgrade"],"meta_description":"Run primitive agent-upgrade to confirm an email and turn a zero-touch agent account into a full developer account from the terminal.","og_image_url":null,"source_file_paths":["cli-node/src/oclif/commands/agent-upgrade.ts"],"recording_id":null,"replayable":false,"task_name":"Agent Account Upgrade from the CLI","category":"CLI","summary":null,"description":"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.","content_kind":"repo_page","content_markdown":"`primitive agent-upgrade` confirms an email address for an [agent account](node-sdk-agent-accounts) 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.\n\nThe command is a terminal wrapper around the same [email-claim flow](node-sdk-agent-accounts) 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.\n\n<Note>\n\nThis 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](node-sdk-agent-accounts).\n\n</Note>\n\n## Prerequisites\n\n- 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).\n- Access to the inbox for the email address you want to confirm, the verification code is sent there.\n\n## Upgrade an agent account\n\n<Steps>\n\n<Step title=\"Set the agent's API key\">\n\nExport the agent's API key so the command authenticates as that account. The org that receives the upgrade is resolved from this key.\n\n```bash\nexport PRIMITIVE_API_KEY=prim_test\n```\n\nPass `--api-key` explicitly instead when you need to override the environment for a single run; the CLI otherwise falls back to saved credentials.\n\n</Step>\n\n<Step title=\"Run the upgrade command\">\n\n```bash\nprimitive agent-upgrade --email you@example.com\n```\n\nOmit `--email` and the command prompts for it interactively:\n\n```bash\nprimitive agent-upgrade\nEmail to confirm:\n```\n\n</Step>\n\n<Step title=\"Confirm the verification code\">\n\nThe command starts the claim and writes a status line to stderr:\n\n```text\nVerification code sent to you@example.com.\n```\n\nIt then prompts for the code:\n\n```text\nVerification code: 482913\n```\n\nPass `--code` up front to skip the prompt in scripted or CI contexts:\n\n```bash\nprimitive agent-upgrade --email you@example.com --code 482913\n```\n\n</Step>\n\n<Step title=\"Verify the result\">\n\nOn 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`:\n\n```json\n{\n  \"plan\": \"developer\"\n}\n```\n\n```text\nUpgraded to developer. Your API key and managed inbox carry over; the send cap is lifted.\n```\n\nThe account's API key and managed inbox are unchanged by the upgrade, only the plan and its send limits change.\n\n</Step>\n\n</Steps>\n\n## Flags\n\n`primitive agent-upgrade` accepts four flags; `--email` and `--code` are prompted for interactively when omitted.\n\n| Flag | Description |\n|---|---|\n| `--email` | Email to confirm. Prompted if omitted. |\n| `--code` | Verification code from the email. Prompted if omitted. |\n| `--api-key` | Agent API key. Defaults to `PRIMITIVE_API_KEY` or saved credentials. |\n| `--api-base-url` | Override the API base URL. |\n\n<Tip>\n\nPrompts are written to stderr, so stdout stays clean for the final JSON payload, pipe it straight into `jq` even when running interactively.\n\n</Tip>\n\n<Warning>\n\nThe command authenticates with the *agent's own* API key, not your operator/developer credentials. Running it against the wrong key upgrades the wrong org.\n\n</Warning>\n\n## Troubleshooting\n\nIf the claim-start or claim-verify call fails, the command prints the API error payload and exits non-zero. Common causes:\n\n- **Verification code expired or wrong**: re-run the command without `--code` to start a fresh claim and get a new code emailed.\n- **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.\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Agent Accounts\" href=\"node-sdk-agent-accounts\">\n\nUnderstand the zero-touch agent account model and the email-claim flow in code.\n\n</Card>\n\n<Card title=\"Authentication: login, signup, logout, whoami\" href=\"cli-authentication\">\n\nManage CLI credentials and diagnose auth issues for developer accounts.\n\n</Card>\n\n<Card title=\"What is the Primitive CLI?\" href=\"cli-overview\">\n\nSee how agent-upgrade fits into the CLI's full command surface.\n\n</Card>\n\n<Card title=\"Inbox Setup and Status\" href=\"cli-inbox\">\n\nCheck the managed inbox that carries over after an agent account upgrade.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/cli-node/src/oclif/commands/agent-upgrade.ts","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Agent+Account+Upgrade+from+the+CLI&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fcli-agent-upgrade","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}