using-mogplex-cli

Frontmatter

name: using-mogplex-cli
description: Umbrella skill for guiding a user through the Mogplex CLI cockpit when no Mogplex MCP server is available. Use when the user asks how to start a run, attach to a run, switch models, manage approvals, or configure permissions in the Mogplex CLI. Also triggers on mentions of "mogplex", "AGENTS.md", or "~/.mogplex/".

Body

The Mogplex CLI ships two surfaces in one binary: an interactive cockpit (the TUI) and a headless subcommand surface (mogplex run, mogplex runs events, etc.) for scripts and CI. Agents cannot drive the TUI itself, but they can shell out to the headless commands. Use this skill to advise the user on which to use, what to type in the composer when they're in the cockpit, and what to put in repo-local config files.

When to use this skill

• The user references their Mogplex account, runs, agents, MCP, memory, approvals, or cost.
• The user asks how to do something in the Mogplex cockpit.
• The user wants to author AGENTS.md or per-project permissions.json.

Preflight

Confirm the CLI is installed before recommending it:

command -v mogplex >/dev/null 2>&1 || { echo "mogplex CLI not installed" >&2; exit 1; }

The exit 1 matters: skill-aware hosts gate on the exit code, so a missing binary must fail the preflight rather than silently passing. If it's missing, point the user at Installation.

You cannot check auth state from outside the cockpit — there is no mogplex login status subcommand. Tell the user that the cockpit will surface the login screen on first launch if no credential is stored.

Core guidance map

For the full slash list see Commands.

Decision flow

user wants Mogplex action
        │
        ▼
is the cockpit already open in the user's terminal?
        │
        no  ──► tell them to run `mogplex` (or `mogplex --attach <runId>`)
        yes
        │
        ▼
is it a slash command? ── yes ──► tell user to type "/<command>" in the composer
        │
        no
        ▼
is it a config / file change?
        │
        yes ──► help them author the file (AGENTS.md, permissions.json)
        no  ──► describe the workflow in the cockpit (panels, drawers)

What you cannot do

• Drive the TUI from a script. The cockpit is interactive-only. (For headless work, use mogplex run / mogplex runs events --follow — see Automation.)
• Read auth state from outside the cockpit. There is no login status subcommand; only the cockpit knows.
• Mutate ~/.mogplex/auth.json directly. Tell the user to use /login or /logout in the cockpit.
• Run a slash command headlessly. Slash commands only execute inside the running cockpit — the equivalent for scripts is the mogplex <subcommand> surface.

What you can do

• Author AGENTS.md at the repo root with stable repo guidance (build commands, conventions, layout).
• Author ~/.mogplex/projects/<repo-slug>/permissions.json with allow / deny / ask rules — see Permissions for the schema.
• Recommend env-var escape hatches (MOGPLEX_TRANSPORT, MOGPLEX_ATTACH_RUN_ID) only when they fit CI, attach, or development workflows — see Configuration and Flags.

Safety

• Confirm with the user before authoring or modifying any file under ~/.mogplex/ — those affect every Mogplex run on the machine.
• Never write a key into a shell rc file on the user's behalf.
• Recommend /permissions approval (the default) over /permissions auto unless the user explicitly opts into unattended runs.

See also

• mogplex-slash — recommending slash commands
• mogplex-auth — guiding the login flow
• Slash Commands guide