# Mogplex Auth

> 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, store a provider key, or when a Mogplex command fails with an auth error.

- Skill: `webrenew/mogplex-auth` (Agent Skill)
- Install (CLI): `npx skillmds@latest add webrenew/mogplex-auth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/webrenew/mogplex-auth/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: webrenew (https://skillmd.com/u/webrenew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/webrenew/mogplex-auth

---


# Mogplex auth

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

The cockpit picks credentials in a fixed order:

1. **Provider env var in the current shell.** If set, it wins — no matter what is stored on disk.

   | Provider | Env var |
   | --- | --- |
   | Mogplex | `MOGPLEX_API_KEY` |
   | Anthropic | `ANTHROPIC_API_KEY` |
   | OpenAI | `OPENAI_API_KEY` |
   | Google | `GOOGLE_GENERATIVE_AI_API_KEY` |
   | Groq | `GROQ_API_KEY` |
   | Mistral | `MISTRAL_API_KEY` |
   | DeepSeek | `DEEPSEEK_API_KEY` |
   | xAI | `XAI_API_KEY` |
   | Cohere | `COHERE_API_KEY` |
   | Vercel | `VERCEL_API_TOKEN` |

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

### 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 hosted model access.

### Alternative: store a provider key in-app

In the login screen (or via `/login` in the composer), the user can pick **Use a provider API key** and paste a key. Stored in `~/.mogplex/auth.json` with mode `0600`.

Supported providers: Anthropic, OpenAI, Google, Groq, Mistral, DeepSeek, xAI, Cohere, Vercel AI Gateway.

### Alternative: provider env var

For CI or ephemeral shells:

```bash
export OPENAI_API_KEY=sk-...
mogplex
```

Do not write keys into shell rc files on the user's behalf. Suggest it; let them do it.

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

| 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 https://mogplex.com/web/settings to add a provider key. |
| 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

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

- 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

- [using-mogplex-cli](../using-mogplex-cli/SKILL.md)
- [Authentication guide](https://mogplex.com/cli/guides/authentication)
- [Configuration and Flags](https://mogplex.com/cli/guides/configuration-and-flags)