---
title: "Authentication: login, signup, logout, whoami"
canonical: "https://test.abhinandan.one/cli-overview/cli-authentication"
markdown_url: "https://test.abhinandan.one/cli-overview/cli-authentication.md"
publisher: "Primitive SDKs"
kind: "guide"
content_type: "reference"
category: "CLI"
parent: "cli-overview"
description: "Run primitive signin (or login) to authenticate the CLI, then use whoami to verify and logout --force to clear stuck credential locks."
keywords: ["primitive signin", "primitive login", "primitive signup", "primitive logout --force", "primitive whoami", "PRIMITIVE_API_KEY"]
last_modified: "2026-08-21T18:22:43.359885+00:00"
published_at: "2026-08-11T18:54:51.675444+00:00"
sections:
  - {anchor: "sign-in-with-an-existing-account", title: "Sign in with an existing account"}
  - {anchor: "step-run-signin-with-no-arguments", title: "Run signin with no arguments"}
  - {anchor: "step-approve-in-the-browser", title: "Approve in the browser"}
  - {anchor: "step-confirm-the-session", title: "Confirm the session"}
  - {anchor: "email-code-sign-in-instead-of-browser-approval", title: "Email-code sign-in instead of browser approval"}
  - {anchor: "create-a-new-account-from-the-terminal", title: "Create a new account from the terminal"}
  - {anchor: "step-start-signup", title: "Start signup"}
  - {anchor: "step-confirm-the-code", title: "Confirm the code"}
  - {anchor: "check-whos-authenticated", title: "Check who's authenticated"}
  - {anchor: "recover-from-stuck-credential-state", title: "Recover from stuck credential state"}
  - {anchor: "diagnose-auth-issues", title: "Diagnose auth issues"}
  - {anchor: "next-steps", title: "Next steps"}
---

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

# Authentication: login, signup, logout, whoami

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.

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. Run signin with no arguments

```bash
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. 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. Confirm the session

```bash
primitive whoami
```

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

> **Tip:** `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.

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

```bash
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. Start signup

```bash
primitive signup <email>
```

Primitive emails a verification code to the address you provided.

### 2. Confirm the code

```bash
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:

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

> **Note:** Creating 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](https://test.abhinandan.one/cli-agent-upgrade.md) for that flow and how to upgrade an agent account to a full developer account.

## Check who's authenticated

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

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

> **Warning:** `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.

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:

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