# mogplex-auth (/cli/skills/mogplex-auth)



<Callout>
  This page mirrors the canonical `SKILL.md` at [`skills/mogplex-auth/SKILL.md`](https://github.com/webrenew/mogplex-docs/blob/main/skills/mogplex-auth/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths).
</Callout>

## Frontmatter [#frontmatter]

```yaml
name: mogplex-auth
description: Guides the user through the Mogplex CLI's in-app login flow, credential precedence, and troubleshooting. Use when the user asks to sign in, switch accounts, debug env-var overrides, or when a Mogplex command fails with an auth error.
```

## Body [#body]

The Mogplex CLI authenticates **in-app**. There is no `mogplex login status` subcommand; the cockpit's login screen is the only flow. Use this skill to advise the user — you cannot inspect or change credentials from outside the cockpit.

## Resolution order [#resolution-order]

The cockpit picks credentials in a fixed order:

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

3. **No credentials** → the cockpit's in-app login screen appears.

Env vars beat stored creds. Always.

## Establish auth [#establish-auth]

### Preferred: account-backed browser login [#preferred-account-backed-browser-login]

Tell the user to launch the cockpit and pick **Sign in with Mogplex** on the login screen, or type `/login` from the composer in an open cockpit.

```bash
mogplex
# pick "Sign in with Mogplex" on the login screen
```

A browser flow opens; the cockpit listens on a local callback and stores the token in `~/.mogplex/auth.json`. The user does the click-through; you do not drive the browser.

Account-backed login unlocks synced model catalog, remote MCP server
definitions, and plan-backed hosted model access.

### Compatibility: provider env var [#compatibility-provider-env-var]

Provider env vars are compatibility and development escape hatches. They are
not the normal customer setup path for billed Mogplex accounts.

Do not write keys into shell rc files on the user's behalf. If a user is
explicitly working in a development or compatibility flow, describe the env-var
override and let them set it themselves.

## Sanity-check env vars (advisory) [#sanity-check-env-vars-advisory]

You can sanity-check which env vars are set without printing values:

```bash
env | grep -E '^(MOGPLEX|ANTHROPIC|OPENAI|GOOGLE_GENERATIVE_AI|GROQ|MISTRAL|DEEPSEEK|XAI|COHERE|VERCEL)_' | sed 's/=.*/=<redacted>/'
```

Never echo a raw key.

## Troubleshooting [#troubleshooting]

| Symptom                                                  | What to recommend                                                                                                                                                                                                     |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Login screen appears at every launch                     | No credential stored and no env var set. Pick a path on the login screen.                                                                                                                                             |
| Login succeeds but prompts fail with "no model access"   | Account-backed login is active but the hosted account lacks model access. Direct the user to [Available Models](https://www.mogplex.com/web/models) and [Plans & Billing](https://www.mogplex.com/plans-and-billing). |
| Cockpit behaves differently than expected after `/login` | An env var is overriding the stored credential. Have the user `unset` it and relaunch.                                                                                                                                |
| User wants to switch accounts                            | Type `/logout` in the composer, then `/login` (or relaunch).                                                                                                                                                          |

## Sign out [#sign-out]

```text
/logout    # type in the composer
```

Or, before attaching to a run:

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

Three things to remember:

* **Env vars still win** on the next session.
* **Restart for certainty.** The current process may still hold the old adapter.
* **Logout clears hosted state.** Synced model catalog and remote MCP definitions vanish locally.

Always confirm with the user before suggesting `/logout`.

## Hard rules [#hard-rules]

* Never read or modify `~/.mogplex/auth.json` directly.
* Never echo a raw key, even from env. Redact.
* Never write a key into a shell config file without explicit user consent.
* Never advise the user to put a key into a JSON config for another agent host when the in-app login would give them an account-backed token instead.

## See also [#see-also]

* [using-mogplex-cli](/cli/skills/using-mogplex-cli)
* [Authentication guide](/cli/guides/authentication)
* [Configuration and Flags](/cli/guides/configuration-and-flags)