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

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.

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

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:

/login

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 and Plans & Billing.

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

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:

mogplex --attach run_abc123 --logout

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 and Plans & Billing.
• The CLI behaves differently than the in-app login implies → check env vars first; they outrank stored auth.

See also

• Configuration and Flags — env-var escape hatches.
• Concepts → Attach — --logout plus --attach.
• Skills → mogplex-auth — the agent skill that gates other Mogplex actions on auth.