| 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, store a provider key, or when a Mogplex command fails with an auth error. |
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:
-
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 |
-
Stored credentials in ~/.mogplex/auth.json (mode 0600).
-
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.
mogplex
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:
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:
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://www.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
/logout # type in the composer
Or, before attaching to a run:
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
