Authentication: login, signup, logout, whoami

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.

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

Sign in with an existing account#

1. 1

   Run signin with no arguments#

   primitive signin
   

   With no email argument, signin uses browser approval: you approve the CLI login request in the browser, and the CLI polls until approval completes.

2. 2

   Approve in the browser#

   Approve the CLI login request in the browser. The CLI is polling in the background and exits once approval completes.

3. 3

   Confirm the session#

   primitive whoami
   

   A successful whoami confirms the CLI has stored working credentials. If it fails, sign in again.

Email-code sign-in instead of browser approval#

If browser approval isn't available (headless server, restricted network), pass the email address and confirm the emailed code:

primitive signin <email> --signup-code <code> --accept-terms
primitive signin confirm <email> <code>

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.

Create a new account from the terminal#

Use primitive signup when you don't have a Primitive account yet:

1. 1

   Start signup#

   primitive signup <email>
   

   Primitive emails a verification code to the address you provided.

2. 2

   Confirm the code#

   primitive signup confirm <email> <code>
   

   This creates the account and completes sign-in in one step.

For non-interactive scripts (CI provisioning, automated agent setup), pass --accept-terms up front, and --signup-code <code> if you were issued one:

primitive signup <email> --accept-terms --signup-code <code>
primitive signup confirm <email> <code>

Check who's authenticated#

primitive whoami reports the account the CLI is currently authenticated as.

primitive whoami

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

Recover from stuck credential state#

Run primitive logout --force to clear local credentials, pending email-code auth state, and stale credential locks.

If 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:

primitive logout --force

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

Diagnose auth issues#

The primitive config and primitive doctor commands help when an authenticated command fails in a way whoami doesn't explain.

• primitive config inspects the CLI's resolved configuration.
• primitive doctor runs the CLI's built-in diagnostics.

Run either before filing a bug report; they surface the most common causes of "commands suddenly stopped authenticating."

Next steps#