mogplex-auth

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:

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.

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:

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

• using-mogplex-cli
• Authentication guide
• Configuration and Flags