Mixpanel authentication

Manage Mixpanel credentials through auth_manager.py. Each subcommand prints
exactly one JSON object to stdout. Parse it and present the result in plain
words.

Run each command below exactly as written, with the full interpreter path. The
pre-approved pattern in allowed-tools matches only that text.

The commands use the plugin environment that the setup skill creates. If the
interpreter path does not exist ("No such file or directory"), tell the user
to run /mixpanel-headless:setup first.

In this skill, mp means ${CLAUDE_PLUGIN_DATA}/venv/bin/mp. When you tell
the user to run an mp command, write that full path, because mp is often
not on the user's PATH. This also applies to the commands in next hints.

Schema: every response has schema_version: 1 and a state of ok,
needs_account, needs_project, or error. Errors are also JSON on stdout
with exit code 0, so you can parse the output without a try/except.

Security rules (firm)

• Do not ask for secrets (passwords, API secrets) in the conversation. They stay visible in the history.
• Do not pass secrets as command-line arguments. They are visible in the process list.
• For a service account, tell the user to run ! ${CLAUDE_PLUGIN_DATA}/venv/bin/mp account add <name> --type service_account --username <username> --project <project_id> --region <region> themselves. The command prompts for the secret with hidden input when it has a terminal.
• If that command fails with "Set MP_SECRET or use --secret-stdin", the ! session has no terminal for the prompt. Tell the user to run the same command in their own terminal, outside Claude Code. Another option: export MP_SECRET in their shell first. Still do not ask for the secret in the chat.

Routing

Parse $ARGUMENTS and route to the matching subcommand. With no arguments,
run session.

"login"

For first-time setup, the one-shot path is mp login. It picks the auth flow
from the environment, derives the account name from /me, and pins a default
project. Tell the user to run:

! ${CLAUDE_PLUGIN_DATA}/venv/bin/mp login

The region behavior depends on the auth type:

• service_account and oauth_token paths probe us → eu → in and use the first region that answers.
• The oauth_browser path (the default for a bare mp login) uses us. EU and India users must pass --region eu or --region in.

Optional flags:

• --name NAME — override the derived account name
• --region us|eu|in — set the region explicitly (required for EU and India browser users)
• --project ID — skip the project picker
• --service-account — force the service-account path (needs MP_USERNAME and MP_SECRET in the environment)
• --token-env VAR — force the static-bearer path (reads the token from $VAR)
• --no-browser — print the authorization URL instead of opening a browser

If mp login fails with "Multiple projects accessible to this account", the
command had no terminal for its project picker. Show the listed projects, ask
which one to use, and tell the user to run it again with --project <id>.

After the user confirms, run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py session to get account.name. Then run
${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account test <account.name>.

No arguments or "session"

Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py session. Switch on state:

• ok — show one line: "Active: account.name → project project.id". Add workspace workspace.id if it is not null. Mention /mixpanel-headless:auth account list and /mixpanel-headless:auth project list for a switch.
• needs_account — no account is configured. Show next[0].command (the one-shot mp login) as the recommended step. List the alternatives: next[1] (explicit account add) and next[2] (the MP_OAUTH_TOKEN environment variables, best for CI and agents).
• needs_project — an account exists but no project is pinned. Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py project list, show the table, and ask which project to use. Then run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py project use <id>.
• error — show error.message. If error.actionable is true, the message names the next command.

"account list"

Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account list. Show items as a table: name, type, region,
is_active. Mark the active account with a star. If referenced_by_targets
is not empty for an account, say so ("team is referenced by targets: ecom").

If items is empty, show the next onboarding hints (as for needs_account).

"account add"

This is a guided wizard. Do not run any script that handles secrets.

1. Ask for the account name (for example "personal", "team", "ci").
2. Ask for the type: oauth_browser (recommended for laptops), service_account (long-lived), or oauth_token (CI and agents).
3. Ask for the region: us, eu, or in (default us).
4. For service_account, ask for the username and the numeric project ID. For oauth_token, ask for the project ID and the name of the environment variable that holds the bearer token. For oauth_browser, the project ID is optional, because mp account login fills it in after the browser flow.
5. Tell the user to run the matching command. For a service account (if it fails with "Set MP_SECRET or use --secret-stdin", follow the security rules above):

Now run this command. It prompts for your service account secret with hidden input:

! ${CLAUDE_PLUGIN_DATA}/venv/bin/mp account add <NAME> --type service_account --username <USERNAME> --project <PROJECT_ID> --region <REGION>

For an OAuth token, the named environment variable must hold the token in the
shell where the command runs:

! ${CLAUDE_PLUGIN_DATA}/venv/bin/mp account add <NAME> --type oauth_token --token-env <VAR> --project <PROJECT_ID> --region <REGION>

For OAuth browser, prefer the one-shot mp login (see "login" above):

! ${CLAUDE_PLUGIN_DATA}/venv/bin/mp login --name <NAME> --region <REGION>

For full control over registration before the browser flow, the two-step path
still works:

! ${CLAUDE_PLUGIN_DATA}/venv/bin/mp account add <NAME> --type oauth_browser --region <REGION>
! ${CLAUDE_PLUGIN_DATA}/venv/bin/mp account login <NAME>      # opens a browser for the PKCE flow

Replace the placeholders with the values you collected. The ! prefix runs the
command in the user's terminal session.

6. After the user confirms, run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account test <NAME>.
7. Report success or failure from the result.ok field.

"account use" or "account use "

If a name is given, run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account use <name>.

If no name is given:

1. Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account list to show the accounts.
2. Ask which one to use.
3. Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account use <name> with the chosen name.

On state: ok, show one line: "Switched to active.account (project active.project)".
On state: error, show error.message.

"account login "

The name is required. If it is missing, run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account list and ask.
Then run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account login <name>.

Tell the user that a browser window opens for Mixpanel authentication. Wait for
the JSON response.

On state: ok: "OAuth login successful. logged_in_as.user.email, token
valid until logged_in_as.expires_at."
On state: error: show error.message and suggest a retry.

"account test" or "account test "

The script needs a name. If none is given, run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py session and use
account.name. Then run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py account test <name>.

The subcommand does not raise, so state is always ok. Read result.ok:

• result.ok: true → "Connected as result.user.email · result.accessible_project_count accessible projects."
• result.ok: false → "Test failed: result.error."

"project list"

Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py project list. Show items as a table: organization, project name,
project ID. Mark the active project (is_active: true) with a star. Suggest
/mixpanel-headless:auth project use <id> for a switch.

"project use "

If no ID is given, run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py project list first and ask which one to use.

Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py project use <PROJECT_ID>.

On state: ok: "Switched to project active.project."
On state: error: show error.message.

"workspace list"

Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py workspace list. Show items as a table: workspace ID, name,
is_default. Mark the active workspace with a star. Name the parent project
from project.name (project.id).

"workspace use "

Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py workspace use <WORKSPACE_ID>.

On state: ok: "Pinned workspace active.workspace."
On state: error: show error.message.

"target list"

Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py target list. A target is a saved combination of an account, a project,
and an optional workspace. Show a table: name, account, project,
workspace.

"target add"

This is a guided wizard. Collect the target name, the account name, the
project ID, and an optional workspace ID. Then run:

${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py target add <NAME> --account <ACCT> --project <PROJ> [--workspace <WS>]

"target use "

Run ${CLAUDE_PLUGIN_DATA}/venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/auth/scripts/auth_manager.py target use <name>. It applies all three axes (account,
project, workspace) to [active] in one atomic config write.

Bearer-token environment variables (MP_OAUTH_TOKEN)

For non-interactive contexts (CI, agents, short-lived environments), the
browser flow does not work. Set these instead:

export MP_OAUTH_TOKEN=<bearer-token>
export MP_PROJECT_ID=<project-id>
export MP_REGION=<us|eu|in>

The library sends an Authorization: Bearer <token> header to every Mixpanel
endpoint. When the full service-account set (MP_USERNAME + MP_SECRET +
MP_PROJECT_ID + MP_REGION) is also present, the library ignores
MP_OAUTH_TOKEN. To use the token, unset MP_USERNAME and MP_SECRET.

Presentation

• Show status in one or two lines, not a wall of JSON.
• Use tables for lists of accounts, projects, workspaces, and targets.
• When something is missing, suggest the next action.
• On an error, show error.message verbatim, because it names the fix.