# Authentication (/cli/guides/authentication)





The CLI ships to end users — auth is in-app. You do **not** need to set environment variables for normal use. Env vars exist as escape hatches for CI and ephemeral shells.

## Resolution order [#resolution-order]

When the CLI starts up, it resolves credentials in this order. The normal
customer path is account-backed login; provider env vars are compatibility and
development overrides.

1. **Auth env var in the current shell.** `MOGPLEX_API_KEY` and legacy local
   provider env vars can override what is stored on disk.

2. **Stored credentials** in `~/.mogplex/auth.json` (mode `0600`). If you previously used Codex and have `CODEX_HOME` set, the CLI still honors it but it is deprecated — set `MOGPLEX_HOME` instead. See [Configuration and Flags → Storage](/cli/guides/configuration-and-flags#storage).

3. **No credentials** → the in-app **login screen** appears (or, in non-interactive contexts, a clear failure).

The practical rule: shell env vars outrank everything else.

## In-app login [#in-app-login]

On first run, use the Mogplex account path:

* **Sign in with Mogplex** — opens a browser flow for account-backed login. The CLI listens on a local callback and stores a Mogplex token. Recommended.

Account-backed login is the product path for normal use.

You can re-open the login screen later from the composer:

```text
/login
```

## What account-backed login means [#what-account-backed-login-means]

When you sign in with Mogplex, the CLI stores a `mogplex` credential in
`~/.mogplex/auth.json` and can reuse hosted state:

* synced model catalog
* remote MCP server definitions
* plan-backed model access configured for your Mogplex user

If account login succeeds but prompts fail, the hosted account usually does not
have usable model access yet. Check [Available Models](/web/models) and
[Plans & Billing](/plans-and-billing).

## Provider env vars [#provider-env-vars]

Direct provider environment variables are a compatibility and development
escape hatch, not the product setup path for billed Mogplex accounts. They
still take precedence over the account login path when they are present, so
unset them before debugging billed account behavior.

If both a stored credential and an env var exist for the same provider, the env
var wins.

## `/logout` [#logout]

```text
/logout
```

Clears the Mogplex token from `~/.mogplex/auth.json`. Three things to remember:

* **Env vars still win.** If the matching env var is set, the next session will still authenticate through it.
* **Restart for certainty.** The current process may still hold the old adapter. Quit (`/quit`) and relaunch if you need an immediate clean slate.
* **Logout clears hosted state.** Synced model catalog and remote MCP definitions vanish locally.

You can also force logout-then-attach in one shot:

```bash
mogplex --attach run_abc123 --logout
```

<Callout>
  The CLI never reads `~/.mogplex/auth.json` to display secret material in
  logs. Session logs at `~/.mogplex/logs/<session-id>.jsonl` redact API keys,
  tokens, and the raw contents of `auth.json`.
</Callout>

## Common outcomes [#common-outcomes]

* The login screen appears at startup → no Mogplex credential is available; sign in.
* Login succeeds but prompts fail → account login is active but the hosted account lacks model access. Check [Available Models](/web/models) and [Plans & Billing](/plans-and-billing).
* The CLI behaves differently than the in-app login implies → check env vars first; they outrank stored auth.

## See also [#see-also]

* [Configuration and Flags](/cli/guides/configuration-and-flags) — env-var escape hatches.
* [Concepts → Attach](/cli/concepts/attach) — `--logout` plus `--attach`.
* [Skills → mogplex-auth](/cli/skills/mogplex-auth) — the agent skill that gates other Mogplex actions on auth.