{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/cli-overview/cli-authentication","markdown_url":"https://test.abhinandan.one/cli-overview/cli-authentication.md","article":{"id":"073bb106-26ff-465b-a527-1bb19068bb72","article_slug":"cli-authentication","parent_article_slug":"cli-overview","parent_article_title":"What is the Primitive CLI?","kind":"guide","published_at":"2026-08-11T18:54:51.675444+00:00","keywords":["primitive signin","primitive login","primitive signup","primitive logout --force","primitive whoami","PRIMITIVE_API_KEY"],"meta_description":"Run primitive signin (or login) to authenticate the CLI, then use whoami to verify and logout --force to clear stuck credential locks.","og_image_url":null,"source_file_paths":[],"recording_id":null,"replayable":false,"task_name":"Authentication: login, signup, logout, whoami","category":"CLI","summary":null,"description":"Authenticate the primitive CLI with browser-assisted or email-code login, create a new account from the terminal, and diagnose or clear stuck credential state.","content_kind":"repo_page","content_markdown":"Use `primitive signin` (or the alias `primitive login`) to authenticate the CLI once, either through browser approval or an emailed one-time code. Reach for this page any time you're setting up the CLI on a new machine, switching accounts, or recovering from an interrupted auth command.\n\nThe CLI stores credentials locally after a successful sign-in, so every other command (`primitive send`, `primitive functions deploy`, `primitive payments charge`, and so on) authenticates automatically without you passing a key. If you'd rather skip stored credentials entirely, export `PRIMITIVE_API_KEY` and every command picks it up directly (see the `--api-key` flag documented on individual commands).\n\n## Sign in with an existing account\n\n<Steps>\n\n<Step title=\"Run signin with no arguments\">\n\n```bash\nprimitive signin\n```\n\nWith no email argument, `signin` uses browser approval: you approve the CLI login request in the browser, and the CLI polls until approval completes.\n\n</Step>\n\n<Step title=\"Approve in the browser\">\n\nApprove the CLI login request in the browser. The CLI is polling in the background and exits once approval completes.\n\n</Step>\n\n<Step title=\"Confirm the session\">\n\n```bash\nprimitive whoami\n```\n\nA successful `whoami` confirms the CLI has stored working credentials. If it fails, sign in again.\n\n</Step>\n\n</Steps>\n\n<Tip>\n\n`primitive signin browser` and `primitive login browser` are the explicit forms of the same browser-approval flow, useful in scripts where you want to be unambiguous about which auth path runs.\n\n</Tip>\n\n### Email-code sign-in instead of browser approval\n\nIf browser approval isn't available (headless server, restricted network), pass the email address and confirm the emailed code:\n\n```bash\nprimitive signin <email> --signup-code <code> --accept-terms\nprimitive signin confirm <email> <code>\n```\n\n`primitive login <email>` and `primitive otp <email>` support the same email-code flow, each with matching `confirm` and `resend` subcommands, for CLIs or scripts that expect those specific verbs.\n\n## Create a new account from the terminal\n\nUse `primitive signup` when you don't have a Primitive account yet:\n\n<Steps>\n\n<Step title=\"Start signup\">\n\n```bash\nprimitive signup <email>\n```\n\nPrimitive emails a verification code to the address you provided.\n\n</Step>\n\n<Step title=\"Confirm the code\">\n\n```bash\nprimitive signup confirm <email> <code>\n```\n\nThis creates the account and completes sign-in in one step.\n\n</Step>\n\n</Steps>\n\nFor non-interactive scripts (CI provisioning, automated agent setup), pass `--accept-terms` up front, and `--signup-code <code>` if you were issued one:\n\n```bash\nprimitive signup <email> --accept-terms --signup-code <code>\nprimitive signup confirm <email> <code>\n```\n\n<Note>\n\nCreating a zero-touch **agent account** (no API key, no human sign-up flow) is a different mechanism from CLI signup, see [Agent Account Upgrade from the CLI](cli-agent-upgrade) for that flow and how to upgrade an agent account to a full developer account.\n\n</Note>\n\n## Check who's authenticated\n\n`primitive whoami` reports the account the CLI is currently authenticated as.\n\n```bash\nprimitive whoami\n```\n\nRun this after any sign-in to confirm which account and org the CLI is currently using, before running a command that sends mail, deploys a function, or moves money through `primitive payments`.\n\n## Recover from stuck credential state\n\nRun `primitive logout --force` to clear local credentials, pending email-code auth state, and stale credential locks.\n\n<Warning>\n\n`primitive logout --force` removes local CLI credentials, pending email-code auth state, and stale credential locks. It does not contact Primitive's servers, so it can't revoke a session server-side; it only clears what's stored on your machine.\n\n</Warning>\n\nIf an interrupted auth command (killed mid-flow, network drop during browser polling) leaves the CLI reporting that \"another credential operation is already in progress,\" recover with:\n\n```bash\nprimitive logout --force\n```\n\nThen sign in again with `primitive signin`. This is the standard recovery command for that specific error message, reach for it before trying to debug the lock file by hand.\n\n## Diagnose auth issues\n\nThe `primitive config` and `primitive doctor` commands help when an authenticated command fails in a way `whoami` doesn't explain.\n\n- `primitive config` inspects the CLI's resolved configuration.\n- `primitive doctor` runs the CLI's built-in diagnostics.\n\nRun either before filing a bug report; they surface the most common causes of \"commands suddenly stopped authenticating.\"\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"What is the Primitive CLI?\" href=\"cli-overview\">\n\nSee the full command surface and how the CLI relates to the Node SDK and api-core.\n\n</Card>\n\n<Card title=\"Agent Account Upgrade from the CLI\" href=\"cli-agent-upgrade\">\n\nUpgrade a zero-touch agent account to a full developer account with primitive agent-upgrade.\n\n</Card>\n\n<Card title=\"Sending, Replying, and Searching Email from the CLI\" href=\"cli-email-commands\">\n\nUse your authenticated session to send, reply, and search mail from the terminal.\n\n</Card>\n\n<Card title=\"Direct API Access and Generic Commands\" href=\"cli-generic-api-access\">\n\nCall any generated operation directly once you're authenticated.\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":null,"raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Authentication%3A+login%2C+signup%2C+logout%2C+whoami&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fcli-authentication","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}