# using-mogplex-cli (/cli/skills/using-mogplex-cli)



<Callout>
  This page mirrors the canonical `SKILL.md` at [`skills/using-mogplex-cli/SKILL.md`](https://github.com/webrenew/mogplex-docs/blob/main/skills/using-mogplex-cli/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths).
</Callout>

## Frontmatter [#frontmatter]

```yaml
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 [#body]

The Mogplex CLI ships two surfaces in one binary: an interactive cockpit (the TUI) and a [headless subcommand surface](/cli/automation) (`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 [#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 [#preflight]

Confirm the CLI is installed before recommending it:

```bash
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](https://www.mogplex.com/cli/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 [#core-guidance-map]

| Intent                              | What to tell the user                                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| Start a run                         | Launch `mogplex`, then type `/run <task>` in the composer.                              |
| Attach to an in-flight run          | `mogplex --attach <runId>` — see [Attach](https://www.mogplex.com/cli/concepts/attach). |
| Switch models                       | Type `/model` in the composer to open the Model Picker drawer.                          |
| Approve / reject pending tool calls | The Approval drawer surfaces them automatically; the user clicks Approve or Reject.     |
| Switch permission modes             | Type `/permissions auto` or `/permissions approval` in the composer.                    |
| Inspect cost                        | Type `/cost` to open the Cost drawer.                                                   |
| Export the run                      | Type `/export` to open the Run Export drawer.                                           |
| Quit                                | Type `/quit`, or double-tap Ctrl+C within 1500ms.                                       |

For the full slash list see [Commands](https://www.mogplex.com/cli/commands).

### Decision flow [#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 [#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](/cli/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 [#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](https://www.mogplex.com/cli/concepts/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](https://www.mogplex.com/cli/guides/configuration-and-flags).

### Safety [#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 [#see-also]

* [mogplex-slash](/cli/skills/mogplex-slash) — recommending slash commands
* [mogplex-auth](/cli/skills/mogplex-auth) — guiding the login flow
* [Slash Commands guide](/cli/guides/slash-commands)