mogplex-auth

Walks the user through the Mogplex CLI's in-app login screen, env-var escape hatches, and credential troubleshooting.

This page mirrors the canonical SKILL.md at skills/mogplex-auth/SKILL.md. Copy that file into your agent host (see Skills overview for install paths).

Frontmatter

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.

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:

Auth env var in the current shell. MOGPLEX_API_KEY and legacy local provider env vars can override what is stored on disk.
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

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

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)

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 Available Models and Plans & 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

/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.