From 5ba1f7a7c57ddcfbafef25043ec310042662a13c Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 27 Apr 2026 14:48:19 -0400 Subject: [PATCH 1/3] docs(cli): rewrite /cli for the new TUI cockpit; drop legacy exec/slash subcommand surface The standalone `mogplex` CLI (with `exec`, `login`, `slash`, etc. subcommands) is replaced by the new interactive cockpit from the mogplex-tui repo. The /cli URL space is preserved; content is rewritten to document the cockpit: - New: cli/concepts/{architecture,transports,permissions,approvals,attach} - New: cli/reference/{panels,drawers,keybindings,cost-and-usage,export} - Rewrites: cli/index, installation, quickstart, commands/index (slash ref), guides/{index,authentication,configuration-and-flags,slash-commands,project-commands}, skills/{index,using-mogplex-cli,mogplex-slash,mogplex-auth} (now guidance skills) - Deletes: cli/commands/{exec,login,slash,reserved-names}, cli/guides/exec-mode, cli/skills/mogplex-exec (capability gone), scripts/gen-cli-reference.ts + prebuild script (no auto-gen target) - Updates extend/{index,skills} to reference the new guidance-skills framing - Drops `tsx` devDep (only used by removed prebuild script) Co-Authored-By: Claude Opus 4.7 (1M context) --- content/docs/cli/commands/exec.mdx | 58 -- content/docs/cli/commands/index.mdx | 77 +- content/docs/cli/commands/login.mdx | 52 -- content/docs/cli/commands/meta.json | 8 +- content/docs/cli/commands/reserved-names.mdx | 47 -- content/docs/cli/commands/slash.mdx | 50 -- content/docs/cli/concepts/approvals.mdx | 77 ++ content/docs/cli/concepts/architecture.mdx | 50 ++ content/docs/cli/concepts/attach.mdx | 74 ++ content/docs/cli/concepts/index.mdx | 21 + content/docs/cli/concepts/meta.json | 4 + content/docs/cli/concepts/permissions.mdx | 99 +++ content/docs/cli/concepts/transports.mdx | 61 ++ content/docs/cli/guides/authentication.mdx | 143 ++-- .../cli/guides/configuration-and-flags.mdx | 227 ++---- content/docs/cli/guides/exec-mode.mdx | 122 --- content/docs/cli/guides/index.mdx | 38 +- content/docs/cli/guides/meta.json | 2 +- content/docs/cli/guides/project-commands.mdx | 168 +---- content/docs/cli/guides/slash-commands.mdx | 147 ++-- content/docs/cli/index.mdx | 155 ++-- content/docs/cli/installation.mdx | 106 +-- content/docs/cli/meta.json | 2 +- content/docs/cli/quickstart.mdx | 200 ++--- content/docs/cli/reference/cost-and-usage.mdx | 50 ++ content/docs/cli/reference/drawers.mdx | 95 +++ content/docs/cli/reference/export.mdx | 49 ++ content/docs/cli/reference/index.mdx | 16 + content/docs/cli/reference/keybindings.mdx | 79 ++ content/docs/cli/reference/meta.json | 4 + content/docs/cli/reference/panels.mdx | 82 ++ content/docs/cli/skills/index.mdx | 43 +- content/docs/cli/skills/meta.json | 2 +- content/docs/cli/skills/mogplex-auth.mdx | 114 ++- content/docs/cli/skills/mogplex-exec.mdx | 109 --- content/docs/cli/skills/mogplex-slash.mdx | 129 ++-- content/docs/cli/skills/using-mogplex-cli.mdx | 93 +-- content/docs/extend/index.mdx | 10 +- content/docs/extend/skills.mdx | 23 +- content/docs/index.mdx | 47 +- package.json | 2 - pnpm-lock.yaml | 291 ------- scripts/gen-cli-reference.ts | 714 ------------------ skills/README.md | 21 +- skills/mogplex-auth/SKILL.md | 118 ++- skills/mogplex-exec/SKILL.md | 100 --- skills/mogplex-slash/SKILL.md | 129 ++-- skills/using-mogplex-cli/SKILL.md | 89 ++- 48 files changed, 1544 insertions(+), 2853 deletions(-) delete mode 100644 content/docs/cli/commands/exec.mdx delete mode 100644 content/docs/cli/commands/login.mdx delete mode 100644 content/docs/cli/commands/reserved-names.mdx delete mode 100644 content/docs/cli/commands/slash.mdx create mode 100644 content/docs/cli/concepts/approvals.mdx create mode 100644 content/docs/cli/concepts/architecture.mdx create mode 100644 content/docs/cli/concepts/attach.mdx create mode 100644 content/docs/cli/concepts/index.mdx create mode 100644 content/docs/cli/concepts/meta.json create mode 100644 content/docs/cli/concepts/permissions.mdx create mode 100644 content/docs/cli/concepts/transports.mdx delete mode 100644 content/docs/cli/guides/exec-mode.mdx create mode 100644 content/docs/cli/reference/cost-and-usage.mdx create mode 100644 content/docs/cli/reference/drawers.mdx create mode 100644 content/docs/cli/reference/export.mdx create mode 100644 content/docs/cli/reference/index.mdx create mode 100644 content/docs/cli/reference/keybindings.mdx create mode 100644 content/docs/cli/reference/meta.json create mode 100644 content/docs/cli/reference/panels.mdx delete mode 100644 content/docs/cli/skills/mogplex-exec.mdx delete mode 100644 scripts/gen-cli-reference.ts delete mode 100644 skills/mogplex-exec/SKILL.md diff --git a/content/docs/cli/commands/exec.mdx b/content/docs/cli/commands/exec.mdx deleted file mode 100644 index c47374d..0000000 --- a/content/docs/cli/commands/exec.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: exec -description: Non-interactive run. ---- - -{/* Auto-generated by scripts/gen-cli-reference.ts — do not edit by hand. */} - -## Status - -Implemented standalone command. - -## Synopsis - -```bash -mogplex exec [OPTIONS] [ARGS] -``` - -## Description - -Non-interactive run. - -## Aliases - -- `e` - -## How It Works - -`mogplex exec` runs one non-interactive task and exits with the engine's final exit code. -The prompt is built from the remaining arguments after `exec`. - -If the prompt starts with `/`, the CLI routes it through the slash-command registry instead of the normal engine prompt path. - -## Common Uses - -```bash -mogplex exec "review the staged diff for regressions" -mogplex exec "summarize the repo structure and likely entrypoints" -mogplex exec "/status" -``` - -## Related Entry Points - -- `mogplex ""` is a shortcut for a one-off non-interactive run without spelling `exec`. -- `mogplex` without a prompt launches the interactive terminal UI. - -## Output - -For automation or scripting, combine `exec` with the global output flags such as `--output json`, `--json`, or `--jsonl`. - -## Options - -Run `mogplex exec --help` to see all supported flags. - -## See also - -- [Exec Mode](/cli/guides/exec-mode) -- [Quickstart](/cli/quickstart) -- [All commands](/cli/commands) diff --git a/content/docs/cli/commands/index.mdx b/content/docs/cli/commands/index.mdx index dc1bf06..c19902e 100644 --- a/content/docs/cli/commands/index.mdx +++ b/content/docs/cli/commands/index.mdx @@ -1,51 +1,60 @@ --- -title: Overview -description: Reference for the Mogplex CLI command surface, with implemented standalone commands promoted and reserved names summarized separately. +title: Slash Commands +description: Every slash command you can type in the Mogplex CLI composer. --- -Pick a command from the sidebar, or run `mogplex --help` in your terminal to see -the full list. +The CLI's command surface is **slash commands** in the composer. There are no top-level subcommands beyond bare `mogplex` (open the cockpit) and `mogplex --attach ` (attach mode). -Use the sidebar for the production-ready standalone commands. For the full flag -list of any command name, run `mogplex --help`. That output is the -source of truth and reflects whichever CLI version you have installed. +## Run control -## Start here +| Command | What it does | +| --- | --- | +| `/run ` | Start a new run with the given task as the initial prompt. | +| `/pause` | Pause the active run. Agents stop at the next safe point. | +| `/resume` | Resume a paused run. | +| `/kill` | Cancel the active run. Agents are stopped; in-flight tool calls are interrupted. | -The most important entrypoints for day-to-day use are: +## Surface inspection -- `mogplex` for an interactive session -- `mogplex exec ""` for a one-off task -- `mogplex login` and `mogplex login status` for stored credentials -- `mogplex slash list` for the slash-command registry +| Command | What it does | +| --- | --- | +| `/agents` | List agents on the active run with status and current action. | +| `/mcp` | Open the MCP drawer — per-server status and tools. | +| `/memory` | Open the Memory drawer — browse and manage entries. | +| `/diff` | Open the Diff drawer — inspect patches produced by the run. | +| `/cost` | Open the Cost drawer — tokens, cost, projections per agent. | -## Current state of the command surface +## Cockpit control -The help output currently lists more command names than the CLI has fully wired -as standalone subcommands. +| Command | What it does | +| --- | --- | +| `/model` | Open the Model Picker drawer — switch the run's model. | +| `/permissions ` | Set the active permission mode (`approval` or `auto`). Takes effect on next run. | +| `/permissions` | (no arg) Show the resolved permission state and where each rule came from. | +| `/export` | Open the Run Export drawer — serialize the run as JSON, JSONL, or Markdown. | +| `/help` | Open the Command Palette to fuzzy-search every action. | +| `/clear` | Clear the composer. | +| `/quit` (alias `/exit`) | Clean exit. | -In the current build, the most established standalone paths are: +## Auth -- `exec` -- `login` -- `slash` +| Command | What it does | +| --- | --- | +| `/login` | Open the in-app login flow. | +| `/logout` | Clear stored Mogplex token. The login screen appears next launch. | -The additional names that still appear in `mogplex --help` but are not yet -real standalone entrypoints are summarized on -[Reserved Names](/cli/commands/reserved-names) instead of being treated as -first-class command pages in the main nav. +## Composing tasks -## What this reference is for +Anything that is **not** a slash command is sent to the active agent as a task or follow-up: -Use the command pages when you already know the command you want and need the -canonical name, aliases, or help entrypoint. +```text +> rebuild the validation layer using zod and update the tests +``` -For interactive workflows that happen inside a live session, use -`mogplex slash list` and the [Quickstart](/cli/quickstart). +If you type a partial slash command, autocomplete candidates appear above the line. Unknown slash commands surface as inline composer errors so you don't accidentally send them as prompts. -For auth behavior and credential precedence, use the -[Authentication guide](/cli/guides/authentication). +## See also -For one-off scripting and slash execution, use the -[Exec Mode guide](/cli/guides/exec-mode) and -[Slash Commands guide](/cli/guides/slash-commands). +- [Reference → Drawers](/cli/reference/drawers) — what each drawer does once opened. +- [Concepts → Permissions](/cli/concepts/permissions) — what `/permissions ` actually changes. +- [Concepts → Attach](/cli/concepts/attach) — `--attach ` for in-flight runs. diff --git a/content/docs/cli/commands/login.mdx b/content/docs/cli/commands/login.mdx deleted file mode 100644 index 853fe15..0000000 --- a/content/docs/cli/commands/login.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: login -description: Authenticate (browser sign-in or API key). ---- - -{/* Auto-generated by scripts/gen-cli-reference.ts — do not edit by hand. */} - -## Status - -Implemented standalone command. - -## Synopsis - -```bash -mogplex login [OPTIONS] [ARGS] -``` - -## Description - -Authenticate (browser sign-in or API key). - -## Current Behavior - -The current build supports three top-level login paths: - -- `mogplex login` opens the same interactive auth chooser as bare `mogplex` -- `mogplex login mogplex` routes to the same chooser -- `mogplex login status` prints a safe summary of stored credentials without revealing secret material - -## What It Stores - -Browser sign-in stores a Mogplex token in `~/.mogplex/auth.json`. -API-key login stores the selected provider credential there instead. - -## Common Uses - -```bash -mogplex login -mogplex login status -``` - -For the full credential precedence rules, use the [Authentication guide](/cli/guides/authentication). - -## Options - -Run `mogplex login --help` to see all supported flags. - -## See also - -- [Authentication](/cli/guides/authentication) -- [Quickstart](/cli/quickstart) -- [All commands](/cli/commands) diff --git a/content/docs/cli/commands/meta.json b/content/docs/cli/commands/meta.json index 68fcb5a..c60714c 100644 --- a/content/docs/cli/commands/meta.json +++ b/content/docs/cli/commands/meta.json @@ -1,11 +1,5 @@ { "title": "Commands", "defaultOpen": true, - "pages": [ - "index", - "exec", - "login", - "slash", - "reserved-names" - ] + "pages": ["index"] } diff --git a/content/docs/cli/commands/reserved-names.mdx b/content/docs/cli/commands/reserved-names.mdx deleted file mode 100644 index d9b79ee..0000000 --- a/content/docs/cli/commands/reserved-names.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Reserved Names -description: Names shown in `mogplex --help` that are not yet production-ready standalone commands. ---- - -{/* Auto-generated by scripts/gen-cli-reference.ts — do not edit by hand. */} - -The CLI help surface currently includes some command names that are not yet fully wired as standalone entrypoints. -The docs keep these names visible because they are part of the published help surface, but they should not dominate the main command navigation. - -Use the implemented standalone commands for production workflows: - -- [`exec`](/cli/commands/exec) -- [`login`](/cli/commands/login) -- [`slash`](/cli/commands/slash) - -## Reserved names - -- `review` — Non-interactive code review against a base ref. Use `mogplex exec "review the staged diff for regressions"` for one-off code review. -- `logout` — Remove stored credentials. Use `/logout` inside a live session to remove the stored credential. Run `mogplex login status` afterward if you want to confirm what is still stored. -- `mcp` — Manage MCP server launchers in config.toml. Use `mogplex exec "/mcp"` or `/mcp` inside a session to inspect configured MCP servers. Manage shared MCP definitions in [Settings](/web/settings). -- `mcp-server` — Run mogplex as an MCP server on stdio. Use [Settings](/web/settings) for shared MCP configuration. Use `mogplex exec "/mcp"` for the current local inspection path. -- `plugin` — Manage plugins. Treat this as a reserved command name for now. The production-safe customization paths today are repo instructions, slash commands, and the hosted settings surfaces. -- `app` — Launch the desktop app (macOS only). The CLI and web app are the production surfaces today. Ignore this command unless a release note explicitly tells you to use it. -- `completion` — Generate shell completion scripts. Shell completion generation is not yet a stable standalone workflow in the current build. Use `mogplex --help` as the current source of truth for available commands and flags. -- `sandbox` — Run a raw command inside the Codex sandbox. Use `/sandbox` inside a live session. If you need a shell entrypoint, try `mogplex exec "/sandbox ..."` in environments where the slash command is available. -- `debug` — Debug helpers. Use `/logs`, `/status`, and [Observability](/web/observability) for current debugging workflows. -- `apply` — Re-apply the latest agent-produced diff. Use an interactive `mogplex` session and inspect or apply changes from the active workflow directly. -- `resume` — Resume a previous session. Use the interactive session and existing session history today. Do not script against `mogplex resume` yet. -- `fork` — Fork a previous session from a turn bookmark. Use a new `mogplex` session or the existing interactive workflow today. Do not script against `mogplex fork` yet. -- `features` — Inspect feature flags. Use the global `--feature KEY[=VAL]` flag on supported commands instead of relying on a standalone `mogplex features` workflow. - -## Experimental names - -- `app-server` — Run the JSON-RPC app-server (experimental). This is an experimental help-surface entry. Do not build automation around it yet. -- `cloud` — Browse Codex Cloud tasks (experimental). Use the [web app](/web) and [Observability](/web/observability) for hosted activity today. -- `exec-server` — Run the standalone exec server (experimental). Treat this as an experimental help-surface entry unless a release note explicitly tells you to use it. - -## Why this page exists - -This page is the honest place to document the additional command names exposed by `mogplex --help` without pretending each one is already a production-ready standalone workflow. - -## See also - -- [Commands overview](/cli/commands) -- [Exec Mode](/cli/guides/exec-mode) -- [Slash Commands](/cli/guides/slash-commands) diff --git a/content/docs/cli/commands/slash.mdx b/content/docs/cli/commands/slash.mdx deleted file mode 100644 index 9473322..0000000 --- a/content/docs/cli/commands/slash.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: slash -description: List or run slash commands. ---- - -{/* Auto-generated by scripts/gen-cli-reference.ts — do not edit by hand. */} - -## Status - -Implemented standalone command. - -## Synopsis - -```bash -mogplex slash [OPTIONS] [ARGS] -``` - -## Description - -List or run slash commands. - -## Current Behavior - -As a standalone subcommand, `mogplex slash` currently supports listing the slash registry. -If you omit the nested subcommand, it behaves the same as `mogplex slash list`. - -## Common Uses - -```bash -mogplex slash list -mogplex slash list --json -mogplex exec "/status" -mogplex exec "/mcp" -``` - -## Important Distinction - -- Use `mogplex slash list` to inspect the registry from the shell. -- Use `mogplex exec "/..."` to run a slash command non-interactively. -- Use a live `mogplex` session when you want the normal interactive slash workflow. - -## Options - -Run `mogplex slash --help` to see all supported flags. - -## See also - -- [Slash Commands](/cli/guides/slash-commands) -- [Quickstart](/cli/quickstart) -- [All commands](/cli/commands) diff --git a/content/docs/cli/concepts/approvals.mdx b/content/docs/cli/concepts/approvals.mdx new file mode 100644 index 0000000..ad9d9d1 --- /dev/null +++ b/content/docs/cli/concepts/approvals.mdx @@ -0,0 +1,77 @@ +--- +title: Approvals +description: How tool calls get gated, the approval queue, risk levels, and what auto-reject means. +--- + +When the active permission mode is `approval`, tool calls that would touch the workspace, write memory, run commands, delete files, use remote tools, or change the model pause and route through the **Approval drawer**. + +## The flow + +``` +agent wants to run something + │ + ▼ +permission resolver: allow / ask / deny? + │ + ├── allow ──► runs immediately, surfaces as a normal timeline event + ├── deny ──► auto-rejected, surfaces as a denied event + └── ask ──► joins the approval queue +``` + +Items in the queue render in the **Approval drawer** with: + +- the action and target +- an inferred **risk level** (`low`, `medium`, `high`) +- the agent that requested it +- the tool involved +- a quick approve/reject affordance + +## Actions that can be gated + +Any of these can hit the queue: + +| Action | What it usually means | +| --- | --- | +| `apply_patch` | Apply a code change | +| `write_memory` | Write to long-term memory | +| `run_command` | Execute a shell command | +| `delete_file` | Delete a file or directory | +| `use_remote_tool` | Call a remote MCP tool | +| `change_model` | Switch the model mid-run | + +## Risk levels + +| Level | Examples | +| --- | --- | +| **low** | Read-only commands, dry-run patches | +| **medium** | Writes inside the workspace, shell commands with side effects | +| **high** | Deletes, network calls, anything outside the workspace | + +The drawer color-codes by risk so you can scan quickly. + +## Approve, reject, batch + +- **Approve** runs the action immediately and resumes the agent. +- **Reject** marks the action as denied; the agent decides how to proceed (usually picking a different approach). +- **Batch approve** is available when multiple items are queued and obviously related. + +The store keeps **optimistic state** — once you approve, the UI assumes success until the event-loop confirms or contradicts. That means the drawer feels instant even if core takes a moment to act. + +## Auto-reject + +If a request matches a `deny` rule from the resolved permissions ([Permissions](/cli/concepts/permissions)), it's **auto-rejected** without ever joining the queue. The denial still appears in the timeline so you can see what was attempted. + +## What `auto` mode changes + +In `auto` mode, no requests join the queue — everything runs immediately. This is the explicit user opt-in to "no questions asked" and maps to the most permissive runtime flags. Switch back with `/permissions approval` whenever you want the gates back. + +## Where approvals show up + +- **Approval drawer** — the queue, opened with `/help` → "Open Approval" or via the command palette. +- **Priority alerts strip** — high-risk pending approvals surface here so they aren't missed if a drawer is closed. +- **Timeline** — every approved/rejected/auto-rejected action appears as a structured event. + +## Read next + +- [Permissions](/cli/concepts/permissions) — how `allow` / `ask` / `deny` rules are configured. +- [Reference → Drawers](/cli/reference/drawers) — the Approval drawer in detail. diff --git a/content/docs/cli/concepts/architecture.mdx b/content/docs/cli/concepts/architecture.mdx new file mode 100644 index 0000000..1500736 --- /dev/null +++ b/content/docs/cli/concepts/architecture.mdx @@ -0,0 +1,50 @@ +--- +title: Architecture +description: One-page mental model — transport → dispatcher → store → React, structured events only, no polling. +--- + +Data flow in the CLI is one-directional: + +``` +transport → dispatcher → store → React (panels + drawers) + ↑ + └── commands flow back out via the dispatcher +``` + +The TUI consumes events and sends commands. Nothing else. + +## What lives where + +| Layer | Responsibility | +| --- | --- | +| **Transport** | Speaks the wire protocol with Mogplex core: process spawn, daemon socket, or stdio JSONL. Emits structured events. Receives commands. | +| **Dispatcher** | Bridges transport ↔ store. Validates events with Zod schemas before they touch state. | +| **Store** | A single Zustand store holds all UI state — connection, active run, agents, timeline, MCP, memory, approvals, warnings, permissions. | +| **Reducer** | Pure transitions over events. New event in, new state out. | +| **React** | Panels and drawers subscribe to the store via selectors. Rendering is OpenTUI primitives — no DOM, no browser. | +| **Contracts** | Zod schemas + TypeScript types for every event, command, and state shape. The boundary with core. No React, no OpenTUI imports here. | + +## Hard rules + +These are invariants, not preferences: + +- **Structured events only.** Stdout chunks are not the source of truth. Real protocol events flow through the transport as typed messages validated by Zod schemas in `contracts/`. +- **No polling.** Reducers, subscriptions, async iterables. No `setInterval` for status checks. +- **Single store.** Components subscribe via selectors. Don't keep parallel local state for things in the store. +- **One transport selector.** The router (`transport/router.ts`) is the only place that picks a transport — see [Transports](/cli/concepts/transports). +- **Approval-gated actions go through the approval system.** Drawers and panels never shortcut it. +- **Permissions hydrate from disk before any transport is selected.** So `/permissions ` takes effect on the next run without a restart. + +## Why these rules matter + +The CLI is supposed to be a credible operator surface for runs that may take minutes or hours and may touch a real workspace. That depends on the data model being honest: + +- If the UI is event-driven, you can attach to a running session and rebuild the same screen. +- If state is centralized, the timeline, agents, and approvals can never disagree. +- If approvals are gated through one queue, "did I really approve this?" has a single answer. + +## Read next + +- [Transports](/cli/concepts/transports) — how core actually talks to the CLI. +- [Permissions](/cli/concepts/permissions) — what gets asked vs. allowed vs. denied. +- [Reference → Panels](/cli/reference/panels) — what each panel renders from the store. diff --git a/content/docs/cli/concepts/attach.mdx b/content/docs/cli/concepts/attach.mdx new file mode 100644 index 0000000..a4c7508 --- /dev/null +++ b/content/docs/cli/concepts/attach.mdx @@ -0,0 +1,74 @@ +--- +title: Attach +description: Use `--attach ` to pull up the cockpit for a run that started somewhere else (CI, web app, another shell). +--- + +Attach mode lets you observe and steer a run that's already in flight. The CLI connects to the Mogplex daemon, replays the run's history into the local store, and then streams new events as they happen. + +## Use it + +```bash +mogplex --attach run_abc123 +``` + +Or via env var (handy when the CLI is launched by another tool): + +```bash +MOGPLEX_ATTACH_RUN_ID=run_abc123 mogplex +``` + +When `--attach` is set, the [transport router](/cli/concepts/transports) selects the **daemon** transport regardless of TTY state. + +## What attach does + +1. Connects to the daemon socket (override with `MOGPLEX_DAEMON_SOCKET` if needed). +2. Asks for the run snapshot. +3. **Replays** the run's history into the store — agents, timeline, approvals, MCP, memory, cost are all rebuilt from events. +4. Subscribes to new events for the run. + +You see the same cockpit you'd see if you'd started the run yourself. + +## What you can do once attached + +Everything the cockpit normally does: + +- Watch the agents and timeline live. +- Open diffs, memory, MCP, cost drawers. +- Approve or reject pending tool calls. +- Pause, resume, kill the run. +- Switch models with `/model`. +- Export the run with `/export`. + +You're a real operator on the run, not a read-only observer. + +## When to use it + +- A run was started in CI or by a webhook and you need to take over. +- A teammate started a run on a shared daemon and you want to watch. +- Your previous CLI session crashed and you want to reattach to its run. +- The web app shows a long-running run and you want a richer terminal view. + +## Auth and permissions + +Attach uses your local Mogplex token (or provider key) the same way as any other session. Permission mode is still respected — if you attach in `approval` mode and the run produces a gated action, the Approval drawer surfaces it for **you** to decide. + +## Detach without killing the run + +Quit the CLI normally (`/quit`, double-tap Ctrl+C). The run keeps going on the daemon. Reattach any time with the same `--attach `. + +To **kill** the run, use `/kill` from inside the cockpit before detaching. + +## Logout-then-attach + +If you need to clear stored auth before reconnecting: + +```bash +mogplex --attach run_abc123 --logout +``` + +That clears the Mogplex token (forces the login screen) and then proceeds to attach. + +## Read next + +- [Transports](/cli/concepts/transports) — how the daemon transport gets selected. +- [Reference → Export](/cli/reference/export) — turning an attached run into an artifact. diff --git a/content/docs/cli/concepts/index.mdx b/content/docs/cli/concepts/index.mdx new file mode 100644 index 0000000..9feefa0 --- /dev/null +++ b/content/docs/cli/concepts/index.mdx @@ -0,0 +1,21 @@ +--- +title: Overview +description: The mental model for how the Mogplex CLI works — architecture, transports, permissions, approvals, and attach mode. +--- + +These pages explain the load-bearing concepts behind the CLI cockpit. Read them in order if you're new; jump to the one you need otherwise. + + + + + + + + + +## Pick a page by question + +- "What actually happens when I press a key?" → [Architecture](/cli/concepts/architecture) +- "Why did the CLI pick this transport?" → [Transports](/cli/concepts/transports) +- "Why is this tool call asking me / why isn't it?" → [Permissions](/cli/concepts/permissions) and [Approvals](/cli/concepts/approvals) +- "How do I see a run that started in CI?" → [Attach](/cli/concepts/attach) diff --git a/content/docs/cli/concepts/meta.json b/content/docs/cli/concepts/meta.json new file mode 100644 index 0000000..dcd5151 --- /dev/null +++ b/content/docs/cli/concepts/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Concepts", + "pages": ["index", "architecture", "transports", "permissions", "approvals", "attach"] +} diff --git a/content/docs/cli/concepts/permissions.mdx b/content/docs/cli/concepts/permissions.mdx new file mode 100644 index 0000000..3c16c6b --- /dev/null +++ b/content/docs/cli/concepts/permissions.mdx @@ -0,0 +1,99 @@ +--- +title: Permissions +description: Two-mode permission model — `approval` and `auto` — with global and per-project rules layered on disk. +--- + +The CLI's permission system has two halves: + +1. A **mode** that sets the baseline: `approval` (default, asks before touching the workspace) or `auto` (run anything without asking). +2. **Rules** in config files that layer on top — `allow`, `deny`, and `ask` lists keyed by tool/command pattern. + +## The two modes + +| Mode | Spawned runtime defaults | Use when | +| --- | --- | --- | +| **`approval`** | sandbox `workspace-write`, approval policy `on-request` | You want gated workflows. Tool calls that touch the workspace pause and surface in the Approval drawer. | +| **`auto`** | sandbox `danger-full-access`, approval policy `never` | You explicitly want everything to run unattended. Use deliberately — there is no second prompt. | + +Switch modes from the composer: + +```text +/permissions approval +/permissions auto +``` + +The new mode applies on the next `/run` (the process transport reads permissions at spawn time — no restart needed). + +## On-disk layout + +Two files, in order of precedence: + +``` +~/.mogplex/permissions.json # global +~/.mogplex/projects//permissions.json # project (overrides) +``` + +Both follow the same shape: + +```json +{ + "version": 1, + "mode": "approval", + "rules": { + "allow": ["bash:git status", "bash:pnpm test"], + "deny": ["bash:rm -rf *"], + "ask": ["bash:gh pr merge*"] + } +} +``` + +- `version` must be `1`. +- `mode` is optional in project files — when absent, the project inherits the global mode (or the built-in default). +- `rules` are partial; missing lists default to empty. + +Files are written with mode `0600` and the projects directory is `0700` so credentials and policy stay private. + +## How rules resolve + +Each rule has one of three sources: `default`, `global`, or `project`. The resolver layers them like this: + +1. **Built-in defaults** for the active mode. +2. **Global rules** from `~/.mogplex/permissions.json`. +3. **Project rules** from `~/.mogplex/projects//permissions.json` — projects can be **more permissive** than the global file. + +The slash status output (`/permissions`) explains why a pattern landed in `allow` vs `ask` vs `deny`, including which file it came from. + +## Pattern format + +Rules are matched against an action descriptor like `bash:`, `write:`, `read:`. Globs use shell-style wildcards. Concrete patterns: + +| Pattern | Matches | +| --- | --- | +| `bash:git status` | exact command | +| `bash:pnpm test*` | command prefix | +| `write:src/**` | any write under `src/` | +| `read:.env*` | any read of dotenv-style files | + +## Example: be permissive in a sandbox repo + +```json +{ + "version": 1, + "rules": { + "allow": ["bash:*", "write:**", "read:**"] + } +} +``` + +Drop that at `~/.mogplex/projects//permissions.json` to make a single repo run unattended while the global policy stays strict. + +## What this does **not** control + +- Auth (who you are signed in as) — see [Authentication](/cli/guides/authentication). +- MCP server enable/disable — see [Reference → Drawers](/cli/reference/drawers). +- Whether the CLI quits on Ctrl+C — see [Reference → Keybindings](/cli/reference/keybindings). + +## Read next + +- [Approvals](/cli/concepts/approvals) — how the queue surfaces gated calls. +- [Configuration and Flags](/cli/guides/configuration-and-flags) — env-var escape hatches. diff --git a/content/docs/cli/concepts/transports.mdx b/content/docs/cli/concepts/transports.mdx new file mode 100644 index 0000000..1ac840a --- /dev/null +++ b/content/docs/cli/concepts/transports.mdx @@ -0,0 +1,61 @@ +--- +title: Transports +description: The three transports the CLI speaks (process, daemon, stdio) and the rules the router uses to pick one. +--- + +The CLI talks to Mogplex core over one of three transports. The router (`transport/router.ts`) is the **only** place that picks one. + +## The three transports + +| Transport | When it's used | What it does | +| --- | --- | --- | +| **process** | Default for an interactive terminal | Spawns a local exec runtime as a child process. The CLI watches its structured event stream and sends commands back. | +| **daemon** | Attach mode (`--attach`) or `MOGPLEX_TRANSPORT=daemon` | Connects to a running mogplex daemon over a Unix socket. Lets you observe and steer a run that is already in flight. | +| **stdio** | `MOGPLEX_TRANSPORT=stdio` or non-TTY stdin | Reads JSONL events from stdin and writes commands to stdout. Used for piping events from another process. | + +## Selection rules + +The router resolves the transport in this exact order: + +1. `MOGPLEX_TRANSPORT=process` or `MOGPLEX_TRANSPORT=live` → **process** +2. `MOGPLEX_TRANSPORT=daemon` **or** `--attach ` is set → **daemon** +3. `MOGPLEX_TRANSPORT=stdio` **or** stdin is a pipe (non-TTY) → **stdio** +4. Default (TTY stdin, no attach) → **process** + +If selection somehow falls through, the router falls back to **daemon** and emits a `transport_fallback` diagnostic. + +## Examples + +```bash +# Default — spawn a local exec process +mogplex + +# Attach to an in-flight run via the daemon socket +mogplex --attach run_abc123 + +# Force stdio (typically used by tooling, not humans) +echo '{"type":"snapshot",...}' | MOGPLEX_TRANSPORT=stdio mogplex + +# Force the process transport even when stdin is a pipe +MOGPLEX_TRANSPORT=process mogplex +``` + +## Permissions and the process transport + +The process transport reads runtime permissions from the active mode **at spawn time**. That means `/permissions auto` (or `/permissions approval`) takes effect on the **next** `/run` without restarting the CLI. Same store, same transport — only the spawn flags change. + +See [Permissions](/cli/concepts/permissions). + +## Daemon socket location + +When using the daemon transport, the socket path is read from `MOGPLEX_DAEMON_SOCKET`. If unset, the daemon's default location is used. + +## Why this matters + +Most users never think about transports. They matter when: + +- You're debugging "why isn't my run showing up?" — usually the transport selection picked the wrong thing because `MOGPLEX_TRANSPORT` is set in the shell. +- You want to attach to a long-running CI run from your laptop — that's daemon mode. +- You're piping structured events from another tool into the cockpit — that's stdio. + +For the env-var reference, see [Configuration and Flags](/cli/guides/configuration-and-flags). diff --git a/content/docs/cli/guides/authentication.mdx b/content/docs/cli/guides/authentication.mdx index 533375a..da23415 100644 --- a/content/docs/cli/guides/authentication.mdx +++ b/content/docs/cli/guides/authentication.mdx @@ -1,15 +1,17 @@ --- title: Authentication -description: Understand Mogplex auth precedence, browser sign-in, stored provider keys, and what `mogplex login`, `/login`, and `/logout` actually change. +description: In-app login, credential precedence, browser sign-in, stored provider keys, and what `/login` and `/logout` actually change. --- -Mogplex can run with either direct provider credentials or your Mogplex -account. On startup, it resolves auth in a fixed order. +import { Callout } from 'fumadocs-ui/components/callout'; + +The CLI ships to end users — auth is in-app. You do **not** need to set environment variables for normal use. Env vars exist as escape hatches for CI and ephemeral shells. ## Resolution order -1. **Environment variable first.** If a provider env var is set in your shell, - Mogplex uses it. +When the CLI starts up, it resolves credentials in this order: + +1. **Provider env var in the current shell.** If set, it wins — no matter what is stored on disk. | Provider | Environment variable | | ---------- | ------------------------------ | @@ -24,121 +26,80 @@ account. On startup, it resolves auth in a fixed order. | Cohere | `COHERE_API_KEY` | | Vercel | `VERCEL_API_TOKEN` | -2. **Fallback to stored credentials.** If the env var is absent, Mogplex reads - `~/.mogplex/auth.json`. +2. **Stored credentials** in `~/.mogplex/auth.json` (mode `0600`). -3. **No credentials means an interactive chooser or a clear failure.** Running - bare `mogplex` in an interactive terminal opens the auth chooser. In - non-interactive contexts, Mogplex exits with a clear message telling you to - authenticate first. +3. **No credentials** → the in-app **login screen** appears (or, in non-interactive contexts, a clear failure). -The practical rule is simple: shell env vars outrank everything else. - -## What account-backed login means +The practical rule: shell env vars outrank everything else. -Browser login is not the same thing as storing a direct provider key locally. +## In-app login -When you sign in with your Mogplex account, the CLI stores a `mogplex` -credential in `~/.mogplex/auth.json` and can reuse hosted account state such -as: - -- synced model catalog -- remote MCP server definitions -- the account-backed model access configured for your Mogplex user +On first run, the login screen offers two paths: -This is the cleanest setup when you want the web app and CLI to share models, -MCP configuration, and account identity. +- **Sign in with Mogplex** — opens a browser flow for account-backed login. The CLI listens on a local callback and stores a Mogplex token. Recommended. +- **Use a provider API key** — store an Anthropic, OpenAI, Google, Groq, Mistral, DeepSeek, xAI, Cohere, or Vercel AI Gateway key locally. -If the account login succeeds but prompts still fail, the hosted account -usually does not have usable model access yet. Add the needed provider key in -[Web Settings](/web/settings). +You can re-open the login screen later from the composer: -## Entry points - -### `mogplex` - -Running bare `mogplex` is the normal entrypoint: - -```bash -mogplex +```text +/login ``` -If no auth is available yet, Mogplex prompts you to either: - -- sign in with Mogplex in the browser -- store a direct provider API key locally - -### `mogplex login` +## What account-backed login means -If you want to jump straight into setup, `mogplex login` opens the same -interactive auth flow: +Browser login is not the same thing as storing a direct provider key. -```bash -mogplex login -``` +When you sign in with Mogplex, the CLI stores a `mogplex` credential in `~/.mogplex/auth.json` and can reuse hosted state: -You can inspect the stored auth file without opening the TUI: - -```bash -mogplex login status -``` - -### `/login` +- synced model catalog +- remote MCP server definitions +- account-backed model access configured for your Mogplex user -Inside a live session, `/login` is still the in-session path for switching or -storing credentials. `/login mogplex` goes to browser login; `/login -` asks for a provider key directly. +If account login succeeds but prompts fail, the hosted account usually does not have usable model access yet. Add a provider key in [Web Settings](/web/settings). -## Provider keys +## Provider keys (env or stored) -Direct provider credentials still work and still take precedence over the -account login path. This is the preferred pattern for CI, ephemeral shells, and -environments where you do not want credentials written to disk. +Direct provider credentials still work and still take precedence over the account login path. This is the preferred pattern for CI and ephemeral shells. ```bash export OPENAI_API_KEY=sk-... mogplex ``` -If both a stored credential and an env var exist for the same provider, the env -var wins. +If both a stored credential and an env var exist for the same provider, the env var wins. -## `/logout` and what it really changes +## `/logout` -Use `/logout` inside a live session to remove a stored credential from -`~/.mogplex/auth.json`. +```text +/logout +``` -Three details matter: +Clears the Mogplex token (and provider key, if stored) from `~/.mogplex/auth.json`. Three things to remember: -- **Env vars still win.** If the matching env var is set, the next session will - still authenticate through that env var. -- **Treat logout as affecting the next session.** If the current session already - constructed a provider adapter, restart the session when you need immediate - certainty that the old credential is gone. -- **Logging out of Mogplex clears shared hosted state.** Remote model catalog - data and remote MCP server sync are cleared when the Mogplex account token is - no longer available. +- **Env vars still win.** If the matching env var is set, the next session will still authenticate through it. +- **Restart for certainty.** The current process may still hold the old adapter. Quit (`/quit`) and relaunch if you need an immediate clean slate. +- **Logout clears hosted state.** Synced model catalog and remote MCP definitions vanish locally. -## Common outcomes and what they mean +You can also force logout-then-attach in one shot: -- `mogplex login status` shows only `mogplex`: the CLI is in account-backed - mode. -- `mogplex login status` shows a provider entry and the session uses that - provider: direct provider auth is active. -- the CLI behaves differently than `login status` suggests: check env vars - first, because they outrank stored auth. -- account login succeeds but prompts fail: the hosted account probably still - lacks model access in [Web Settings](/web/settings). +```bash +mogplex --attach run_abc123 --logout +``` -## Logging and credential safety + + The CLI never reads `~/.mogplex/auth.json` to display secret material in + logs. Session logs at `~/.mogplex/logs/.jsonl` redact API keys, + tokens, and the raw contents of `auth.json`. + -Session logs at `~/.mogplex/logs/.jsonl` do not contain: +## Common outcomes -- API keys -- OAuth tokens or PATs -- raw contents of `~/.mogplex/auth.json` +- The login screen appears at startup → no credentials anywhere; sign in or store a provider key. +- Login succeeds but prompts fail → account login is active but the hosted account lacks model access. Fix in [Web Settings](/web/settings). +- The CLI behaves differently than the in-app login implies → check env vars first; they outrank stored auth. -The runtime redacts those values before writing logs to disk. +## See also -When `MOGPLEX_DEBUG=1` is set, debug logs can still capture prompt content or -tool output. Treat debug logs with the same care as your source code. +- [Configuration and Flags](/cli/guides/configuration-and-flags) — env-var escape hatches. +- [Concepts → Attach](/cli/concepts/attach) — `--logout` plus `--attach`. +- [Skills → mogplex-auth](/cli/skills/mogplex-auth) — the agent skill that gates other Mogplex actions on auth. diff --git a/content/docs/cli/guides/configuration-and-flags.mdx b/content/docs/cli/guides/configuration-and-flags.mdx index 25a88ff..067b1ee 100644 --- a/content/docs/cli/guides/configuration-and-flags.mdx +++ b/content/docs/cli/guides/configuration-and-flags.mdx @@ -1,200 +1,87 @@ --- title: Configuration and Flags -description: Understand config.toml locations, profiles, environment precedence, and the global CLI flags that override Mogplex behavior per run. +description: The CLI's single flag (`--attach`), the env-var escape hatches, and where local state lives on disk. --- -Use this guide when you need to answer: +import { Callout } from 'fumadocs-ui/components/callout'; -- where does Mogplex read configuration from? -- which layer wins when config, env vars, profiles, and flags disagree? -- which flags are safe to treat as per-run overrides? +The CLI is configured **in-app**. There is one CLI flag and a small set of environment variables that exist as escape hatches. -## The three layers to think about + + Env vars are not required for normal use. They exist for CI, attach + workflows, and tooling that needs to inject behavior. If you are setting + env vars to make day-to-day work happen, something is wrong — start with + the in-app login and `/permissions` instead. + -Mogplex configuration is easiest to understand when you separate it into three -jobs: +## CLI flags -- **config files** for stable defaults -- **environment variables** for shell-scoped or secret state -- **CLI flags** for one-off overrides on a single run +| Flag | What it does | +| --- | --- | +| `--attach ` | Attach to an in-flight run via the daemon transport. See [Concepts → Attach](/cli/concepts/attach). | +| `--logout` | Clear the stored Mogplex token before launching. Combine with `--attach` if needed. | +| `--events=jsonl` | Read events from stdin in JSONL format (used with stdio transport). | -If behavior feels surprising, the usual cause is that one of those layers is -outranking the others. +That's it. Everything else is in-app — slash commands, drawers, the login screen. -## Config file locations +## Environment variables -The main user config lives at: +### Auth (provider keys) -```text -$MOGPLEX_HOME/config.toml -``` +See the table in [Authentication → Resolution order](/cli/guides/authentication#resolution-order). Setting any provider env var overrides stored credentials for that provider. -If `MOGPLEX_HOME` is unset, the default path is: +### Transport selection -```text -~/.mogplex/config.toml -``` +| Variable | Effect | +| --- | --- | +| `MOGPLEX_TRANSPORT=process` (or `=live`) | Force the process transport — spawn a local exec runtime. | +| `MOGPLEX_TRANSPORT=daemon` | Force the daemon transport — connect to a running daemon. | +| `MOGPLEX_TRANSPORT=stdio` | Force the stdio transport — read JSONL from stdin. | +| `MOGPLEX_DAEMON_SOCKET` | Override the daemon socket path. | +| `MOGPLEX_ATTACH_RUN_ID` | Equivalent to `--attach `. | -Project-level config can also live inside a repo at: +See [Concepts → Transports](/cli/concepts/transports) for the selection rules. -```text -./.mogplex/config.toml -``` +### Storage -Two environment details matter: +| Variable | Effect | +| --- | --- | +| `MOGPLEX_HOME` | Override the home directory location (default `~/.mogplex/`). | +| `CODEX_HOME` | Deprecated fallback; use `MOGPLEX_HOME` instead. | -- `MOGPLEX_HOME` overrides the home directory location entirely -- `CODEX_HOME` still works as a fallback, but it is deprecated in favor of - `MOGPLEX_HOME` +## Local state on disk -## Resolution order +| Path | Contents | +| --- | --- | +| `~/.mogplex/auth.json` | Mogplex token and provider credentials (mode `0600`). | +| `~/.mogplex/permissions.json` | Global permission mode and rules. | +| `~/.mogplex/projects//permissions.json` | Per-project permission overrides. | +| `~/.mogplex/logs/.jsonl` | Structured session logs (secrets redacted). | +| `~/.mogplex/bin/mogplex` | The CLI binary (default install location). | -Mogplex resolves config from lowest priority to highest priority in this exact -order: +All Mogplex-owned files use restrictive modes (`0600` for files, `0700` for directories) so credentials and policy stay private. -1. built-in defaults -2. user config at `$MOGPLEX_HOME/config.toml` -3. project config at `./.mogplex/config.toml` -4. the active profile under `[profiles.]` -5. environment variables -6. `--config KEY=VALUE` overrides -7. per-invocation CLI flags such as `--sandbox` and `--model` +## Configuring permissions -That means a repo config can override your home config, env vars can override -both, and explicit flags still win over everything else. +Permissions are managed by editing the JSON files above or by using `/permissions ` in the composer. See [Concepts → Permissions](/cli/concepts/permissions) for the on-disk schema and resolution rules. -## Profiles +## Configuring MCP -Profiles are the clean way to switch between named CLI behaviors without -rewriting your main config every time. +MCP servers are configured in [Web Settings](/web/settings) when you're signed in to Mogplex (synced down on launch). The CLI's MCP drawer surfaces what's configured but does not edit it directly. -Example: +## Why the CLI doesn't read `config.toml` -```toml -model_provider = "openai" -sandbox_mode = "read-only" -approval_policy = "on-request" +Earlier Mogplex CLI builds used `~/.mogplex/config.toml` for CLI-only options like `model_provider`, `sandbox_mode`, profiles, and `slash_commands`. The current cockpit replaces that surface with: -[profiles.write] -sandbox_mode = "workspace-write" +- **In-app login** for `model_provider` and credentials. +- **`/permissions `** + the permissions JSON files for sandbox and approval policy. +- **`/model`** for runtime model selection. +- **The slash command registry** (built-in) for the composer surface. -[profiles.safe] -sandbox_mode = "read-only" -approval_policy = "never" -``` +If you have an old `config.toml` from a previous install, it is ignored by the current CLI. -Select a profile with either: +## See also -```bash -mogplex --profile fast -``` - -or: - -```bash -MOGPLEX_PROFILE=fast mogplex -``` - -`--profile` wins over `MOGPLEX_PROFILE`, and `CODEX_PROFILE` is only a fallback -when the Mogplex-prefixed variable is absent. - -## One-off overrides with `--config` - -Use `--config` when you want to override a config key without editing any file. - -Examples: - -```bash -mogplex --config sandbox_mode=workspace-write --config approval_policy=never -mogplex --config model_provider=anthropic exec "summarize this repository" -``` - -This is useful when you want the run to stay self-documenting in shell history -or CI logs. - -## Global flags that matter most - -The top-level CLI currently supports these high-signal flags: - -- `--config KEY=VALUE` for direct config-key overrides -- `--sandbox MODE` for `read-only`, `workspace-write`, or - `danger-full-access` -- `--approval POLICY` for `untrusted`, `on-failure`, `on-request`, or `never` -- `--cwd DIR` to change the working directory -- `--model NAME` to override the selected model -- `--profile NAME` to activate one named profile -- `--feature KEY[=VAL]` to toggle feature flags -- `--color WHEN` for `auto`, `always`, or `never` - -These flags are parsed before Mogplex decides whether you are launching the TUI -or exec mode, so they apply to both `mogplex` and `mogplex exec ...` unless the -flag itself is exec-specific. - -## Output flags are exec-specific - -Structured output belongs to one-off runs, not the interactive TUI. - -Use these with `mogplex exec` or the bare-prompt exec shorthand: - -- `--output text` -- `--output json` -- `--output jsonl` -- `--json` -- `--jsonl` - -Examples: - -```bash -mogplex exec --json "summarize this repository" -mogplex --jsonl "review the staged diff for regressions" -``` - -If another program is going to parse the result, prefer JSON or JSONL instead -of screen-oriented text. - -## Slash-command config still lives in `config.toml` - -The `slash_commands` section in `config.toml` is still the right place for -slash-registry policy such as: - -- disabling specific command names -- adding aliases -- adding extra user-scope command directories - -Keep repo behavior in `.agents/commands/`, and keep personal registry policy in -config. - -For the slash loader itself, see [Slash Commands](/cli/guides/slash-commands). -For repo-local command files, see -[Project Commands](/cli/guides/project-commands). - -## Startup behavior toggle - -Mogplex checks for published updates on startup and can print an update banner -in interactive shells. - -If you want to suppress that banner for a shell session or script, set: - -```bash -MOGPLEX_SKIP_UPDATE_CHECK=1 -``` - -## Common mistakes - -- assuming project config beats environment variables: env vars still win -- forgetting that `--profile` only selects `[profiles.NAME]`, not a different - config file -- using `--json` with interactive `mogplex` and expecting the TUI to emit - machine-readable output -- relying on `CODEX_HOME` or `CODEX_PROFILE` without realizing they are fallback - compatibility paths, not the preferred names - -## A practical split - -- put durable personal defaults in `$MOGPLEX_HOME/config.toml` -- put repo-specific defaults in `./.mogplex/config.toml` -- use profiles for named modes like `write`, `safe`, or `ci` -- use flags when the override should only apply to one run - -That keeps the CLI predictable without turning every invocation into a wall of -arguments. +- [Authentication](/cli/guides/authentication) +- [Concepts → Transports](/cli/concepts/transports) +- [Concepts → Permissions](/cli/concepts/permissions) diff --git a/content/docs/cli/guides/exec-mode.mdx b/content/docs/cli/guides/exec-mode.mdx deleted file mode 100644 index b38e10f..0000000 --- a/content/docs/cli/guides/exec-mode.mdx +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Exec Mode -description: Use `mogplex exec` and bare prompt invocation for one-off, non-interactive tasks, scripts, slash-command execution, and structured output. ---- - -`mogplex exec` is the non-interactive side of the CLI. - -Use it when you want one task, one result, and an exit code you can treat like -any other shell command. - -## Two equivalent entrypoints - -These two forms both run a one-off task: - -```bash -mogplex exec "review the staged diff for regressions" -mogplex "review the staged diff for regressions" -``` - -The explicit `exec` form is usually clearer in scripts and CI. The bare-prompt -form is faster when typing by hand. - -When you pass prompt arguments without a subcommand, the CLI routes that call to -exec mode automatically. - -## What exec mode is for - -Use exec mode when you want: - -- a single prompt and final result -- shell-friendly exit behavior -- structured output such as JSON or JSONL -- a slash command run without opening the TUI -- a quick one-off task that should not become a long interactive session - -If you want back-and-forth conversation, model switching, or repeated edits in -one live session, use bare `mogplex` instead. - -## What makes exec mode different - -Exec mode is intentionally self-contained: - -- it does not open the interactive TUI -- it does not include the plan/request-user-input interaction path -- it is designed to finish the task and exit - -In practice, treat it as the CLI equivalent of "run this one thing and stop." - -## Structured output - -For automation, wrappers, and shell pipelines, combine `exec` with output -flags: - -```bash -mogplex exec --json "summarize this repository" -mogplex exec --jsonl "review the staged diff for correctness issues" -``` - -The top-level CLI also supports: - -- `--output text` -- `--output json` -- `--output jsonl` -- `--json` -- `--jsonl` - -If another tool is supposed to consume the result, use JSON or JSONL instead of -screen-oriented text. - -## Slash commands in exec mode - -If the prompt starts with `/`, exec mode routes it through the slash-command -registry instead of the normal prompt path. - -Examples: - -```bash -mogplex exec "/status" -mogplex exec "/mcp" -mogplex exec "/logs --lines=100" -``` - -That registry includes: - -- built-in slash commands -- project commands from `.agents/commands/` -- user commands from `~/.mogplex/commands/` - -So `mogplex exec "/your-project-command"` is a valid way to run project-local -slash workflows from scripts or shell history. - -## Local image paths - -Exec mode also understands local image paths in prompts and passes them to the -engine as structured image inputs instead of plain text paths. - -That matters when you want a one-off multimodal task without starting the TUI. - -## Good defaults - -- prefer `mogplex exec "..."` in scripts, CI, and automation -- use bare `mogplex "..."` when you want the shortcut interactively -- use `mogplex slash list` to inspect the available slash registry before you - depend on a command in automation -- keep prompts task-shaped instead of trying to simulate a long conversation in - one shell call - -## Good use cases - -- review a diff from CI or a git hook -- summarize a repo before another tool step -- run a project slash command from a shell script -- inspect local slash state without opening the TUI -- run a one-off prompt that should emit machine-readable output - -## Common mistakes - -- using exec mode for work that really needs iterative back-and-forth -- assuming a top-level subcommand exists when the slash equivalent is the real - supported path -- skipping `--json` or `--jsonl` when another program is supposed to parse the - result diff --git a/content/docs/cli/guides/index.mdx b/content/docs/cli/guides/index.mdx index b2a3179..ba0f891 100644 --- a/content/docs/cli/guides/index.mdx +++ b/content/docs/cli/guides/index.mdx @@ -1,6 +1,6 @@ --- title: Overview -description: Deep dives into how the Mogplex CLI behaves once you need more than the install and quickstart pages. +description: Behavioral guides for the Mogplex CLI — auth, configuration, slash workflows, and repo-local conventions. --- Use these pages when you want behavior and decision-making, not just syntax. @@ -9,52 +9,38 @@ Use these pages when you want behavior and decision-making, not just syntax. - ## Pick a guide by question -- "Why is the CLI choosing this provider or model?" - Read [Authentication](/cli/guides/authentication). -- "Where should this default live: config file, env var, profile, or flag?" - Read [Configuration and Flags](/cli/guides/configuration-and-flags). -- "Should this task be interactive or one-shot?" - Read [Exec Mode](/cli/guides/exec-mode). -- "Why does this slash command exist in one place but not another?" - Read [Slash Commands](/cli/guides/slash-commands). -- "How do I make Mogplex behave like part of this repo?" - Read [Project Commands](/cli/guides/project-commands). +- "Why is the CLI choosing this provider or model?" → [Authentication](/cli/guides/authentication) +- "Where does this default live and which env var overrides it?" → [Configuration and Flags](/cli/guides/configuration-and-flags) +- "How do I drive a run from the composer?" → [Slash Commands](/cli/guides/slash-commands) +- "How do I make Mogplex behave like part of this repo?" → [Project Commands](/cli/guides/project-commands) ## Read these in order if you are new 1. [Installation](/cli/installation) 2. [Quickstart](/cli/quickstart) -3. [Authentication](/cli/guides/authentication) -4. [Configuration and Flags](/cli/guides/configuration-and-flags) -5. [Exec Mode](/cli/guides/exec-mode) +3. [Concepts → Architecture](/cli/concepts/architecture) +4. [Authentication](/cli/guides/authentication) +5. [Configuration and Flags](/cli/guides/configuration-and-flags) 6. [Slash Commands](/cli/guides/slash-commands) 7. [Project Commands](/cli/guides/project-commands) - -If you already have the CLI working, skip straight to the behavioral page that -matches the thing you are trying to understand. diff --git a/content/docs/cli/guides/meta.json b/content/docs/cli/guides/meta.json index ede85b5..6a02bb5 100644 --- a/content/docs/cli/guides/meta.json +++ b/content/docs/cli/guides/meta.json @@ -1,4 +1,4 @@ { "title": "Guides", - "pages": ["index", "authentication", "configuration-and-flags", "exec-mode", "slash-commands", "project-commands"] + "pages": ["index", "authentication", "configuration-and-flags", "slash-commands", "project-commands"] } diff --git a/content/docs/cli/guides/project-commands.mdx b/content/docs/cli/guides/project-commands.mdx index 84292b7..f0a6b34 100644 --- a/content/docs/cli/guides/project-commands.mdx +++ b/content/docs/cli/guides/project-commands.mdx @@ -1,21 +1,20 @@ --- title: Project Commands -description: Use `AGENTS.md`, `.agents/commands/`, and `/init` to make Mogplex behave like part of the repository instead of a generic terminal tool. +description: Use `AGENTS.md` and per-project permission files to make Mogplex behave like part of the repository. --- -The CLI gets dramatically better when the repository teaches it how to work. +Two repo-local layers shape how the CLI behaves inside a checked-out repo: -Two local layers matter most: +- `AGENTS.md` at the repo root — durable instructions for any agent operating in this codebase. +- `~/.mogplex/projects//permissions.json` — per-project permission overrides. -- `AGENTS.md` at the project root -- markdown slash commands under `.agents/commands/` +Both are optional; the CLI works without either. They make the experience dramatically better when the repo has stable conventions or wants different gates than your global default. ## `AGENTS.md` -`AGENTS.md` is the repo-local instruction layer. It is the place for stable -truths about how work should happen in this codebase. +`AGENTS.md` is the repo-local instruction layer. Place it at the project root. -Good `AGENTS.md` content includes: +Good content includes: - project purpose and architecture notes - build, test, lint, and typecheck commands @@ -23,151 +22,58 @@ Good `AGENTS.md` content includes: - naming or error-handling patterns - repo-specific guardrails the assistant should follow -Keep `AGENTS.md` durable. If the guidance changes every hour, it probably -belongs in the current task prompt instead. +Keep it durable. If guidance changes hourly, it belongs in the task prompt instead. -## Where project slash commands live +`AGENTS.md` is read by the Mogplex orchestrator when it spawns agents into the repo — it's not parsed by the CLI itself, but it shapes every run that runs in this repo. -Mogplex loads project commands from: +## Per-project permissions -```text -/.agents/commands/**/*.md -``` - -This is the preferred path because it follows a cross-tool convention other AI -coding tools can also understand. - -The legacy path still works: - -```text -/.mogplex/commands/**/*.md -``` - -User-scoped commands are loaded from: +Permission rules can be set globally or per-project. The project file lives at: ```text -$AGENTS_HOME/commands/**/*.md -# or, by default -~/.mogplex/commands/**/*.md -``` - -## Precedence rules - -When the same command name exists in more than one place, Mogplex resolves it -in this order: - -1. project commands from `.agents/commands/` -2. project commands from the legacy `.mogplex/commands/` -3. user commands -4. built-in commands - -That means a repo-local command can intentionally override a user command, and -either can shadow a built-in when you have a good reason. - -## Command file format - -A custom command is a markdown file with optional YAML frontmatter. The body is -the prompt template sent to the model. - -Example: - -```markdown ---- -description: Review staged changes for correctness and missing tests -arguments: - - name: focus - kind: positional -aliases: - - staged-review ---- -Review the staged git diff for correctness bugs, regressions, and missing -tests. - -Extra focus: $1 +~/.mogplex/projects//permissions.json ``` -Useful frontmatter fields include: +It can override the mode and add `allow` / `deny` / `ask` rules that are layered **on top of** the global rules. Projects can be more permissive than the global file. -- `description` -- `aliases` -- `arguments` -- `model` -- `allowed-tools` -- `available-during-task` +Example — make a single sandbox repo run unattended while the global policy stays strict: -A bare markdown file with no frontmatter is still a valid command. - -## Template substitution - -Command bodies support positional and named placeholders: - -- `$ARGUMENTS` for all positional args joined together -- `$1`, `$2`, and so on for positional slots -- `${NAME}` or `$NAME` for named args - -That lets one command file handle a family of repeatable prompts without shell -scripting. - -## Namespacing from directories - -Nested directories turn into namespaced slash commands: - -```text -.agents/commands/release/notes.md -> /release:notes -.agents/commands/deploy.md -> /deploy +```json +{ + "version": 1, + "rules": { + "allow": ["bash:*", "write:**", "read:**"] + } +} ``` -Use this when the repo has enough commands that a flat list starts getting -messy. - -## Bootstrap with `/init` - -Inside a live session, `/init` scaffolds the basics: - -- an `AGENTS.md` -- a starter `.agents/commands/review.md` - -That makes `/init` the fastest way to turn an unprepared repo into one with -basic Mogplex conventions. +See [Concepts → Permissions](/cli/concepts/permissions) for the schema, resolution rules, and how `/permissions` reports each rule's source. ## Verify what loaded -Use the slash registry to confirm what Mogplex can see: +In the composer: -```bash -mogplex slash list -mogplex slash list --json +```text +/permissions ``` -That output includes built-ins plus project and user commands after precedence -resolution. - -## Config-level control - -The `slash_commands` section in `~/.mogplex/config.toml` can: - -- disable commands by name -- create aliases -- add extra user-scope directories - -That means repo-local behavior belongs in the repo, while personal preferences -belong in your home config. - -For config file locations, profile selection, and full precedence rules, use -[Configuration and Flags](/cli/guides/configuration-and-flags). +Without an argument, `/permissions` shows the resolved mode and rules and explains where each pattern came from (`default`, `global`, or `project`). ## Recommended split - put long-lived repo rules in `AGENTS.md` -- put repeatable prompt workflows in `.agents/commands/` -- keep personal-only shortcuts in `~/.mogplex/commands/` -- use normal shell scripts when the behavior is command-shaped instead of - prompt-shaped +- put per-repo permission overrides in `~/.mogplex/projects//permissions.json` +- keep personal-only defaults in `~/.mogplex/permissions.json` (global) +- use `/permissions ` for one-off mode flips that don't deserve a config file ## Anti-patterns - putting volatile task notes in `AGENTS.md` -- storing personal-only commands in the repo -- creating a repo command that duplicates a built-in name without good reason -- using slash command files for workflows that would be clearer as shell - scripts or project tooling +- relying on a per-project `permissions.json` to **restrict** something the global already allows (the merge can only add allows; deny rules need to be set explicitly per scope) +- editing `permissions.json` while the cockpit is mid-run — wait until `/permissions` confirms the next state, then `/run` again + +## See also + +- [Concepts → Permissions](/cli/concepts/permissions) +- [Concepts → Approvals](/cli/concepts/approvals) +- [Configuration and Flags](/cli/guides/configuration-and-flags) diff --git a/content/docs/cli/guides/slash-commands.mdx b/content/docs/cli/guides/slash-commands.mdx index 5c194fd..ab6be4a 100644 --- a/content/docs/cli/guides/slash-commands.mdx +++ b/content/docs/cli/guides/slash-commands.mdx @@ -1,112 +1,109 @@ --- title: Slash Commands -description: Understand the slash-command surface, how discovery works, and how to run slash commands inside a session or through exec mode. +description: Common workflows in the composer — start a run, pause, switch model, view a diff, approve, export. --- -Slash commands are the local control surface for the Mogplex CLI. +For the full list of slash commands, see [Commands](/cli/commands). This guide walks the workflows that actually use them. -They cover actions that are more like session control or local tooling than -normal model prompts. +## Start a run -## Where slash commands work +```text +/run review the staged diff for regressions +``` -There are three relevant paths: +The Agents panel populates as core spawns workers. The Timeline streams events. Watch the Header for `transport: nominal` and a non-empty `model`. -1. Inside a live `mogplex` session -2. From the shell with `mogplex slash list` -3. From the shell with `mogplex exec "/..."` for one-off execution +## Pause and resume -Today, `mogplex slash` is mainly a registry-inspection command. Actual slash -execution from the shell goes through `mogplex exec "/..."`. +```text +/pause +/resume +``` -## Important distinction +`/pause` lets agents stop at the next safe point. Use it before you switch models or change permissions. -There are two different surfaces that often get confused: +## Switch the model mid-run -- **top-level CLI commands** such as `mogplex exec` and `mogplex login` -- **slash commands** such as `/status`, `/mcp`, and `/compact` +```text +/model +``` -Some capabilities exist today as slash commands even when the matching -top-level command name is not fully wired yet. +Opens the **Model Picker** drawer. Pick a model and confirm. If the active permission mode gates `change_model` as `ask`, the change surfaces in the Approval drawer first. -## Built-in slash commands +## Inspect a diff -The current built-in surface includes commands such as: +```text +/diff +``` -- `/help` -- `/status` -- `/model` -- `/approvals` -- `/compact` -- `/clear` -- `/init` -- `/review` -- `/config` -- `/mcp` -- `/skills` -- `/login` -- `/logout` -- `/logs` -- `/sandbox` -- `/quit` +Opens the **Diff** drawer with the most recent patch. Step through hunks; approve or reject if the run is gated. -Use `mogplex slash list` to inspect the exact registry in your environment. +## Approve or reject pending tool calls -## Discover the registry +The Approval drawer surfaces gated requests automatically. From the composer, you can also use the Command Palette: -```bash -mogplex slash list -mogplex slash list --json +```text +/help ``` -The JSON form is the best choice if you want to inspect command metadata or -build tooling on top of the slash registry. +Then search "Approval" to focus the drawer. -## Run a slash command from the shell +See [Concepts → Approvals](/cli/concepts/approvals). -Use exec mode for actual execution: +## Switch permission modes -```bash -mogplex exec "/status" -mogplex exec "/config list" -mogplex exec "/mcp" -mogplex exec "/skills list" +```text +/permissions auto +/permissions approval ``` -This is the current shell-safe path when you want one slash action without -opening the TUI. +`auto` runs everything without asking; `approval` (the default) gates anything that touches the workspace. The change applies on the next `/run` — no restart required. -## Project and user commands +See [Concepts → Permissions](/cli/concepts/permissions). -Mogplex also loads slash commands from markdown files in these locations: +## Check cost and usage -- project scope: `.agents/commands/` -- user scope: `~/.mogplex/commands/` +```text +/cost +``` + +Per-agent and per-run breakdown. Crossed thresholds also appear in the Priority alerts strip. -That lets you keep repo-specific slash commands alongside the codebase and keep -personal commands in your home directory. +## Export the run + +```text +/export +``` -The loader also supports config-driven aliasing, disabling, and extra user -directories through the `slash_commands` config section. +Opens the **Run Export** drawer. Pick a format (JSON, JSONL, Markdown) and scope. -## High-value built-ins +See [Reference → Export](/cli/reference/export). + +## Kill the run + +```text +/kill +``` + +Cancels the active run immediately. Agents are stopped; in-flight tool calls are interrupted. + +## Quit the cockpit + +```text +/quit +``` -Some built-ins are particularly useful day to day: +Or `/exit`, or double-tap `Ctrl+C` (single press is a soft-interrupt — see [Reference → Keybindings](/cli/reference/keybindings)). -- `/status` for model, usage, approval, and cwd -- `/compact` when the session is getting heavy -- `/config` for inspecting or setting config values -- `/mcp` for checking configured MCP servers -- `/logs` for recent session errors -- `/sandbox` for spawn, pause, resume, peek, and kill operations when a sandbox - manager is available +## Common pitfalls -## If a command is missing +- **Typing `/run` with no arguments** — sends an empty task; you'll get an inline composer error. +- **Forgetting that `/permissions` is per-spawn** — you set the mode now; it applies to the next `/run`. +- **Using `q` with a drawer open** — `q` only quits when no drawer is open. While a drawer is open it's reserved for the drawer. +- **Pressing Ctrl+C once and walking away** — that's a soft-interrupt, not a quit. Press it twice within 1500ms to exit. -Check these in order: +## See also -1. `mogplex slash list` to confirm the command exists in the current runtime -2. the repo-local `.agents/commands/` directory -3. your user-level `~/.mogplex/commands/` directory -4. whether the capability only exists as a top-level command or only as a slash - command in the current build +- [Commands](/cli/commands) — full slash command reference +- [Reference → Keybindings](/cli/reference/keybindings) +- [Reference → Drawers](/cli/reference/drawers) diff --git a/content/docs/cli/index.mdx b/content/docs/cli/index.mdx index 640cf92..a9a3ff3 100644 --- a/content/docs/cli/index.mdx +++ b/content/docs/cli/index.mdx @@ -1,129 +1,74 @@ --- title: Overview -description: Use the Mogplex CLI for interactive terminal sessions, one-off exec runs, slash commands, and repo-local instructions. +description: Mogplex CLI is a terminal-native command center for supervising AI coding runs — agents, runs, MCP, memory, diffs, approvals, cost, and model routing on one screen. --- -The Mogplex CLI (`mogplex`) is the local runtime for Mogplex. +The Mogplex CLI (`mogplex`) is a terminal-native command center for supervising AI coding runs. -Use it for interactive terminal sessions, one-off `exec` runs, slash-command -workflows, local MCP configuration, and repo-scoped conventions like -`AGENTS.md`, optional `agent.json`, and `.agents/commands/`. +It is not a log viewer. It is the operator cockpit for everything happening on a run: the agents working on it, the timeline of events, the MCP servers in use, the memory being read and written, the diffs being produced, the tool calls waiting for approval, and the cost and tokens being burned. + +``` +agents · runs · tools · MCP servers · context · memory +diffs · cost · tokens · model routing · approval gates · process control +``` - + + + - + -## Start here when the repo on disk is the source of truth +## Where the CLI fits + +- **Web app** is the shared control plane: GitHub coverage, repo setup, reusable agents, hosted runs, routing, settings. +- **CLI** is the persistent terminal cockpit you sit in front of while a run is happening — start it, watch it, steer it, approve it, kill it. -The CLI is the best Mogplex surface when: +The CLI consumes structured events from the Mogplex core and sends commands back. It does not spawn Claude Code or Codex directly; it observes and controls runs that core orchestrates. -- the repo is already checked out locally -- you want work to happen in the terminal instead of through GitHub events -- you need repo-local instructions, slash commands, or shell-friendly one-off - runs +## What the CLI shows -The web app still matters for shared account state, but the CLI is the faster -tool for actual repo-in-place execution. +The screen is split into panels you can focus and drawers you can open: -## Choose the right CLI mode +- **Header** — repo, branch, model, mode, run status, dirty flag, permission mode, transport health +- **Agents** — every agent on the active run with status, model, current action +- **Timeline** — structured events streaming in +- **Context & Memory** — what's loaded, what's been written +- **MCP strip** — which MCP servers are ready +- **Command input** — slash commands and composer +- **Priority alerts** — things you should not miss -- `mogplex` launches the interactive session. Use this when you want back and - forth, slash commands, model switching, and a persistent local workflow. -- `mogplex exec ""` runs one non-interactive task and exits. Use this - for scripts, wrappers, and quick one-off work. -- `mogplex ""` is a shorthand for a one-off non-interactive run. -- `mogplex slash list` shows the slash-command registry available in the - current environment. -- `mogplex exec "/status"` or another slash line executes a slash command - without opening the full TUI. +Drawers cover the deep views: diffs, approvals, MCP detail, memory, agent detail, model picker, cost, run export, and a command palette for everything else. -The important distinction is that `mogplex slash list` is for discovery. -Actual slash execution from the shell goes through exec mode. +See [Reference → Panels](/cli/reference/panels) and [Reference → Drawers](/cli/reference/drawers). ## What the CLI is best at -- repo-in-place work from your terminal -- one-off review or edit tasks without opening the browser -- local slash-command workflows -- reusing models, MCP definitions, and tokens synced from your Mogplex account - -## What the CLI loads from your machine and repo - -These files explain most CLI behavior: - -- `~/.mogplex/auth.json` stores browser login or provider credentials. -- `~/.mogplex/config.toml` stores CLI configuration and profiles. -- `./.mogplex/config.toml` stores project-level config overrides inside a repo. -- `~/.mogplex/logs/` stores structured session logs. -- `AGENTS.md` teaches Mogplex how to work inside a specific repo. -- `.agents/commands/` adds repo-scoped slash commands. -- `~/.mogplex/commands/` adds user-scoped slash commands across repos. -- `agent.json` is an optional project-level config file the interactive CLI can - scaffold on first run in a repo. - -That list is worth understanding because “why is Mogplex behaving like this?” -usually comes down to one of those local files or an environment variable. - -## The shortest reliable setup - -1. Install the binary with [Installation](/cli/installation). -2. Run `mogplex`. -3. Authenticate either through your Mogplex account or a direct provider key. -4. Run a first task in the repo. -5. Inspect the slash registry with `mogplex slash list`. - -If you want shared configuration from the hosted product, connect the account in -the [web app](/web/settings) first so the CLI can reuse synced models and MCP -definitions. - -## Web app vs CLI - -The cleanest setup is usually: - -1. configure GitHub, models, API keys, and shared MCP servers in the - [web app](/web/settings) -2. do local repo work in the CLI -3. inspect hosted runs and cost in [Observability](/web/observability) - -That split keeps shared account state in one place and local execution in the -tool that is best at working inside a repo. - -## What a healthy CLI setup looks like - -- `mogplex` opens cleanly -- `mogplex exec "..."` works without special ceremony -- `mogplex slash list` shows the registry you expect -- repo-local instructions actually change behavior inside the repo -- shared hosted state appears only when you intended to use account-backed login - -## Common “where do I start?” questions - -- "Should I start with `mogplex` or `mogplex exec`?" - Start with `mogplex` for back-and-forth work and `mogplex exec` for one task - plus an exit code. -- "How do repo-specific conventions get loaded?" - Through `AGENTS.md`, `.agents/commands/`, optional `agent.json`, and your - local config. -- "Where do I change defaults, profiles, or per-run safety controls?" - In [Configuration and Flags](/cli/guides/configuration-and-flags). -- "Why does the CLI behave differently across shells?" - Environment variables beat stored auth, and repo-local instruction files can - change the assembled prompt. -- "Where should I configure shared models and MCP servers?" - In the [web app settings](/web/settings) if you want account-backed sync, or - locally in CLI config if you want shell-only behavior. +- Watching a run end-to-end without leaving the terminal. +- Approving or rejecting tool calls as they happen. +- Switching models, pausing, resuming, killing, exporting a run. +- Attaching to an in-flight run that started somewhere else (`--attach `). + +## Files the CLI reads + +- `~/.mogplex/auth.json` — Mogplex token and provider credentials. +- `~/.mogplex/permissions.json` — global permission mode and rules. +- `~/.mogplex/projects//permissions.json` — project-level overrides. +- `~/.mogplex/logs/` — structured session logs (secrets redacted). + +## Slash commands at a glance + +`/run `, `/pause`, `/resume`, `/kill`, `/agents`, `/mcp`, `/diff`, `/memory`, `/model`, `/cost`, `/export`, `/help`, `/clear`, `/quit` (alias `/exit`). + +Full reference: [Slash commands](/cli/commands). ## Read next -- [Quickstart](/cli/quickstart) for the first working session -- [Authentication](/cli/guides/authentication) for credential precedence -- [Configuration and Flags](/cli/guides/configuration-and-flags) for config - files, profiles, and per-run overrides -- [Exec Mode](/cli/guides/exec-mode) for one-off tasks -- [Slash Commands](/cli/guides/slash-commands) for the local control surface -- [Project Commands](/cli/guides/project-commands) for repo-local instructions, - slash files, and `/init` +- [Installation](/cli/installation) +- [Quickstart](/cli/quickstart) +- [Concepts → Architecture](/cli/concepts/architecture) +- [Concepts → Permissions](/cli/concepts/permissions) +- [Concepts → Attach](/cli/concepts/attach) diff --git a/content/docs/cli/installation.mdx b/content/docs/cli/installation.mdx index e617493..0039868 100644 --- a/content/docs/cli/installation.mdx +++ b/content/docs/cli/installation.mdx @@ -6,11 +6,7 @@ description: Install the Mogplex CLI on macOS, Linux, or Windows and verify that import { Tabs, Tab } from 'fumadocs-ui/components/tabs'; import { Callout } from 'fumadocs-ui/components/callout'; -Use the hosted installer to download the current release binary for your -platform. No Node.js runtime is required for this path. - -The public URLs under `www.mogplex.com` redirect to the canonical installer -host at `install.mogplex.com`, so either path is expected. +Use the hosted installer to download the current release for your platform. No Node.js runtime is required. ## Install @@ -38,52 +34,35 @@ iwr -useb https://www.mogplex.com/install.ps1 | iex ## What the installer changes -The hosted installer downloads the current release archive, extracts the -`mogplex` binary, and installs it into the Mogplex home bin directory by -default: +The installer downloads the current release archive, extracts the `mogplex` binary, and installs it into the Mogplex home bin directory: - macOS and Linux: `~/.mogplex/bin/mogplex` -- Windows: `%USERPROFILE%\\.mogplex\\bin\\mogplex.exe` - -After that, it tries to make `mogplex` runnable immediately: +- Windows: `%USERPROFILE%\.mogplex\bin\mogplex.exe` -- on macOS and Linux it first tries to link `mogplex` into a writable directory - that is already on your `PATH` -- if that is not possible, it falls back to updating your shell profile or - printing the export command you need -- on Windows it updates the user `PATH` when needed for future PowerShell - sessions +It then tries to make `mogplex` runnable immediately: -If you want to install somewhere else, set `MOGPLEX_INSTALL_DIR` before running -the installer. +- on macOS and Linux it first tries to link `mogplex` into a writable directory already on your `PATH` +- if that is not possible, it updates your shell profile or prints the export command +- on Windows it updates the user `PATH` for future PowerShell sessions -## Advanced installer options +If you want a different install location, set `MOGPLEX_INSTALL_DIR` before running the installer. -The installer also supports a small set of environment variables: +## Installer environment variables -- `MOGPLEX_INSTALL_DIR` - Override the install location. -- `MOGPLEX_VERSION` - Pin the installer to a specific release instead of the latest one. -- `MOGPLEX_BASE_URL` - Override the manifest host. The installer requires this to use HTTPS. +- `MOGPLEX_INSTALL_DIR` — override the install location. +- `MOGPLEX_VERSION` — pin to a specific release instead of the latest. +- `MOGPLEX_BASE_URL` — override the manifest host (must be HTTPS). -If you only want a custom install directory, you do not need to pin a version. -Add `MOGPLEX_VERSION` only when you intentionally want a fixed release. - -Example: +Examples: ```bash MOGPLEX_INSTALL_DIR="$HOME/.local/bin" \ -curl -fsSL https://www.mogplex.com/install.sh | sh + curl -fsSL https://www.mogplex.com/install.sh | sh ``` -Version pinning still works when you need it: - ```bash -# Example using the current release; replace 0.1.14 if you want a different pin. -MOGPLEX_VERSION=0.1.14 \ -curl -fsSL https://www.mogplex.com/install.sh | sh +MOGPLEX_VERSION=0.2.0 \ + curl -fsSL https://www.mogplex.com/install.sh | sh ``` ## Verify the install @@ -92,68 +71,37 @@ curl -fsSL https://www.mogplex.com/install.sh | sh mogplex --version ``` -If the binary is on your `PATH`, you should see the installed version string. -The installer tries to make `mogplex` available immediately by linking it into -a writable `PATH` directory or by updating your shell profile. - -The installer also ends by printing: - -```text -run: mogplex -``` - -That is the intended next step. A successful install is not just "the script -finished"; it is "the current shell can run `mogplex`." - -If your current shell still does not see it yet, run: +If your current shell still does not see it, run: ```bash rehash -# or open a fresh login shell +# or exec zsh -l ``` -On macOS and Linux, the installer requires `curl` or `wget` for download, plus -an archive extractor that matches the published asset format: `tar` for -`.tar.gz`, or `unzip` or `ditto` for `.zip`. - -## First run after install +## First run ```bash mogplex ``` -If you are not authenticated yet, Mogplex prompts you to either: - -- sign in with your Mogplex account in the browser -- store a direct provider API key locally +The first launch opens the in-app login screen. Sign in with your Mogplex account or store a provider key locally — Mogplex never requires environment variables for normal use. For the full first-run flow, continue with [Quickstart](/cli/quickstart). ## Upgrade -Re-run the installer. It detects an existing installation and replaces the -binary in place. +Re-run the installer. It detects the existing install and replaces the binary in place. ## Troubleshooting -- `mogplex: command not found`: the install succeeded but your current shell has - not picked up the updated `PATH` yet. -- The installer downloads but fails before extraction: confirm the machine has - an extractor for the published archive format (`tar` for `.tar.gz`, or - `unzip` or `ditto` for `.zip`). -- You pinned `MOGPLEX_BASE_URL` and the script exits immediately: the installer - rejects non-HTTPS hosts. -- Browser login works, but the CLI still has no model access: check the hosted - account in [Web Settings](/web/settings) and confirm the account has a usable - provider key or gateway key. -- You want a shell-managed setup instead: skip stored provider login and use - env vars such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. +- `mogplex: command not found` — the install succeeded but your shell has not picked up the updated `PATH`. Rehash or open a new shell. +- The installer downloads but fails before extraction — confirm your machine has the right extractor (`tar` for `.tar.gz`, `unzip` or `ditto` for `.zip`). +- You pinned `MOGPLEX_BASE_URL` and the script exits immediately — the installer rejects non-HTTPS hosts. +- Login succeeds but prompts fail — your account probably lacks model access. Add a provider key in [Web Settings](/web/settings). ## Uninstall -Delete the `mogplex` binary from the location the installer reported. Your -session data in `~/.mogplex/` is left untouched. +Delete the `mogplex` binary from the location the installer reported. Local state in `~/.mogplex/` is left untouched. -Remove that directory too if you want to clear config, auth, logs, slash -commands, and other local state. +Remove that directory too if you want to clear config, auth, logs, permissions, and other local state. diff --git a/content/docs/cli/meta.json b/content/docs/cli/meta.json index b158d8c..9eab485 100644 --- a/content/docs/cli/meta.json +++ b/content/docs/cli/meta.json @@ -1,4 +1,4 @@ { "title": "CLI", - "pages": ["index", "installation", "quickstart", "commands", "guides", "skills"] + "pages": ["index", "installation", "quickstart", "concepts", "reference", "commands", "guides", "skills"] } diff --git a/content/docs/cli/quickstart.mdx b/content/docs/cli/quickstart.mdx index 2e45369..566a4e4 100644 --- a/content/docs/cli/quickstart.mdx +++ b/content/docs/cli/quickstart.mdx @@ -1,185 +1,97 @@ --- title: Quickstart -description: Install the CLI, choose an auth path, run a first task, and confirm the current Mogplex CLI surface is working. +description: Install, sign in, start a run, and confirm the CLI cockpit is working end-to-end. --- -This page is for the fastest credible proof that the CLI is working. - -The shortest useful loop is: +The shortest useful loop: 1. install the binary 2. start `mogplex` -3. choose an auth path -4. run one task -5. confirm the slash and repo-local surfaces behave the way you expect +3. sign in (in-app) +4. start a run with `/run` +5. watch agents and timeline; approve or kill as needed ## 1. Install -See [Installation](/cli/installation) for platform-specific commands. +See [Installation](/cli/installation). -## 2. Start Mogplex +## 2. Start the cockpit ```bash mogplex ``` -If you are not authenticated yet and you are in a normal interactive terminal, -Mogplex prompts you to choose one of these exact startup paths: - -- **Sign in with Mogplex** to open the browser flow and reuse your account-backed - model access, synced model catalog, and synced MCP definitions -- **Use an API key** to store a provider key locally for direct CLI use - -If you choose **Use an API key**, the current startup picker can store keys for: - -- Anthropic -- OpenAI -- Google AI -- Vercel AI Gateway -- Groq -- Mistral -- DeepSeek -- xAI -- Cohere - -Stored credentials live under `~/.mogplex/auth.json`. - -Success at this step means the CLI reaches the prompt and does not bounce you -back out with an auth error. - -The practical choice is: - -- choose **Sign in with Mogplex** when you want the CLI to inherit hosted state - from the web app -- choose **Use an API key** when this machine should behave independently of the - hosted account - -## 3. Alternative: use an environment variable - -If you prefer shell-managed credentials, direct provider env vars still work and -take precedence over stored auth: - -```bash -export ANTHROPIC_API_KEY=sk-ant-... -# or -export OPENAI_API_KEY=sk-... -mogplex -``` - -That means a shell export can temporarily override whichever provider you -previously stored through Mogplex login. - -This is useful for CI, short-lived shells, or temporary provider switches, but -it also explains why a shell can behave differently from what -`mogplex login status` seems to imply. - -Inside a session, the common entry points are: - -- `/help` to list in-session commands -- `/status` to inspect model, usage, approval mode, and cwd -- `/model` to switch models -- `/compact` to summarize and continue with a smaller context window - -For the full auth resolution order, see [Authentication](/cli/guides/authentication). +If you are not authenticated, the in-app login screen appears. Pick one: -If you want to inspect what Mogplex has already stored locally, run: +- **Sign in with Mogplex** — opens a browser for account-backed login. Recommended; reuses synced model catalog and remote MCP definitions. +- **Use a provider API key** — store an Anthropic, OpenAI, Google, Groq, Mistral, DeepSeek, xAI, Cohere, or Vercel AI Gateway key locally. -```bash -mogplex login status -``` +Stored credentials live in `~/.mogplex/auth.json` (file mode `0600`). -## 4. Run one real task + + The CLI ships to end users — auth and config are in-app. Environment + variables exist as escape hatches only. See + [Configuration and Flags](/cli/guides/configuration-and-flags). + -If you want a live session, stay inside `mogplex` and ask for work directly. +## 3. Start a run -If you want a one-shot result with normal shell exit behavior, use exec mode: +In the composer: -```bash -mogplex exec "review the staged diff for regressions" +```text +/run review the staged diff for regressions ``` -Bare prompts also route to non-interactive exec mode: - -```bash -mogplex "summarize this repository" -``` +The Agents panel populates as core spawns workers. The Timeline streams structured events. The Header shows model, mode, run status, and transport health. -Use `mogplex exec` when you want the intent to be explicit in scripts, -automation, or shell history. +## 4. Drive the run -A good first success check is a repo-local prompt such as: +| Action | Command | +| --- | --- | +| Pause / resume | `/pause` then `/resume` | +| Kill the run | `/kill` | +| Switch models | `/model` (opens picker drawer) | +| Open the diff | `/diff` | +| See cost so far | `/cost` | +| Open MCP detail | `/mcp` | +| Inspect memory | `/memory` | +| Export the run | `/export` | +| List slash commands | `/help` | +| Quit | `/quit` (alias `/exit`) | -```bash -mogplex exec "summarize this repository and point out the likely entrypoints" -``` +Full reference: [Commands](/cli/commands). -If that works, you know auth, model access, and the non-interactive path are -all alive. +## 5. Approvals -## 5. Inspect the slash surface +If the active permission mode is `approval` (the default), tool calls that touch the workspace pause and surface in the Approval drawer. Approve or reject inline. See [Concepts → Approvals](/cli/concepts/approvals) and [Concepts → Permissions](/cli/concepts/permissions). -```bash -mogplex slash list -``` +## 6. Attach to an in-flight run -That shows the built-in in-session commands plus any project or user commands -loaded from `.agents/commands/` and `~/.mogplex/commands/`. - -If you want to execute a slash command from the shell instead of only listing -it, go through exec mode: +If a run was started somewhere else (web app, CI, another shell), you can pull up its cockpit with: ```bash -mogplex exec "/status" +mogplex --attach ``` -That is the right split: - -- `mogplex slash list` to discover what exists -- `mogplex exec "/..."` to execute a slash command non-interactively - -## 6. Make Mogplex repo-aware - -Inside a repo, the next upgrade is to add repo-local instructions and commands: - -- `AGENTS.md` for stable repo guidance -- `.agents/commands/` for repo-scoped slash commands -- `/init` inside a live session to scaffold the basics quickly -- optional `agent.json` when you want project-level config beyond markdown - instructions +See [Concepts → Attach](/cli/concepts/attach). -See [Project Commands](/cli/guides/project-commands) for the full pattern. +## What "working" looks like -## 7. Know what "working" looks like +- `mogplex` opens cleanly to the cockpit (or to the login screen on first run). +- Header shows `transport: nominal` once core is connected. +- `/run ` produces agents in the Agents panel and events in the Timeline. +- Approvals appear in the Approval drawer when the run touches the workspace. +- Ctrl+C does **not** quit — it logs a soft-interrupt. Press it twice within 1500ms (or type `/quit`) to exit. -By this point, a healthy setup looks like: - -- `mogplex` opens cleanly -- `mogplex login status` matches the auth mode you chose -- `mogplex exec "..."` returns a normal result -- `mogplex slash list` shows the commands you expect -- repo-local instructions affect behavior once you add them - -If you cannot say yes to those, the problem is usually one of three things: +## Common first-run issues -- auth source confusion between env vars and stored login -- missing provider or hosted model access -- missing repo-local files such as `AGENTS.md` or `.agents/commands/` +- Login succeeds but no models available — add a provider key in [Web Settings](/web/settings) (account-backed login inherits hosted model access). +- Header says `transport: offline` — core is unreachable. Check network and retry; the daemon transport surfaces a reconnect banner. +- A slash command "doesn't work" — check `/help` for the actual registry. -## Common first-run issues +## Read next -- `mogplex` opens, but you do not have usable models: if you used account login, - check [Web Settings](/web/settings) and add an API key or gateway key there. -- `mogplex login status` shows stored auth, but the current shell behaves - differently: an env var is probably overriding stored credentials. -- `mogplex exec` works, but a slash command is missing: confirm it appears in - `mogplex slash list` first. - -From there, the best next docs are: - -- [Authentication](/cli/guides/authentication) for credential precedence and - browser sign-in -- [Exec Mode](/cli/guides/exec-mode) for one-off tasks -- [Slash Commands](/cli/guides/slash-commands) for project-local command - discovery and `/init` -- [Project Commands](/cli/guides/project-commands) for repo-local instruction - files and command packs +- [Concepts → Architecture](/cli/concepts/architecture) for the mental model. +- [Concepts → Permissions](/cli/concepts/permissions) for `approval` vs `auto` modes. +- [Reference → Keybindings](/cli/reference/keybindings) for focus rotation and exit behavior. +- [Guides → Authentication](/cli/guides/authentication) for credential precedence. diff --git a/content/docs/cli/reference/cost-and-usage.mdx b/content/docs/cli/reference/cost-and-usage.mdx new file mode 100644 index 0000000..ec20b1a --- /dev/null +++ b/content/docs/cli/reference/cost-and-usage.mdx @@ -0,0 +1,50 @@ +--- +title: Cost & Usage +description: How the cockpit tracks tokens, cost, run limits, and surfaces warnings before you hit a wall. +--- + +The CLI tracks usage and cost as structured events flow in, then surfaces warnings when configured thresholds are crossed. + +## Where you see it + +| Surface | What it shows | +| --- | --- | +| **Header** | The active model and (when available) abbreviated usage | +| **Cost drawer** (`/cost`) | Per-agent and per-run breakdown: input/output tokens, cost, projection, model | +| **Priority alerts strip** | Warnings for crossed thresholds and approaching run limits | + +## What gets tracked + +- **Tokens** — input and output, per agent and per run. +- **Cost** — derived from token counts and the model's pricing where known. +- **Run limits** — configurable caps that, when crossed, can trigger a pause or warning depending on policy. + +Numbers come from structured `usage_*` events emitted by core. The CLI does not estimate or extrapolate beyond what it's told. + +## Thresholds and crossings + +Thresholds are evaluated against incoming usage events. Crossing a threshold is itself an event that: + +- updates the Cost drawer +- adds a row to the Priority alerts strip +- surfaces in the Timeline + +Typical thresholds: + +| Type | Example | +| --- | --- | +| Soft warning | Approaching 80% of a run's token budget | +| Hard warning | Crossed the configured cost ceiling | +| Run limit | Maximum number of agent steps reached | + +## What the cockpit does at a threshold + +By default, threshold crossings are informational — you see them, you decide. If your permission mode and rules are configured to gate on `run_command` or `change_model`, the agent's next action may also surface in the Approval drawer. + +The cockpit never silently kills a run for crossing a soft threshold. + +## Read next + +- [Drawers](/cli/reference/drawers) — the Cost drawer +- [Concepts → Approvals](/cli/concepts/approvals) — gating on actions +- [Export](/cli/reference/export) — capture cost data with the run artifact diff --git a/content/docs/cli/reference/drawers.mdx b/content/docs/cli/reference/drawers.mdx new file mode 100644 index 0000000..f85f0f5 --- /dev/null +++ b/content/docs/cli/reference/drawers.mdx @@ -0,0 +1,95 @@ +--- +title: Drawers +description: Every drawer in the cockpit — what it does, how to open it, when to use it. +--- + +Drawers are modal overlays for deep views. Each one registers with the drawer registry at module load, so the [Command Palette](#command-palette) can list every drawer the build ships. + +## Diff + +Shows the diff for a patch produced during a run. Opens with `/diff` or by selecting a patch event in the Timeline. + +What you can do: + +- step through hunks +- inspect the full file context +- approve / reject the patch (when permission mode requires it) + +## Approval + +The pending-approval queue. Each item shows action, target, risk level, and the requesting agent. See [Concepts → Approvals](/cli/concepts/approvals) for how items get here. + +What you can do: + +- approve or reject inline +- batch-approve obviously related items +- jump to the related Timeline event + +## MCP + +Per-server view of every configured MCP server and its capabilities. Open with `/mcp` or via the MCP strip. + +What you can do: + +- inspect available tools per server +- see why a server is `unavailable` or `degraded` +- follow links into [Web Settings](/web/settings) for shared MCP configuration + +## Memory + +Browse and manage memory entries. Open with `/memory`. + +What you can do: + +- read existing entries +- delete entries (gated by permission mode) +- see what was written during the active run + +The CLI never mutates memory directly — every write goes through core and may surface in the Approval queue. + +## Agent Detail + +Focused view of one agent. Open by selecting an agent card and pressing enter. + +What you can do: + +- read the agent's current plan and recent actions +- inspect tool calls in flight +- soft-interrupt the agent (`Ctrl+C` while focused) + +## Model Picker + +Switch the active run's model. Open with `/model`. + +What you can do: + +- pick from the synced model catalog (account-backed login) or local config +- preview pricing where available +- swap models mid-run (gated by permission mode if `change_model` is `ask`) + +## Cost + +Per-run cost and token usage with thresholds and projections. Open with `/cost`. See [Cost & Usage](/cli/reference/cost-and-usage) for thresholds and warnings. + +## Run Export + +Serialize the current run for sharing or archival. Open with `/export`. See [Export](/cli/reference/export) for formats. + +## Command Palette + +Fuzzy-find every action the cockpit exposes — slash commands, drawers, run controls, focus targets. Lists actions by category: + +| Category | Examples | +| --- | --- | +| `command` | `/run`, `/pause`, `/diff`, `/mcp` | +| `drawer` | Open MCP, Open Diff, Open Memory, Open Agent Detail, Open Model Picker, Open Cost, Open Run Export, Open Approval | +| `control` | Pause Run, Resume Run, Cancel Run, Export Run | +| `focus` | Focus Agents, Focus Timeline, Focus Composer | + +The Palette is the safety net when you don't remember a slash command name. + +## Read next + +- [Panels](/cli/reference/panels) +- [Commands](/cli/commands) — slash command reference +- [Concepts → Approvals](/cli/concepts/approvals) diff --git a/content/docs/cli/reference/export.mdx b/content/docs/cli/reference/export.mdx new file mode 100644 index 0000000..f261856 --- /dev/null +++ b/content/docs/cli/reference/export.mdx @@ -0,0 +1,49 @@ +--- +title: Export +description: Serialize a run for sharing or archival via `/export` and the Run Export drawer. +--- + +Use `/export` to capture the active (or attached) run as a portable artifact. Opens the **Run Export** drawer with format and scope choices. + +## What gets included + +- Run metadata: id, repo, branch, model, mode, start/end timestamps. +- Agents: roles, models, final status. +- Timeline: structured events (tool calls, patches, approvals, errors, lifecycle). +- Cost & usage: token counts and cost per agent. +- Approvals: every queued item with its decision. +- Memory writes performed during the run. + +The export is built from the same store the cockpit renders from, so what you see in the panels is what lands in the artifact. + +## Formats + +The Run Export drawer offers a small set of serializers: + +| Format | Use when | +| --- | --- | +| **JSON** | You want the structured data for tooling. One object per run. | +| **JSONL** | You want streaming events for replay or analysis. | +| **Markdown** | You want a human-readable summary suitable for PRs or post-mortems. | + +Pick a scope — full run, timeline only, approvals only, etc. — before exporting. + +## Where the file lands + +By default the artifact is written under the active run's local export directory. The drawer prints the resolved path on completion. + +## When to export + +- **Post-mortem** — capture a failed run for review. +- **Sharing** — send a teammate the markdown summary or the JSON for tooling. +- **Audit** — keep a record of every approval decision and tool call. +- **Resume context** — feed a JSONL export back into another tool that consumes Mogplex events. + +## Detach without exporting + +Quitting (or killing the CLI process) does not auto-export. If you need the artifact, run `/export` first. + +## Read next + +- [Concepts → Attach](/cli/concepts/attach) — exporting works on attached runs too +- [Drawers](/cli/reference/drawers) — the Run Export drawer diff --git a/content/docs/cli/reference/index.mdx b/content/docs/cli/reference/index.mdx new file mode 100644 index 0000000..0489353 --- /dev/null +++ b/content/docs/cli/reference/index.mdx @@ -0,0 +1,16 @@ +--- +title: Overview +description: Reference pages for the CLI cockpit — panels, drawers, keybindings, cost & usage, and export. +--- + +Use these pages when you know what you're looking at and need the specifics. + + + + + + + + + +For slash commands, see [Commands](/cli/commands). diff --git a/content/docs/cli/reference/keybindings.mdx b/content/docs/cli/reference/keybindings.mdx new file mode 100644 index 0000000..2e9d9cd --- /dev/null +++ b/content/docs/cli/reference/keybindings.mdx @@ -0,0 +1,79 @@ +--- +title: Keybindings +description: Focus rotation, exit behavior, drawer keys, and the Ctrl+C soft-interrupt. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +## Exit + +| Action | What happens | +| --- | --- | +| **`Ctrl+C` (single press)** | Soft-interrupt — logs `[soft-interrupt]` to stderr. **Does not quit.** | +| **`Ctrl+C` twice within 1500ms** | Clean exit. Restores terminal state, stops the dispatcher, destroys the renderer. | +| **`q`** | Clean exit, but **only when no drawer or help overlay is open**. While a drawer is open, `q` is reserved for the drawer. | +| **`/quit` (alias `/exit`)** | Clean exit from the composer. | + + + The double-tap-to-exit rule prevents accidental quit-on-Ctrl+C while a long + run is in flight. Hitting Ctrl+C once is the conventional "soft cancel" — + hitting it twice means you really want out. + + +## Focus + +| Action | Key | +| --- | --- | +| Focus the Agents panel | `focus:agents` (via Command Palette or palette shortcut) | +| Focus the Timeline | `focus:timeline` | +| Focus the Composer | `focus:composer` | + +The exact shortcut keys are surfaced in the Command Palette (`/help` to open the palette and search "Focus"). + +## Drawer keys + +When a drawer is open: + +| Key | Action | +| --- | --- | +| `Esc` | Close the drawer | +| `↑` / `↓` | Move selection within the drawer | +| `Enter` | Activate the focused item (varies per drawer) | +| `a` | Approve (Approval drawer) | +| `r` | Reject (Approval drawer) | +| `q` | (reserved by the drawer; does not quit the app) | + +Each drawer can register its own additional keymap. See the per-drawer entries in [Reference → Drawers](/cli/reference/drawers). + +## Composer + +| Key | Action | +| --- | --- | +| `Enter` | Send | +| `Shift+Enter` | Newline | +| `Tab` | Autocomplete slash command | +| `↑` / `↓` | Browse composer history | + +## Command Palette + +| Key | Action | +| --- | --- | +| Open palette | Listed in `/help`, also via the `Open Command Palette` action | +| Type | Fuzzy-search across commands, drawers, controls, focus targets | +| `Enter` | Run the selected action | + +## Signals + +| Signal | Behavior | +| --- | --- | +| `SIGINT` (Ctrl+C) | Soft-interrupt then double-tap to exit (see above) | +| `SIGTERM` | Clean exit | +| crash / unhandled exception | Terminal state is restored on the way out | + +The terminal is always restored on exit — cursor visible, raw mode off — even if the renderer crashed. + +## Read next + +- [Panels](/cli/reference/panels) +- [Drawers](/cli/reference/drawers) +- [Commands](/cli/commands) diff --git a/content/docs/cli/reference/meta.json b/content/docs/cli/reference/meta.json new file mode 100644 index 0000000..e42c8ff --- /dev/null +++ b/content/docs/cli/reference/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Reference", + "pages": ["index", "panels", "drawers", "keybindings", "cost-and-usage", "export"] +} diff --git a/content/docs/cli/reference/panels.mdx b/content/docs/cli/reference/panels.mdx new file mode 100644 index 0000000..46b5ed4 --- /dev/null +++ b/content/docs/cli/reference/panels.mdx @@ -0,0 +1,82 @@ +--- +title: Panels +description: Every panel in the cockpit — what it shows, when it updates, what it doesn't do. +--- + +The CLI lays out seven panels. Each one subscribes to the central store via selectors, so they can never disagree. + +## Header + +The status bar across the top. + +| Field | Meaning | +| --- | --- | +| **repo / branch** | The active repository and branch | +| **model** | The model the active run is using | +| **mode** | Run mode (idle, planning, executing, etc.) | +| **run status** | ready, running, paused, completed, failed, killed | +| **dirty** | Whether the working tree has uncommitted changes | +| **perms** | Active permission mode (`approval` or `auto`) | +| **transport** | Connection health: `nominal` (connected), `connecting`, `reconnect`, `degraded`, `offline` | + +The transport label uses aerospace-ops phrasing — `nominal` means everything is connected and healthy. + +## Agents + +The left rail. Lists every agent on the active run as a card with: + +- agent number +- name and role (architect, builder, reviewer, tester, researcher) +- model +- status (starting, planning, thinking, calling_tool, editing, reviewing, testing, blocked, waiting_for_approval, paused, completed, failed, killed) +- current action (truncated to fit) +- an animated activity frame for actively-working agents + +Below the agent cards, a **system status** block shows transport health, the active model, and MCP server counts. + +Press the focus key (see [Keybindings](/cli/reference/keybindings)) to navigate; selecting an agent and pressing enter opens the **Agent Detail** drawer. + +## Timeline + +The center panel. Streams structured events as they happen — tool calls, patches, approvals, errors, model routing decisions, run lifecycle. Events are typed (validated by Zod schemas in `contracts/`), not parsed stdout. + +Use it to: + +- watch what an agent is actually doing +- find the event that triggered an approval or an error +- scroll back through the run's history + +## Context & Memory + +What's loaded in context and what's been written to memory. Subscribes to memory events from core. Open the **Memory** drawer (`/memory`) to manage entries. + +## MCP strip + +A compact status row of configured MCP servers and their readiness. Open the **MCP** drawer (`/mcp`) for the full per-server view. + +## Command input + +The composer at the bottom. Type: + +- a freeform task — sends to the active agent +- `/` — runs a slash command (see [Commands](/cli/commands)) +- partial slash — autocomplete candidates appear above the line + +Unknown slash commands surface as inline composer errors so you don't accidentally send them as prompts. + +## Priority alerts + +A strip that surfaces things you should not miss even if a drawer is closed: + +- high-risk pending approvals +- usage / cost threshold crossings +- run limits about to be hit +- transport degradation or reconnect events + +Alerts auto-dismiss when the underlying condition clears. + +## Read next + +- [Drawers](/cli/reference/drawers) +- [Keybindings](/cli/reference/keybindings) +- [Concepts → Architecture](/cli/concepts/architecture) diff --git a/content/docs/cli/skills/index.mdx b/content/docs/cli/skills/index.mdx index 69aa38a..1482b66 100644 --- a/content/docs/cli/skills/index.mdx +++ b/content/docs/cli/skills/index.mdx @@ -1,15 +1,21 @@ --- title: Skills -description: Agent Skills that teach external agents (Claude Code, Claude Agent SDK, Cursor, opencode) how to drive a user's Mogplex workspace through the `mogplex` CLI — a drop-in substitute when a Mogplex MCP server is not available. +description: Agent Skills that teach external agents (Claude Code, Claude Agent SDK, Cursor, opencode) how to guide a user through the Mogplex CLI cockpit. --- -Mogplex ships a set of [Anthropic Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) that let any skill-aware agent operate a user's Mogplex workspace through the CLI, without MCP, and without asking the user to paste tokens into a JSON config. +Mogplex ships a set of [Anthropic Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) that teach a skill-aware agent how to help users drive the Mogplex CLI. -This page is the reference for the skill set itself. For the decision between Skills and the upcoming [MCP server](/extend/mcp-server), see [Extend → Skills vs MCP](/extend/skills). + + The current CLI is interactive-only — there is no headless `exec` surface + for an agent to call. These skills are **guidance skills**: they teach an + agent to recommend the right slash command, walk a user through the login + screen, and help author repo-local config (`AGENTS.md`, + `permissions.json`). Agents do not drive the cockpit directly. + ## Source of truth -The canonical skill files live in the docs repo at `skills//SKILL.md` and follow the standard Anthropic skill format (YAML frontmatter with `name` and `description`, markdown body, file named `SKILL.md` in a directory that matches the skill name). +The canonical skill files live at `skills//SKILL.md` in [`webrenew/mogplex-docs`](https://github.com/webrenew/mogplex-docs). The pages under this section mirror those files. ## Skills @@ -17,28 +23,23 @@ The canonical skill files live in the docs repo at `skills//SKILL.md` and - ## Install -The skill files are hosted in [`webrenew/mogplex-docs`](https://github.com/webrenew/mogplex-docs) under `skills/`. Pick one fetch method (this sets a `SKILLS` path variable), then copy into your agent host. +The skill files are hosted at [`webrenew/mogplex-docs`](https://github.com/webrenew/mogplex-docs) under `skills/`. Pick one fetch method, then copy into your agent host. ### Claude Code @@ -48,19 +49,17 @@ git clone https://github.com/webrenew/mogplex-docs.git SKILLS=mogplex-docs/skills # Option B — sparse download of just the skills/ tree -# degit copies the *contents* of skills/ into mogplex-skills/, -# so mogplex-skills is the skills tree (no nested skills/ dir). npx -y degit webrenew/mogplex-docs/skills mogplex-skills SKILLS=mogplex-skills ``` -Then, in the same shell: +Then: ```bash # Global mkdir -p ~/.claude/skills && cp -R "$SKILLS"/* ~/.claude/skills/ -# Or per-project (run from your project root) +# Or per-project mkdir -p .claude/skills && cp -R "$SKILLS"/* .claude/skills/ ``` @@ -72,7 +71,7 @@ Skills picked up automatically via `settingSources: ["user", "project"]`: import { query } from "@anthropic-ai/claude-agent-sdk"; const response = query({ - prompt: "Run /status against my Mogplex workspace", + prompt: "How do I switch models in Mogplex?", options: { settingSources: ["user", "project"] }, }); ``` @@ -83,7 +82,7 @@ Copy the body of each `SKILL.md` into the host's project-rules or system-prompt- ## Design principles -- **CLI-first.** Skills assume `mogplex` is on `PATH`. They never instruct the agent to read or write credential files directly. -- **Auth preflight.** Every action-performing skill tells the agent to run `mogplex login status` first. -- **Structured output.** Skills prefer `--json` / `--jsonl` for anything the agent has to parse. -- **No silent writes.** Any command that mutates state is flagged so the agent asks the user before running it. +- **Guidance, not execution.** Skills tell the user what to do in the cockpit. They do not try to drive the TUI. +- **Auth handoff.** Auth lives in the cockpit's login screen. Skills recommend `/login` and explain env-var precedence. +- **Repo-local config is fair game.** Skills can help the user author `AGENTS.md` and `~/.mogplex/projects//permissions.json` — those are plain files. +- **No silent writes.** Anything that mutates user-owned state is recommended to the user, not done by the agent. diff --git a/content/docs/cli/skills/meta.json b/content/docs/cli/skills/meta.json index b1f6b5c..1cddb1e 100644 --- a/content/docs/cli/skills/meta.json +++ b/content/docs/cli/skills/meta.json @@ -1,4 +1,4 @@ { "title": "Skills", - "pages": ["index", "using-mogplex-cli", "mogplex-exec", "mogplex-slash", "mogplex-auth"] + "pages": ["index", "using-mogplex-cli", "mogplex-slash", "mogplex-auth"] } diff --git a/content/docs/cli/skills/mogplex-auth.mdx b/content/docs/cli/skills/mogplex-auth.mdx index bded211..799e431 100644 --- a/content/docs/cli/skills/mogplex-auth.mdx +++ b/content/docs/cli/skills/mogplex-auth.mdx @@ -1,26 +1,26 @@ --- title: mogplex-auth -description: Verifies or establishes Mogplex CLI authentication before running other Mogplex commands. +description: 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`](https://github.com/mogplex/mogplex-docs/blob/main/skills/mogplex-auth/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths). +This page mirrors the canonical `SKILL.md` at [`skills/mogplex-auth/SKILL.md`](https://github.com/webrenew/mogplex-docs/blob/main/skills/mogplex-auth/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths). ## Frontmatter ```yaml name: mogplex-auth -description: Verifies or establishes Mogplex CLI authentication before running other Mogplex commands. Use when `mogplex login status` shows no credential, a Mogplex command fails with an auth error, or the user asks to sign in, switch accounts, or inspect credential state. +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. ``` ## Body -Every action against Mogplex needs a credential. Run this skill first whenever another skill tells you to "handle auth" or when a 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 +## Resolution order -Mogplex picks credentials in a fixed 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. @@ -37,99 +37,91 @@ Mogplex picks credentials in a fixed order: | Cohere | `COHERE_API_KEY` | | Vercel | `VERCEL_API_TOKEN` | -2. **Stored credentials** in `~/.mogplex/auth.json`. -3. **No credentials** → interactive prompt (TUI) or a clear failure in non-interactive contexts. +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. -### Check current state +## 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. ```bash -mogplex login status +mogplex +# pick "Sign in with Mogplex" on the login screen ``` -Read the output, do not read the file. The command prints a safe summary and never reveals secret material. +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. -| `login status` says | What it means | -| --- | --- | -| `mogplex` credential present | Account-backed login is active (unless an env var overrides it). | -| a provider entry (e.g. `openai`) | Direct provider credential stored locally. | -| nothing stored | No disk credential — will fall back to env vars, else fail. | +Account-backed login unlocks synced model catalog, remote MCP server definitions, and hosted model access. -Then sanity-check env vars in the current process, never printing the full value: +### Alternative: store a provider key in-app -```bash -env | grep -E '^(MOGPLEX|ANTHROPIC|OPENAI|GOOGLE_GENERATIVE_AI|GROQ|MISTRAL|DEEPSEEK|XAI|COHERE|VERCEL)_' | sed 's/=.*/=/' -``` +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. -### Establish auth +### Alternative: provider env var -**Preferred: account-backed browser login.** The user runs this themselves: +For CI or ephemeral shells: ```bash -mogplex login +export OPENAI_API_KEY=sk-... +mogplex ``` -Do not attempt to drive the browser. Hand off to the user, wait for them to confirm, then re-check `mogplex login status`. +Do not write keys into shell rc files on the user's behalf. Suggest it; let them do it. -**Alternative: direct provider env var.** For CI or ephemeral shells: +## Sanity-check env vars (advisory) + +You can sanity-check which env vars are set without printing values: ```bash -export OPENAI_API_KEY=sk-... -mogplex exec "..." +env | grep -E '^(MOGPLEX|ANTHROPIC|OPENAI|GOOGLE_GENERATIVE_AI|GROQ|MISTRAL|DEEPSEEK|XAI|COHERE|VERCEL)_' | sed 's/=.*/=/' ``` -Do not write keys into shell rc files on the user's behalf. Suggest it; let them do it. +Never echo a raw key. -**Alternative: stored provider key.** Inside a live session, the user runs `/login ` and pastes the key into the TUI. You cannot do this for them. +## Troubleshooting -### Troubleshooting decision tree +| 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 [Web Settings](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). | -``` -auth error from a mogplex command - │ - ▼ -run `mogplex login status` - │ - ▼ -credential shown? ── no ──► is an env var set for any provider? - │ │ - │ yes ──► env var may be malformed; print a - │ │ redacted preview and ask user to verify - │ no ──► ask user to run `mogplex login` - │ - yes - │ - ▼ -does the session use that credential? - │ - no ──► an env var is overriding it; unset it or clear it from the - │ current shell, then retry - yes ──► account login succeeded but hosted account lacks model access; - direct user to Mogplex web settings to add a provider key +## Sign out + +```text +/logout # type in the composer ``` -### Signing out +Or, before attaching to a run: ```bash -# Inside a live session only: -/logout +mogplex --attach run_abc123 --logout ``` -- Env vars still win on the next session. -- The current process may still hold the old adapter; restart for certainty. -- Logging out of Mogplex clears hosted state — model catalog sync and remote MCP definitions vanish locally. +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 +## Hard rules -- Never read `~/.mogplex/auth.json` directly. +- 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 `mogplex login` would give them an account-backed token instead. +- 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](/cli/skills/using-mogplex-cli) - [Authentication guide](/cli/guides/authentication) +- [Configuration and Flags](/cli/guides/configuration-and-flags) diff --git a/content/docs/cli/skills/mogplex-exec.mdx b/content/docs/cli/skills/mogplex-exec.mdx deleted file mode 100644 index f18f449..0000000 --- a/content/docs/cli/skills/mogplex-exec.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: mogplex-exec -description: Runs a one-off, non-interactive Mogplex task from the shell and captures a final result with exit code. ---- - - -This page mirrors the canonical `SKILL.md` at [`skills/mogplex-exec/SKILL.md`](https://github.com/mogplex/mogplex-docs/blob/main/skills/mogplex-exec/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths). - - -## Frontmatter - -```yaml -name: mogplex-exec -description: Runs a one-off, non-interactive Mogplex task from the shell and captures a final result with exit code. Use when the agent needs to execute a single prompt against the user's Mogplex account, run a slash command without opening the TUI, or pipe a Mogplex result into another tool. -``` - -## Body - -`mogplex exec` runs a single task and exits. Use it whenever you need one result, not a conversation. - -### Preflight - -```bash -mogplex login status -``` - -If no credential is reported and no provider env var is set, stop and handle auth first (see [`mogplex-auth`](/cli/skills/mogplex-auth)). - -### Two equivalent entrypoints - -```bash -mogplex exec "review the staged diff for regressions" -mogplex "review the staged diff for regressions" -``` - -Prefer the explicit `exec` form in scripts, CI, and agent-written commands — it will never be mistaken for a subcommand name if Mogplex adds new top-level commands later. - -### Structured output - -```bash -mogplex exec --json "summarize this repository" -mogplex exec --jsonl "review the staged diff for correctness issues" -mogplex exec --output json "…" -mogplex exec --output jsonl "…" -``` - -- `--json` → single final object when the task completes. -- `--jsonl` → one JSON object per event, streamed as the task runs. - -Do not parse the default text output. It is tuned for humans and is not stable. - -### Slash commands in exec mode - -If the prompt starts with `/`, `exec` routes it through the slash registry: - -```bash -mogplex exec "/status" -mogplex exec "/mcp" -mogplex exec "/logs --lines=100" -mogplex exec "/skills list" -``` - -See [`mogplex-slash`](/cli/skills/mogplex-slash) for discovery. - -### Local image paths - -Exec understands local image paths embedded in the prompt and forwards them as structured image inputs. Pass absolute paths when available: - -```bash -mogplex exec "describe /Users/me/Downloads/shot.png" -``` - -### Exit codes - -`mogplex exec` exits with the engine's final exit code. Treat non-zero as failure and surface the stderr output to the user rather than retrying blindly. - -### When NOT to use exec - -- Multi-turn conversation → instruct the user to run `mogplex` interactively instead. -- Anything that requires TUI input (plan confirmation, model picker) → use a live session. -- Long-running background work → prefer a Mogplex sandbox or a Trigger.dev-style job; exec is for synchronous, bounded tasks. - -### Good patterns - -```bash -# Run and capture to a file for further processing -mogplex exec --json "list the skills configured in this workspace" > /tmp/skills.json - -# Pipe JSONL events into a consumer -mogplex exec --jsonl "refactor the auth module" | jq -c 'select(.type=="tool_result")' - -# CI: fail the job if the review found regressions -if ! mogplex exec --json "/review" > review.json; then - cat review.json >&2 - exit 1 -fi -``` - -### Common mistakes - -- Parsing text output. Always pass `--json` or `--jsonl` when the caller is a program. -- Using `exec` for conversational work. One prompt, one result. -- Forgetting `--help` is the source of truth: `mogplex exec --help` reflects the installed version exactly. - -## See also - -- [mogplex-slash](/cli/skills/mogplex-slash) -- [mogplex-auth](/cli/skills/mogplex-auth) -- [Exec mode guide](/cli/guides/exec-mode) diff --git a/content/docs/cli/skills/mogplex-slash.mdx b/content/docs/cli/skills/mogplex-slash.mdx index 65e4c94..46ffbf4 100644 --- a/content/docs/cli/skills/mogplex-slash.mdx +++ b/content/docs/cli/skills/mogplex-slash.mdx @@ -1,108 +1,87 @@ --- title: mogplex-slash -description: Discovers and runs Mogplex slash commands from the shell via `mogplex slash list` and `mogplex exec "/..."`. +description: Recommends the right Mogplex slash command for a user's intent and explains what each command does in the cockpit. --- -This page mirrors the canonical `SKILL.md` at [`skills/mogplex-slash/SKILL.md`](https://github.com/mogplex/mogplex-docs/blob/main/skills/mogplex-slash/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths). +This page mirrors the canonical `SKILL.md` at [`skills/mogplex-slash/SKILL.md`](https://github.com/webrenew/mogplex-docs/blob/main/skills/mogplex-slash/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths). ## Frontmatter ```yaml name: mogplex-slash -description: Discovers and runs Mogplex slash commands from the shell via `mogplex slash list` and `mogplex exec "/..."`. Use when the user asks for a slash command like /status, /mcp, /skills, /sandbox, or /logs, or when a project stores commands in `.agents/commands/` or `~/.mogplex/commands/`. +description: Recommends the right Mogplex slash command for a user's intent and explains what each command does in the cockpit composer. Use when the user asks how to start, pause, kill, attach, model-switch, approve, or export a Mogplex run. ``` ## Body -Slash commands are Mogplex's control surface — session control, local tooling, project scripts. They are NOT prompts sent to a model; they are registered actions. +The Mogplex CLI's command surface is **slash commands** in the cockpit composer. They run inside the interactive TUI — not from the shell. Use this skill to tell the user which slash command to type. -### Preflight +### Run control -```bash -mogplex login status -``` - -Most slash commands require auth. If unauthenticated, resolve that first (see [`mogplex-auth`](/cli/skills/mogplex-auth)). - -### Discover the registry - -Always inspect what actually exists in the current environment before depending on a command: +| Intent | Slash command | +| --- | --- | +| Start a new run | `/run ` | +| Pause the active run | `/pause` | +| Resume a paused run | `/resume` | +| Cancel the active run | `/kill` | -```bash -mogplex slash list --json -``` - -The registry includes three sources: +### Surface inspection (open a drawer) -1. **Built-ins** shipped with the CLI (`/status`, `/mcp`, `/skills`, `/sandbox`, `/logs`, `/model`, `/approvals`, `/compact`, `/clear`, `/init`, `/review`, `/config`, `/login`, `/logout`, `/quit`, `/help`). -2. **Project commands** from `.agents/commands/*.md` in the current repo. -3. **User commands** from `~/.mogplex/commands/*.md`. +| Intent | Slash command | +| --- | --- | +| List agents on the active run | `/agents` | +| Per-MCP-server status | `/mcp` | +| Browse memory | `/memory` | +| Inspect a patch | `/diff` | +| Tokens, cost, projection | `/cost` | -### Execute a slash command +### Cockpit control -Use `exec` — the `slash` top-level command is only for inspection: - -```bash -mogplex exec "/status" -mogplex exec "/mcp" -mogplex exec "/config list" -mogplex exec "/skills list" -mogplex exec "/logs --lines=100" -mogplex exec "/sandbox peek" -``` +| Intent | Slash command | +| --- | --- | +| Switch models mid-run | `/model` | +| Set permission mode | `/permissions ` | +| Show the resolved permission state | `/permissions` (no arg) | +| Serialize the run | `/export` | +| Open the command palette | `/help` | +| Clear the composer | `/clear` | +| Quit the cockpit | `/quit` (alias `/exit`) | -Pass `--json` when you need to parse the output: +### Auth -```bash -mogplex exec --json "/status" -mogplex exec --json "/skills list" -``` - -### High-value built-ins for agents - -| Command | Purpose | Safe to run without asking? | -| --- | --- | --- | -| `/status` | Model, usage, approval mode, cwd | yes, read-only | -| `/skills list` | Installed Mogplex skills | yes, read-only | -| `/mcp` | Configured MCP servers | yes, read-only | -| `/config list` | Current config values | yes, read-only | -| `/logs --lines=N` | Recent session errors | yes, logs are redacted | -| `/sandbox peek` | Inspect sandbox state | yes, read-only | -| `/config set …` | Mutate config | no, ask user first | -| `/sandbox kill` | Destroy sandbox state | no, ask user first | -| `/logout` | Remove stored credentials | no, ask user first | - -### Project-local slash commands - -When the user mentions a command you do not recognize (e.g. `/deploy-preview`), it is likely project-local: - -```bash -ls .agents/commands/ 2>/dev/null -ls ~/.mogplex/commands/ 2>/dev/null -``` +| Intent | Slash command | +| --- | --- | +| Open the in-app login flow | `/login` | +| Clear stored credentials | `/logout` | -Each `.md` file in those directories registers a slash command. Read the file to understand what it does before executing it. +### When the user says… -### If a command is missing +| User says | You recommend | +| --- | --- | +| "Run a task on this repo" | Open `mogplex` and type `/run ` | +| "Pull up that run from CI" | `mogplex --attach ` | +| "Switch to Sonnet" | Type `/model` in the composer | +| "Approve all pending tool calls" | Open the Approval drawer (use Command Palette via `/help` if not visible) and approve from there | +| "Run unattended for the next hour" | `/permissions auto` — flag the safety implications | +| "Save what just happened" | `/export` and pick Markdown for human-readable, JSON/JSONL for tooling | +| "Get out" | Double-tap Ctrl+C within 1500ms, or `/quit` | -Work through this checklist before telling the user a command does not exist: +### What you cannot do -1. `mogplex slash list --json` to confirm the registry in the current runtime. -2. Check `.agents/commands/` for a project-scoped override or addition. -3. Check `~/.mogplex/commands/` for a personal command. -4. The capability may exist only as a top-level command (e.g. `mogplex login`) rather than a slash command. Run `mogplex --help`. -5. The capability may be listed in `--help` but not yet implemented as a standalone subcommand. Try the slash form inside `exec "/..."`. +- Run a slash command from the shell. There is no `mogplex slash` subcommand; slash commands only execute inside the running cockpit. +- See which slash commands are available without launching the cockpit. The registry is built into the binary; `/help` inside the cockpit shows the live list. +- Drive the cockpit on the user's behalf. Tell them what to type. -### Common mistakes +### Safety -- Running `mogplex slash /status` (it does not execute slash commands). -- Assuming every `/` item you see in a doc is available in the user's build — always confirm with `slash list --json`. -- Running mutating slash commands without user confirmation. +- `/permissions auto` is the explicit user opt-in to "no questions asked." Recommend `/permissions approval` (the default) for normal use. +- `/kill` cancels the active run immediately and interrupts in-flight tool calls. Confirm before suggesting it on a long run. +- `/logout` clears stored credentials including hosted Mogplex state (synced model catalog, remote MCP). Confirm before suggesting. ## See also -- [mogplex-exec](/cli/skills/mogplex-exec) +- [using-mogplex-cli](/cli/skills/using-mogplex-cli) - [mogplex-auth](/cli/skills/mogplex-auth) -- [Slash commands guide](/cli/guides/slash-commands) +- [Commands](/cli/commands) diff --git a/content/docs/cli/skills/using-mogplex-cli.mdx b/content/docs/cli/skills/using-mogplex-cli.mdx index 59f6706..bcad985 100644 --- a/content/docs/cli/skills/using-mogplex-cli.mdx +++ b/content/docs/cli/skills/using-mogplex-cli.mdx @@ -1,51 +1,55 @@ --- title: using-mogplex-cli -description: Umbrella skill for driving a user's Mogplex workspace through the `mogplex` CLI when no Mogplex MCP server is available. +description: Umbrella skill for guiding a user through the Mogplex CLI cockpit when no Mogplex MCP server is available. --- -This page mirrors the canonical `SKILL.md` at [`skills/using-mogplex-cli/SKILL.md`](https://github.com/mogplex/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). +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). ## Frontmatter ```yaml name: using-mogplex-cli -description: Umbrella skill for driving a user's Mogplex workspace through the `mogplex` CLI when no Mogplex MCP server is available. Use when the user asks to run a Mogplex workspace action, execute a Mogplex slash command, or use Mogplex skills, agents, or memories from outside the Mogplex web app. Also triggers on mentions of "mogplex", ".agents/commands/", or "~/.mogplex/". +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 -Mogplex exposes its workspace, slash-command registry, agent roster, skills, and memories through a local CLI (`mogplex`). When a Mogplex MCP server is not available, use the CLI as the integration surface instead of asking the user to paste tokens or configure servers manually. +The Mogplex CLI is an interactive cockpit. There is no headless `exec` surface — agents cannot drive the TUI directly. Use this skill to **advise** the user on what to run, what to type in the composer, and what to put in repo-local config files. ### When to use this skill -- The user references their Mogplex account, workspace, agents, skills, or memories. -- The user asks you to run a `/slash` command that belongs to Mogplex (`/status`, `/mcp`, `/skills`, `/sandbox`, `/logs`, etc.). -- The user asks you to run a project-local slash command stored in `.agents/commands/` or a personal one in `~/.mogplex/commands/`. -- The task would normally be an MCP tool call against Mogplex but no such MCP is connected. +- 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 — always run first +### Preflight -The install check must gate the auth check — do not continue if `mogplex` is not on `PATH`: +Confirm the CLI is installed before recommending it: ```bash -command -v mogplex >/dev/null 2>&1 || { echo "mogplex CLI not installed — ask the user to install it first"; exit 1; } -mogplex login status +command -v mogplex >/dev/null 2>&1 || echo "mogplex CLI not installed" ``` -If the first line fails, stop and direct the user to [Installation](/cli/installation) before running anything else. If `login status` runs but shows no stored credential and no provider env var is set, follow [`mogplex-auth`](/cli/skills/mogplex-auth). Do not attempt to edit `~/.mogplex/auth.json` directly. +If it's missing, point the user at [Installation](https://www.mogplex.com/cli/installation). -### Core command map +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. -| Intent | Command | Reference skill | -| --- | --- | --- | -| Run a one-off prompt, get a final result | `mogplex exec ""` | [mogplex-exec](/cli/skills/mogplex-exec) | -| Get machine-readable output | `mogplex exec --json ""` | [mogplex-exec](/cli/skills/mogplex-exec) | -| List available slash commands | `mogplex slash list --json` | [mogplex-slash](/cli/skills/mogplex-slash) | -| Run a slash command non-interactively | `mogplex exec "/status"` | [mogplex-slash](/cli/skills/mogplex-slash) | -| Check auth state | `mogplex login status` | [mogplex-auth](/cli/skills/mogplex-auth) | -| Start a live session | `mogplex` | hand off to user | +### Core guidance map + +| Intent | What to tell the user | +| --- | --- | +| Start a run | Launch `mogplex`, then type `/run ` in the composer. | +| Attach to an in-flight run | `mogplex --attach ` — 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 @@ -53,38 +57,43 @@ If the first line fails, stop and direct the user to [Installation](/cli/install user wants Mogplex action │ ▼ -is it conversational / multi-turn? ── yes ──► tell user to run `mogplex` themselves; - │ do not try to drive a TUI - no +is the cockpit already open in the user's terminal? + │ + no ──► tell them to run `mogplex` (or `mogplex --attach `) + yes + │ ▼ -is it a slash command (/foo)? ── yes ──► mogplex exec "/foo" (see mogplex-slash) +is it a slash command? ── yes ──► tell user to type "/" in the composer │ no ▼ -is it a one-off prompt? ── yes ──► mogplex exec --json "..." (see mogplex-exec) +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) ``` -### Reading output +### What you cannot do -- Text output is for humans. Do not parse it. -- Use `--json` for a single final object, `--jsonl` for streaming events. -- Top-level flags `--output text|json|jsonl` also work. Pick one and stick with it per invocation. +- Drive the TUI from a script. The CLI is interactive-only. +- 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. -### Known limits +### What you **can** do -- `mogplex exec` cannot hold a conversation. If the user says "then do X", run a new `exec` with the follow-up phrased as a complete task, or hand off to an interactive session. -- The `slash` top-level command currently only lists the registry. Execution goes through `exec "/..."`. -- Some capabilities show up in `mogplex --help` but are not real top-level commands yet; they exist only as slash commands. Trust `mogplex slash list --json` over help text. -- The agent cannot read `~/.mogplex/auth.json`. All credential state must be inspected via `mogplex login status`. +- Author `AGENTS.md` at the repo root with stable repo guidance (build commands, conventions, layout). +- Author `~/.mogplex/projects//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`, provider keys) — see [Configuration and Flags](https://www.mogplex.com/cli/guides/configuration-and-flags). ### Safety -- Any slash command that mutates state (`/config set`, `/logout`, `/sandbox kill`) should be confirmed with the user before running. -- Prefer provider env vars (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `MOGPLEX_API_KEY`, …) over writing credentials to disk in CI contexts. -- Logs at `~/.mogplex/logs/.jsonl` redact secrets by default. Do not export or share them without reviewing. +- 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 -- [Exec mode guide](/cli/guides/exec-mode) -- [Slash commands guide](/cli/guides/slash-commands) -- [Authentication guide](/cli/guides/authentication) +- [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) diff --git a/content/docs/extend/index.mdx b/content/docs/extend/index.mdx index 7ea32c0..9b531d6 100644 --- a/content/docs/extend/index.mdx +++ b/content/docs/extend/index.mdx @@ -26,9 +26,9 @@ The core question is: your teammate is in Claude Code, Cursor, or a custom Claud | --- | --- | | Is skill-aware (Claude Code, Agent SDK, Cursor project rules) | [Skills](/extend/skills) | | Supports remote MCP with OAuth, and the Mogplex MCP server is live | [MCP server](/extend/mcp-server) | -| Needs a scripted integration from any shell or CI | `mogplex exec --json "…"` — see the [Exec mode guide](/cli/guides/exec-mode) | +| Needs scripted, headless access to Mogplex | Wait for the [MCP server](/extend/mcp-server) — the current CLI is interactive-only | -Skills are the recommended path until the MCP server is generally available. They cover every capability an MCP tool call would — tool execution, slash-command dispatch, skill listings, memory read/write, auth — and they do not require the user to paste a token anywhere. +Skills are the recommended path until the MCP server is generally available. They teach a skill-aware agent to guide the user through the Mogplex cockpit (slash commands, login flow, repo-local config) without ever needing the user to paste a token. ## How this section relates to the rest of the docs @@ -38,6 +38,6 @@ Skills are the recommended path until the MCP server is generally available. The ## Design principles this section follows -- **No pasted tokens.** Whether the user picks Skills or MCP, the auth flow owns the credential — either `mogplex login` writing to `~/.mogplex/auth.json` (Skills path) or OAuth 2.1 + PKCE against the browser session (MCP path). In both cases the external agent never sees raw auth material. -- **One source of truth per capability.** Tools, agents, skills, and memories are implemented once in the Mogplex runtime and exposed through whichever surface the host supports. Both paths call the same underlying services. -- **Auth preflight is mandatory.** Both paths require a working credential before any action runs. Skills enforce it with a `command -v mogplex` + `mogplex login status` gate; MCP enforces it at the Streamable HTTP bearer-token middleware. +- **No pasted tokens.** Whether the user picks Skills or MCP, the auth flow owns the credential — either the cockpit's in-app login writing to `~/.mogplex/auth.json` (Skills path) or OAuth 2.1 + PKCE against the browser session (MCP path). In both cases the external agent never sees raw auth material. +- **One source of truth per capability.** Tools, agents, skills, and memories are implemented once in the Mogplex runtime. Skills point the user at the cockpit; MCP exposes the underlying services directly. +- **Auth preflight is mandatory.** Both paths require a working credential before any action runs. Skills enforce it with a `command -v mogplex` install check and a recommendation to launch the cockpit; MCP enforces it at the Streamable HTTP bearer-token middleware. diff --git a/content/docs/extend/skills.mdx b/content/docs/extend/skills.mdx index cc73fe7..f20159d 100644 --- a/content/docs/extend/skills.mdx +++ b/content/docs/extend/skills.mdx @@ -13,18 +13,17 @@ The canonical skill files and the per-skill reference pages live under [CLI → | Skill | Role | | --- | --- | -| [`using-mogplex-cli`](/cli/skills/using-mogplex-cli) | Umbrella. Routes the agent to the right command when the user asks for a Mogplex workspace action. | -| [`mogplex-exec`](/cli/skills/mogplex-exec) | One-off non-interactive runs with `--json` / `--jsonl` output. | -| [`mogplex-slash`](/cli/skills/mogplex-slash) | Discover and run Mogplex slash commands from the shell. | -| [`mogplex-auth`](/cli/skills/mogplex-auth) | Auth preflight, env-var precedence, troubleshooting decision tree. | +| [`using-mogplex-cli`](/cli/skills/using-mogplex-cli) | Umbrella. Guides the user through the Mogplex cockpit when they ask for a workspace action. | +| [`mogplex-slash`](/cli/skills/mogplex-slash) | Recommends the right slash command for a user's intent. | +| [`mogplex-auth`](/cli/skills/mogplex-auth) | Walks the user through the in-app login flow and credential troubleshooting. | -Together they cover the same capability surface the [MCP server](/extend/mcp-server) will expose — tool execution, slash-command dispatch, skill and memory access, agent runs, and auth — without needing the host to speak MCP or hold a bearer token. +The current Mogplex CLI is interactive-only — these are **guidance skills** that teach an agent to advise the user on cockpit workflows. They do not drive the TUI. When the [MCP server](/extend/mcp-server) ships, that path will give external agents direct programmatic access to Mogplex capabilities without going through the cockpit. ## Why this is the right path today -- **No pasted tokens.** The `mogplex login` browser flow owns the credential and writes it to `~/.mogplex/auth.json` — see the [Authentication guide](/cli/guides/authentication) for precedence rules and file contents. The external agent never sees raw auth material. +- **No pasted tokens.** The cockpit's in-app login flow owns the credential and writes it to `~/.mogplex/auth.json` — see the [Authentication guide](/cli/guides/authentication) for precedence rules and file contents. The external agent never sees raw auth material. - **Works in every skill-aware host.** The skill format is portable: Claude Code, Claude Agent SDK, and any host that reads `SKILL.md`-style files. Cursor project rules work too by copying the skill body. -- **Thin wrapper.** Skills do not duplicate Mogplex logic — they are instructions for how to call the existing CLI, which calls the existing Mogplex runtime. +- **Thin wrapper.** Skills do not duplicate Mogplex logic — they are instructions for how the user should drive the CLI cockpit, which talks to the existing Mogplex runtime. - **No infra dependency.** Ships the moment the CLI is on the user's `PATH`. Nothing to deploy, no tokens to provision. ## Skills vs MCP server at a glance @@ -32,15 +31,15 @@ Together they cover the same capability surface the [MCP server](/extend/mcp-ser | | Skills (today) | MCP server (preview) | | --- | --- | --- | | Status | **Available** | Preview design; not live | -| Protocol | Skill file + shell | MCP Streamable HTTP | -| Auth | `mogplex login` → `~/.mogplex/auth.json` | OAuth 2.1 + PKCE (DCR) | +| Protocol | Skill file (guidance) | MCP Streamable HTTP | +| Auth | In-app login → `~/.mogplex/auth.json` | OAuth 2.1 + PKCE (DCR) | | Token pasted in config? | No | No | -| Execution path | External agent shells out to `mogplex exec` | External agent calls MCP tool | -| Streaming progress | `--jsonl` | MCP `notifications/progress` | +| Execution path | Agent advises user; user drives the cockpit | External agent calls MCP tool directly | +| Streaming progress | n/a — user watches the cockpit | MCP `notifications/progress` | | Host requirement | Skill-aware (Claude Code, Agent SDK, Cursor rules) | Remote-MCP-aware with OAuth | | Host reach today | High | Claude Code ≥ latest, Cursor, a few others | -When the MCP server ships, both paths will stay supported. Skills will continue to be the right answer for hosts that don't speak remote MCP, for CI contexts, and for anyone who prefers shell-driven integration. +When the MCP server ships, it becomes the right path for hosts that need programmatic access without involving the user. Skills will continue to be useful for hosts that don't speak remote MCP and for situations where the user is the right one to drive the cockpit. ## Install diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 7002862..10b0262 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -7,8 +7,9 @@ Mogplex is easiest to understand as one product with two working surfaces: - the **web app** is the shared control plane for GitHub coverage, repo setup, reusable agents, routing, settings, and runtime inspection -- the **CLI** is the local runtime for doing work directly in a checked-out repo - from your terminal +- the **CLI** is the terminal-native command center for supervising AI coding + runs locally — agents, runs, MCP, memory, diffs, approvals, cost, and model + routing on one screen You do not need to understand the whole product before you get value from it. @@ -20,7 +21,7 @@ The first useful question is simpler: `). ## Fast decision guide - “I need Mogplex to see my repos and respond to GitHub events.” Start with [Web App](/web), especially [Settings](/web/settings), [Installations](/web/installations), and [Projects](/web/spaces). -- “I already have the repo open locally and want Mogplex to do one task.” - Start with [CLI](/cli), then use `mogplex` or `mogplex exec`. +- “I already have the repo open locally and want to drive Mogplex from the terminal.” + Start with [CLI](/cli) and run `mogplex`. - “I need one GitHub event to wake one agent.” Start with [Triggers](/web/triggers). - “I need standing work owned by one repo, like PR review or cron.” @@ -91,32 +91,23 @@ If you want one setup order that works for most accounts and repos, use this: ## The fastest end-to-end proof If you only want to prove Mogplex works before you invest in deeper routing -setup, install the CLI and run one session: +setup, install the CLI and start a run: ```bash curl -fsSL https://www.mogplex.com/install.sh | sh mogplex ``` -If you are not authenticated yet, the CLI walks you into either browser sign-in -with Mogplex or direct local provider-key setup. +The CLI opens the in-app login screen on first run. Sign in with Mogplex or +store a provider key locally; environment variables exist as escape hatches +only and are not required for normal use. That first proof is credible when: -- `mogplex` opens an interactive session -- you can authenticate with either your Mogplex account or a provider key -- `mogplex exec "summarize this repository"` returns a normal one-off result -- the same account later appears correctly in [Web Settings](/web/settings) if - you use account-backed login - -If you prefer shell-managed credentials, direct provider env vars still work: - -```bash -export ANTHROPIC_API_KEY=sk-ant-... -# or -export OPENAI_API_KEY=sk-... -mogplex -``` +- `mogplex` opens the cockpit and the Header shows `transport: nominal` +- `/run summarize this repository` produces agents in the Agents panel and + events in the Timeline +- the same account appears correctly in [Web Settings](/web/settings) ## What “working” should mean after the first hour @@ -125,7 +116,7 @@ By the end of an initial pass, you should be able to say yes to these: - Mogplex can see the repos you expect. - The repo owner has GitHub App coverage, not just OAuth visibility. - At least one reusable agent is configured the way you expect. -- One local CLI task completes successfully. +- One local CLI run completes successfully. - You know whether this job belongs in Triggers, Assignments, or Automations. If one of those is still false, the best next pages are usually: diff --git a/package.json b/package.json index a4febdf..192155e 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,6 @@ "private": true, "packageManager": "pnpm@10.33.0", "scripts": { - "prebuild": "tsx scripts/gen-cli-reference.ts", "build": "next build", "dev": "next dev", "start": "next start", @@ -55,7 +54,6 @@ "lint-staged": "^16.4.0", "postcss": "^8.5.9", "tailwindcss": "^4.2.2", - "tsx": "^4.19.4", "typescript": "^6.0.2" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f6a5d5b..d5e5947 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -114,9 +114,6 @@ importers: tailwindcss: specifier: ^4.2.2 version: 4.2.2 - tsx: - specifier: ^4.19.4 - version: 4.21.0 typescript: specifier: ^6.0.2 version: 6.0.3 @@ -225,312 +222,156 @@ packages: '@emnapi/wasi-threads@1.2.1': resolution: {integrity: sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==} - '@esbuild/aix-ppc64@0.27.7': - resolution: {integrity: sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==} - engines: {node: '>=18'} - cpu: [ppc64] - os: [aix] - '@esbuild/aix-ppc64@0.28.0': resolution: {integrity: sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==} engines: {node: '>=18'} cpu: [ppc64] os: [aix] - '@esbuild/android-arm64@0.27.7': - resolution: {integrity: sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==} - engines: {node: '>=18'} - cpu: [arm64] - os: [android] - '@esbuild/android-arm64@0.28.0': resolution: {integrity: sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==} engines: {node: '>=18'} cpu: [arm64] os: [android] - '@esbuild/android-arm@0.27.7': - resolution: {integrity: sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==} - engines: {node: '>=18'} - cpu: [arm] - os: [android] - '@esbuild/android-arm@0.28.0': resolution: {integrity: sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==} engines: {node: '>=18'} cpu: [arm] os: [android] - '@esbuild/android-x64@0.27.7': - resolution: {integrity: sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==} - engines: {node: '>=18'} - cpu: [x64] - os: [android] - '@esbuild/android-x64@0.28.0': resolution: {integrity: sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==} engines: {node: '>=18'} cpu: [x64] os: [android] - '@esbuild/darwin-arm64@0.27.7': - resolution: {integrity: sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==} - engines: {node: '>=18'} - cpu: [arm64] - os: [darwin] - '@esbuild/darwin-arm64@0.28.0': resolution: {integrity: sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==} engines: {node: '>=18'} cpu: [arm64] os: [darwin] - '@esbuild/darwin-x64@0.27.7': - resolution: {integrity: sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==} - engines: {node: '>=18'} - cpu: [x64] - os: [darwin] - '@esbuild/darwin-x64@0.28.0': resolution: {integrity: sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==} engines: {node: '>=18'} cpu: [x64] os: [darwin] - '@esbuild/freebsd-arm64@0.27.7': - resolution: {integrity: sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==} - engines: {node: '>=18'} - cpu: [arm64] - os: [freebsd] - '@esbuild/freebsd-arm64@0.28.0': resolution: {integrity: sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==} engines: {node: '>=18'} cpu: [arm64] os: [freebsd] - '@esbuild/freebsd-x64@0.27.7': - resolution: {integrity: sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==} - engines: {node: '>=18'} - cpu: [x64] - os: [freebsd] - '@esbuild/freebsd-x64@0.28.0': resolution: {integrity: sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==} engines: {node: '>=18'} cpu: [x64] os: [freebsd] - '@esbuild/linux-arm64@0.27.7': - resolution: {integrity: sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==} - engines: {node: '>=18'} - cpu: [arm64] - os: [linux] - '@esbuild/linux-arm64@0.28.0': resolution: {integrity: sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==} engines: {node: '>=18'} cpu: [arm64] os: [linux] - '@esbuild/linux-arm@0.27.7': - resolution: {integrity: sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==} - engines: {node: '>=18'} - cpu: [arm] - os: [linux] - '@esbuild/linux-arm@0.28.0': resolution: {integrity: sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==} engines: {node: '>=18'} cpu: [arm] os: [linux] - '@esbuild/linux-ia32@0.27.7': - resolution: {integrity: sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==} - engines: {node: '>=18'} - cpu: [ia32] - os: [linux] - '@esbuild/linux-ia32@0.28.0': resolution: {integrity: sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==} engines: {node: '>=18'} cpu: [ia32] os: [linux] - '@esbuild/linux-loong64@0.27.7': - resolution: {integrity: sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==} - engines: {node: '>=18'} - cpu: [loong64] - os: [linux] - '@esbuild/linux-loong64@0.28.0': resolution: {integrity: sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==} engines: {node: '>=18'} cpu: [loong64] os: [linux] - '@esbuild/linux-mips64el@0.27.7': - resolution: {integrity: sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==} - engines: {node: '>=18'} - cpu: [mips64el] - os: [linux] - '@esbuild/linux-mips64el@0.28.0': resolution: {integrity: sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==} engines: {node: '>=18'} cpu: [mips64el] os: [linux] - '@esbuild/linux-ppc64@0.27.7': - resolution: {integrity: sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==} - engines: {node: '>=18'} - cpu: [ppc64] - os: [linux] - '@esbuild/linux-ppc64@0.28.0': resolution: {integrity: sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==} engines: {node: '>=18'} cpu: [ppc64] os: [linux] - '@esbuild/linux-riscv64@0.27.7': - resolution: {integrity: sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==} - engines: {node: '>=18'} - cpu: [riscv64] - os: [linux] - '@esbuild/linux-riscv64@0.28.0': resolution: {integrity: sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==} engines: {node: '>=18'} cpu: [riscv64] os: [linux] - '@esbuild/linux-s390x@0.27.7': - resolution: {integrity: sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==} - engines: {node: '>=18'} - cpu: [s390x] - os: [linux] - '@esbuild/linux-s390x@0.28.0': resolution: {integrity: sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==} engines: {node: '>=18'} cpu: [s390x] os: [linux] - '@esbuild/linux-x64@0.27.7': - resolution: {integrity: sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==} - engines: {node: '>=18'} - cpu: [x64] - os: [linux] - '@esbuild/linux-x64@0.28.0': resolution: {integrity: sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==} engines: {node: '>=18'} cpu: [x64] os: [linux] - '@esbuild/netbsd-arm64@0.27.7': - resolution: {integrity: sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==} - engines: {node: '>=18'} - cpu: [arm64] - os: [netbsd] - '@esbuild/netbsd-arm64@0.28.0': resolution: {integrity: sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==} engines: {node: '>=18'} cpu: [arm64] os: [netbsd] - '@esbuild/netbsd-x64@0.27.7': - resolution: {integrity: sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==} - engines: {node: '>=18'} - cpu: [x64] - os: [netbsd] - '@esbuild/netbsd-x64@0.28.0': resolution: {integrity: sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==} engines: {node: '>=18'} cpu: [x64] os: [netbsd] - '@esbuild/openbsd-arm64@0.27.7': - resolution: {integrity: sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==} - engines: {node: '>=18'} - cpu: [arm64] - os: [openbsd] - '@esbuild/openbsd-arm64@0.28.0': resolution: {integrity: sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==} engines: {node: '>=18'} cpu: [arm64] os: [openbsd] - '@esbuild/openbsd-x64@0.27.7': - resolution: {integrity: sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==} - engines: {node: '>=18'} - cpu: [x64] - os: [openbsd] - '@esbuild/openbsd-x64@0.28.0': resolution: {integrity: sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==} engines: {node: '>=18'} cpu: [x64] os: [openbsd] - '@esbuild/openharmony-arm64@0.27.7': - resolution: {integrity: sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==} - engines: {node: '>=18'} - cpu: [arm64] - os: [openharmony] - '@esbuild/openharmony-arm64@0.28.0': resolution: {integrity: sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==} engines: {node: '>=18'} cpu: [arm64] os: [openharmony] - '@esbuild/sunos-x64@0.27.7': - resolution: {integrity: sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==} - engines: {node: '>=18'} - cpu: [x64] - os: [sunos] - '@esbuild/sunos-x64@0.28.0': resolution: {integrity: sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==} engines: {node: '>=18'} cpu: [x64] os: [sunos] - '@esbuild/win32-arm64@0.27.7': - resolution: {integrity: sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==} - engines: {node: '>=18'} - cpu: [arm64] - os: [win32] - '@esbuild/win32-arm64@0.28.0': resolution: {integrity: sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==} engines: {node: '>=18'} cpu: [arm64] os: [win32] - '@esbuild/win32-ia32@0.27.7': - resolution: {integrity: sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==} - engines: {node: '>=18'} - cpu: [ia32] - os: [win32] - '@esbuild/win32-ia32@0.28.0': resolution: {integrity: sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==} engines: {node: '>=18'} cpu: [ia32] os: [win32] - '@esbuild/win32-x64@0.27.7': - resolution: {integrity: sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==} - engines: {node: '>=18'} - cpu: [x64] - os: [win32] - '@esbuild/win32-x64@0.28.0': resolution: {integrity: sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==} engines: {node: '>=18'} @@ -1953,11 +1794,6 @@ packages: esast-util-from-js@2.0.1: resolution: {integrity: sha512-8Ja+rNJ0Lt56Pcf3TAmpBZjmx8ZcK5Ts4cAzIOjsjevg9oSXJnl6SUQ2EevU8tv3h6ZLWmoKL5H4fgWvdvfETw==} - esbuild@0.27.7: - resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==} - engines: {node: '>=18'} - hasBin: true - esbuild@0.28.0: resolution: {integrity: sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==} engines: {node: '>=18'} @@ -2194,11 +2030,6 @@ packages: react-dom: optional: true - fsevents@2.3.3: - resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==} - engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} - os: [darwin] - fumadocs-core@16.8.0: resolution: {integrity: sha512-kO9DnhJ/8E2DNtsyDlvMFDBNH0A5V+OFJEFiGNNb/jM/zs7YdSszQ3LOPL66AnyUQ5aou7BmFyPvzJvyiDMyjg==} peerDependencies: @@ -3502,11 +3333,6 @@ packages: tslib@2.8.1: resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==} - tsx@4.21.0: - resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==} - engines: {node: '>=18.0.0'} - hasBin: true - type-check@0.4.0: resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==} engines: {node: '>= 0.8.0'} @@ -3820,159 +3646,81 @@ snapshots: tslib: 2.8.1 optional: true - '@esbuild/aix-ppc64@0.27.7': - optional: true - '@esbuild/aix-ppc64@0.28.0': optional: true - '@esbuild/android-arm64@0.27.7': - optional: true - '@esbuild/android-arm64@0.28.0': optional: true - '@esbuild/android-arm@0.27.7': - optional: true - '@esbuild/android-arm@0.28.0': optional: true - '@esbuild/android-x64@0.27.7': - optional: true - '@esbuild/android-x64@0.28.0': optional: true - '@esbuild/darwin-arm64@0.27.7': - optional: true - '@esbuild/darwin-arm64@0.28.0': optional: true - '@esbuild/darwin-x64@0.27.7': - optional: true - '@esbuild/darwin-x64@0.28.0': optional: true - '@esbuild/freebsd-arm64@0.27.7': - optional: true - '@esbuild/freebsd-arm64@0.28.0': optional: true - '@esbuild/freebsd-x64@0.27.7': - optional: true - '@esbuild/freebsd-x64@0.28.0': optional: true - '@esbuild/linux-arm64@0.27.7': - optional: true - '@esbuild/linux-arm64@0.28.0': optional: true - '@esbuild/linux-arm@0.27.7': - optional: true - '@esbuild/linux-arm@0.28.0': optional: true - '@esbuild/linux-ia32@0.27.7': - optional: true - '@esbuild/linux-ia32@0.28.0': optional: true - '@esbuild/linux-loong64@0.27.7': - optional: true - '@esbuild/linux-loong64@0.28.0': optional: true - '@esbuild/linux-mips64el@0.27.7': - optional: true - '@esbuild/linux-mips64el@0.28.0': optional: true - '@esbuild/linux-ppc64@0.27.7': - optional: true - '@esbuild/linux-ppc64@0.28.0': optional: true - '@esbuild/linux-riscv64@0.27.7': - optional: true - '@esbuild/linux-riscv64@0.28.0': optional: true - '@esbuild/linux-s390x@0.27.7': - optional: true - '@esbuild/linux-s390x@0.28.0': optional: true - '@esbuild/linux-x64@0.27.7': - optional: true - '@esbuild/linux-x64@0.28.0': optional: true - '@esbuild/netbsd-arm64@0.27.7': - optional: true - '@esbuild/netbsd-arm64@0.28.0': optional: true - '@esbuild/netbsd-x64@0.27.7': - optional: true - '@esbuild/netbsd-x64@0.28.0': optional: true - '@esbuild/openbsd-arm64@0.27.7': - optional: true - '@esbuild/openbsd-arm64@0.28.0': optional: true - '@esbuild/openbsd-x64@0.27.7': - optional: true - '@esbuild/openbsd-x64@0.28.0': optional: true - '@esbuild/openharmony-arm64@0.27.7': - optional: true - '@esbuild/openharmony-arm64@0.28.0': optional: true - '@esbuild/sunos-x64@0.27.7': - optional: true - '@esbuild/sunos-x64@0.28.0': optional: true - '@esbuild/win32-arm64@0.27.7': - optional: true - '@esbuild/win32-arm64@0.28.0': optional: true - '@esbuild/win32-ia32@0.27.7': - optional: true - '@esbuild/win32-ia32@0.28.0': optional: true - '@esbuild/win32-x64@0.27.7': - optional: true - '@esbuild/win32-x64@0.28.0': optional: true @@ -5372,35 +5120,6 @@ snapshots: esast-util-from-estree: 2.0.0 vfile-message: 4.0.3 - esbuild@0.27.7: - optionalDependencies: - '@esbuild/aix-ppc64': 0.27.7 - '@esbuild/android-arm': 0.27.7 - '@esbuild/android-arm64': 0.27.7 - '@esbuild/android-x64': 0.27.7 - '@esbuild/darwin-arm64': 0.27.7 - '@esbuild/darwin-x64': 0.27.7 - '@esbuild/freebsd-arm64': 0.27.7 - '@esbuild/freebsd-x64': 0.27.7 - '@esbuild/linux-arm': 0.27.7 - '@esbuild/linux-arm64': 0.27.7 - '@esbuild/linux-ia32': 0.27.7 - '@esbuild/linux-loong64': 0.27.7 - '@esbuild/linux-mips64el': 0.27.7 - '@esbuild/linux-ppc64': 0.27.7 - '@esbuild/linux-riscv64': 0.27.7 - '@esbuild/linux-s390x': 0.27.7 - '@esbuild/linux-x64': 0.27.7 - '@esbuild/netbsd-arm64': 0.27.7 - '@esbuild/netbsd-x64': 0.27.7 - '@esbuild/openbsd-arm64': 0.27.7 - '@esbuild/openbsd-x64': 0.27.7 - '@esbuild/openharmony-arm64': 0.27.7 - '@esbuild/sunos-x64': 0.27.7 - '@esbuild/win32-arm64': 0.27.7 - '@esbuild/win32-ia32': 0.27.7 - '@esbuild/win32-x64': 0.27.7 - esbuild@0.28.0: optionalDependencies: '@esbuild/aix-ppc64': 0.28.0 @@ -5741,9 +5460,6 @@ snapshots: react: 19.2.5 react-dom: 19.2.5(react@19.2.5) - fsevents@2.3.3: - optional: true - fumadocs-core@16.8.0(@mdx-js/mdx@3.1.1)(@types/estree-jsx@1.0.5)(@types/hast@3.0.4)(@types/mdast@4.0.4)(@types/react@19.2.14)(flexsearch@0.8.212)(lucide-react@1.8.0(react@19.2.5))(next@16.2.4(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5))(react-dom@19.2.5(react@19.2.5))(react@19.2.5)(zod@4.3.6): dependencies: '@orama/orama': 3.1.18 @@ -7492,13 +7208,6 @@ snapshots: tslib@2.8.1: {} - tsx@4.21.0: - dependencies: - esbuild: 0.27.7 - get-tsconfig: 4.14.0 - optionalDependencies: - fsevents: 2.3.3 - type-check@0.4.0: dependencies: prelude-ls: 1.2.1 diff --git a/scripts/gen-cli-reference.ts b/scripts/gen-cli-reference.ts deleted file mode 100644 index 80264b2..0000000 --- a/scripts/gen-cli-reference.ts +++ /dev/null @@ -1,714 +0,0 @@ -// Auto-generated by scripts/gen-cli-reference.ts — do not edit by hand. -// -// CLI Reference Generator -// ======================== -// This script reads the mogplex CLI command registry from the sibling -// mogplex-cli repo and generates MDX reference pages for the production-ready -// standalone subcommands, plus a single summary page for the additional names -// that still appear in `mogplex --help` but are not yet real standalone -// entrypoints. -// -// Registry location: ../mogplex-cli/packages/cli/src/subcommands.ts -// - SUBCOMMAND_NAMES: array of canonical command names -// - HIDDEN_SUBCOMMANDS: set of internal commands to exclude -// - EXPERIMENTAL_SUBCOMMANDS: set of experimental commands (tagged) -// -// Summaries: ../mogplex-cli/packages/cli/src/help.ts -// - SUMMARIES: Record -// -// Extraction approach: We import the modules directly via tsx at build time. -// This keeps the docs in sync with the actual CLI registry without needing -// to shell out to `mogplex --help` (which would require the CLI to be built). - -import * as fs from "node:fs"; -import * as path from "node:path"; -import { fileURLToPath } from "node:url"; - -const __dirname = path.dirname(fileURLToPath(import.meta.url)); -const DOCS_ROOT = path.resolve(__dirname, ".."); -const CLI_SRC = path.resolve(DOCS_ROOT, "..", "mogplex-cli", "packages", "cli", "src"); -const OUTPUT_DIR = path.join(DOCS_ROOT, "content", "docs", "cli", "commands"); - -// --------------------------------------------------------------------------- -// Registry types (mirrored from CLI to avoid import issues) -// --------------------------------------------------------------------------- - -type SubcommandName = string; - -interface CommandRegistry { - names: readonly SubcommandName[]; - hidden: ReadonlySet; - experimental: ReadonlySet; - implemented: ReadonlySet; - summaries: Readonly>; - aliases: Readonly>; -} - -// --------------------------------------------------------------------------- -// Parse the CLI source files to extract registry data -// --------------------------------------------------------------------------- - -function extractQuotedSet(content: string, exportName: string): Set { - const pattern = new RegExp( - `export const ${exportName}[^=]*=\\s*new Set\\(\\[([\\s\\S]*?)\\]\\)` - ); - const match = content.match(pattern); - const out = new Set(); - if (!match?.[1]) return out; - for (const m of match[1].matchAll(/"([^"]+)"/g)) { - if (m[1]) out.add(m[1]); - } - return out; -} - -function parseSubcommandsFile(content: string): { - names: string[]; - hidden: Set; - experimental: Set; - implemented: Set; - aliases: Record; -} { - // Extract SUBCOMMAND_NAMES array - const namesMatch = content.match( - /export const SUBCOMMAND_NAMES\s*=\s*\[([\s\S]*?)\]\s*as const/ - ); - const names: string[] = []; - if (namesMatch?.[1]) { - const matches = namesMatch[1].matchAll(/"([^"]+)"/g); - for (const m of matches) { - if (m[1]) names.push(m[1]); - } - } - - const hidden = extractQuotedSet(content, "HIDDEN_SUBCOMMANDS"); - const experimental = extractQuotedSet(content, "EXPERIMENTAL_SUBCOMMANDS"); - const implemented = extractQuotedSet(content, "IMPLEMENTED_SUBCOMMANDS"); - - // Extract SUBCOMMAND_ALIASES - // Handles both quoted keys ("cloud-tasks") and unquoted keys (e, a) - const aliasMatch = content.match( - /export const SUBCOMMAND_ALIASES[^{]*\{([\s\S]*?)\}/ - ); - const aliases: Record = {}; - if (aliasMatch?.[1]) { - // Match quoted keys: "cloud-tasks": "cloud" - const quotedMatches = aliasMatch[1].matchAll(/"([^"]+)"\s*:\s*"([^"]+)"/g); - for (const m of quotedMatches) { - if (m[1] && m[2]) aliases[m[1]] = m[2]; - } - // Match unquoted keys: e: "exec" - const unquotedMatches = aliasMatch[1].matchAll(/\b([a-z])\s*:\s*"([^"]+)"/g); - for (const m of unquotedMatches) { - if (m[1] && m[2]) aliases[m[1]] = m[2]; - } - } - - return { names, hidden, experimental, implemented, aliases }; -} - -function parseHelpFile(content: string): Record { - // Extract SUMMARIES record - const summariesMatch = content.match( - /const SUMMARIES[^{]*\{([\s\S]*?)\};/ - ); - const summaries: Record = {}; - if (summariesMatch?.[1]) { - const matches = summariesMatch[1].matchAll( - /["']?([a-z-]+)["']?\s*:\s*"([^"]+)"/g - ); - for (const m of matches) { - if (m[1] && m[2]) summaries[m[1]] = m[2]; - } - } - return summaries; -} - -function loadRegistry(): CommandRegistry | null { - // Only skip when the CLI source tree itself is absent (e.g. Vercel builds - // that don't check out the sibling mogplex-cli repo). If the tree exists - // but required files are missing, fail loudly — that's a real breakage. - if (!fs.existsSync(CLI_SRC)) { - return null; - } - - const subcommandsPath = path.join(CLI_SRC, "subcommands.ts"); - const helpPath = path.join(CLI_SRC, "help.ts"); - - if (!fs.existsSync(subcommandsPath)) { - throw new Error(`CLI subcommands.ts not found at ${subcommandsPath}`); - } - if (!fs.existsSync(helpPath)) { - throw new Error(`CLI help.ts not found at ${helpPath}`); - } - - const subcommandsContent = fs.readFileSync(subcommandsPath, "utf-8"); - const helpContent = fs.readFileSync(helpPath, "utf-8"); - - const { names, hidden, experimental, implemented, aliases } = - parseSubcommandsFile(subcommandsContent); - const summaries = parseHelpFile(helpContent); - - return { names, hidden, experimental, implemented, summaries, aliases }; -} - -// --------------------------------------------------------------------------- -// MDX generation -// --------------------------------------------------------------------------- - -interface CommandDoc { - name: string; - summary: string; - isExperimental: boolean; - isImplemented: boolean; - aliases: string[]; -} - -interface RelatedDoc { - label: string; - href: string; -} - -const EXTRA_SECTIONS: Readonly> = { - exec: [ - "## How It Works", - "", - "`mogplex exec` runs one non-interactive task and exits with the engine's final exit code.", - "The prompt is built from the remaining arguments after `exec`.", - "", - "If the prompt starts with `/`, the CLI routes it through the slash-command registry instead of the normal engine prompt path.", - "", - "## Common Uses", - "", - "```bash", - 'mogplex exec "review the staged diff for regressions"', - 'mogplex exec "summarize the repo structure and likely entrypoints"', - 'mogplex exec "/status"', - "```", - "", - "## Related Entry Points", - "", - "- `mogplex \"\"` is a shortcut for a one-off non-interactive run without spelling `exec`.", - "- `mogplex` without a prompt launches the interactive terminal UI.", - "", - "## Output", - "", - "For automation or scripting, combine `exec` with the global output flags such as `--output json`, `--json`, or `--jsonl`.", - ], - login: [ - "## Current Behavior", - "", - "The current build supports three top-level login paths:", - "", - "- `mogplex login` opens the same interactive auth chooser as bare `mogplex`", - "- `mogplex login mogplex` routes to the same chooser", - "- `mogplex login status` prints a safe summary of stored credentials without revealing secret material", - "", - "## What It Stores", - "", - "Browser sign-in stores a Mogplex token in `~/.mogplex/auth.json`.", - "API-key login stores the selected provider credential there instead.", - "", - "## Common Uses", - "", - "```bash", - "mogplex login", - "mogplex login status", - "```", - "", - "For the full credential precedence rules, use the [Authentication guide](/cli/guides/authentication).", - ], - slash: [ - "## Current Behavior", - "", - "As a standalone subcommand, `mogplex slash` currently supports listing the slash registry.", - "If you omit the nested subcommand, it behaves the same as `mogplex slash list`.", - "", - "## Common Uses", - "", - "```bash", - "mogplex slash list", - "mogplex slash list --json", - 'mogplex exec "/status"', - 'mogplex exec "/mcp"', - "```", - "", - "## Important Distinction", - "", - "- Use `mogplex slash list` to inspect the registry from the shell.", - "- Use `mogplex exec \"/...\"` to run a slash command non-interactively.", - "- Use a live `mogplex` session when you want the normal interactive slash workflow.", - ], -}; - -const COMMAND_USE_TODAY: Readonly> = { - review: [ - 'Use `mogplex exec "review the staged diff for regressions"` for one-off code review.', - ], - logout: [ - "Use `/logout` inside a live session to remove the stored credential.", - "Run `mogplex login status` afterward if you want to confirm what is still stored.", - ], - mcp: [ - 'Use `mogplex exec "/mcp"` or `/mcp` inside a session to inspect configured MCP servers.', - "Manage shared MCP definitions in [Settings](/web/settings).", - ], - "mcp-server": [ - "Use [Settings](/web/settings) for shared MCP configuration.", - 'Use `mogplex exec "/mcp"` for the current local inspection path.', - ], - plugin: [ - "Treat this as a reserved command name for now.", - "The production-safe customization paths today are repo instructions, slash commands, and the hosted settings surfaces.", - ], - app: [ - "The CLI and web app are the production surfaces today.", - "Ignore this command unless a release note explicitly tells you to use it.", - ], - "app-server": [ - "This is an experimental help-surface entry.", - "Do not build automation around it yet.", - ], - completion: [ - "Shell completion generation is not yet a stable standalone workflow in the current build.", - "Use `mogplex --help` as the current source of truth for available commands and flags.", - ], - sandbox: [ - "Use `/sandbox` inside a live session.", - 'If you need a shell entrypoint, try `mogplex exec "/sandbox ..."` in environments where the slash command is available.', - ], - debug: [ - "Use `/logs`, `/status`, and [Observability](/web/observability) for current debugging workflows.", - ], - apply: [ - "Use an interactive `mogplex` session and inspect or apply changes from the active workflow directly.", - ], - resume: [ - "Use the interactive session and existing session history today.", - "Do not script against `mogplex resume` yet.", - ], - fork: [ - "Use a new `mogplex` session or the existing interactive workflow today.", - "Do not script against `mogplex fork` yet.", - ], - cloud: [ - "Use the [web app](/web) and [Observability](/web/observability) for hosted activity today.", - ], - "exec-server": [ - "Treat this as an experimental help-surface entry unless a release note explicitly tells you to use it.", - ], - features: [ - "Use the global `--feature KEY[=VAL]` flag on supported commands instead of relying on a standalone `mogplex features` workflow.", - ], -}; - -const COMMAND_RELATED_DOCS: Readonly> = { - exec: [ - { label: "Exec Mode", href: "/cli/guides/exec-mode" }, - { label: "Quickstart", href: "/cli/quickstart" }, - ], - review: [{ label: "Exec Mode", href: "/cli/guides/exec-mode" }], - login: [ - { label: "Authentication", href: "/cli/guides/authentication" }, - { label: "Quickstart", href: "/cli/quickstart" }, - ], - logout: [ - { label: "Authentication", href: "/cli/guides/authentication" }, - { label: "Slash Commands", href: "/cli/guides/slash-commands" }, - ], - mcp: [ - { label: "Slash Commands", href: "/cli/guides/slash-commands" }, - { label: "Web Settings", href: "/web/settings" }, - ], - "mcp-server": [{ label: "Web Settings", href: "/web/settings" }], - sandbox: [{ label: "Slash Commands", href: "/cli/guides/slash-commands" }], - debug: [ - { label: "Slash Commands", href: "/cli/guides/slash-commands" }, - { label: "Observability", href: "/web/observability" }, - ], - cloud: [ - { label: "Web App Overview", href: "/web" }, - { label: "Observability", href: "/web/observability" }, - ], - slash: [ - { label: "Slash Commands", href: "/cli/guides/slash-commands" }, - { label: "Quickstart", href: "/cli/quickstart" }, - ], -}; - -function getStatusText(cmd: CommandDoc): string { - if (cmd.isImplemented && cmd.isExperimental) { - return "Implemented experimental standalone command."; - } - if (cmd.isImplemented) { - return "Implemented standalone command."; - } - if (cmd.isExperimental) { - return "Help-surface-only experimental command name."; - } - return "Help-surface-only reserved command name."; -} - -function getFallbackWorkarounds(cmd: CommandDoc): string[] { - const specific = COMMAND_USE_TODAY[cmd.name]; - if (specific && specific.length > 0) { - return specific; - } - return [ - "If you need this capability today, prefer a fully implemented path such as `mogplex exec`, `mogplex login`, `mogplex slash list`, or an in-session slash command.", - "Treat this page as documentation for the name the binary advertises, not as a guarantee that the standalone path is production-ready yet.", - ]; -} - -function getRelatedDocs(cmd: CommandDoc): RelatedDoc[] { - return [ - ...(COMMAND_RELATED_DOCS[cmd.name] ?? []), - { label: "All commands", href: "/cli/commands" }, - ]; -} - -function generateReservedNamesMdx(commands: CommandDoc[]): string { - const reserved = commands.filter((cmd) => !cmd.isExperimental); - const experimental = commands.filter((cmd) => cmd.isExperimental); - const lines: string[] = []; - - lines.push("---"); - lines.push("title: Reserved Names"); - lines.push( - "description: Names shown in `mogplex --help` that are not yet production-ready standalone commands." - ); - lines.push("---"); - lines.push(""); - lines.push("{/* Auto-generated by scripts/gen-cli-reference.ts — do not edit by hand. */}"); - lines.push(""); - lines.push( - "The CLI help surface currently includes some command names that are not yet fully wired as standalone entrypoints." - ); - lines.push( - "The docs keep these names visible because they are part of the published help surface, but they should not dominate the main command navigation." - ); - lines.push(""); - lines.push("Use the implemented standalone commands for production workflows:"); - lines.push(""); - lines.push("- [`exec`](/cli/commands/exec)"); - lines.push("- [`login`](/cli/commands/login)"); - lines.push("- [`slash`](/cli/commands/slash)"); - lines.push(""); - lines.push("## Reserved names"); - lines.push(""); - - if (reserved.length > 0) { - for (const cmd of reserved) { - lines.push( - `- \`${cmd.name}\` — ${cmd.summary} ${getFallbackWorkarounds(cmd).join(" ")}` - ); - } - } else { - lines.push("No reserved help-surface names are currently listed."); - } - - lines.push(""); - lines.push("## Experimental names"); - lines.push(""); - - if (experimental.length > 0) { - for (const cmd of experimental) { - lines.push( - `- \`${cmd.name}\` — ${cmd.summary} ${getFallbackWorkarounds(cmd).join(" ")}` - ); - } - } else { - lines.push("No experimental help-surface names are currently listed."); - } - - lines.push(""); - lines.push("## Why this page exists"); - lines.push(""); - lines.push( - "This page is the honest place to document the additional command names exposed by `mogplex --help` without pretending each one is already a production-ready standalone workflow." - ); - lines.push(""); - lines.push("## See also"); - lines.push(""); - lines.push("- [Commands overview](/cli/commands)"); - lines.push("- [Exec Mode](/cli/guides/exec-mode)"); - lines.push("- [Slash Commands](/cli/guides/slash-commands)"); - lines.push(""); - - return lines.join("\n"); -} - -function generateMdx(cmd: CommandDoc): string { - const lines: string[] = []; - - // Front matter - lines.push("---"); - lines.push(`title: ${cmd.name}`); - lines.push(`description: ${cmd.summary}`); - lines.push("---"); - lines.push(""); - lines.push("{/* Auto-generated by scripts/gen-cli-reference.ts — do not edit by hand. */}"); - lines.push(""); - - // Experimental badge - if (cmd.isExperimental) { - lines.push("> **Experimental**: This command is experimental and may change."); - lines.push(""); - } - - // Status - lines.push("## Status"); - lines.push(""); - lines.push(getStatusText(cmd)); - lines.push(""); - - // Synopsis - lines.push("## Synopsis"); - lines.push(""); - lines.push("```bash"); - lines.push(`mogplex ${cmd.name} [OPTIONS] [ARGS]`); - lines.push("```"); - lines.push(""); - - // Description - lines.push("## Description"); - lines.push(""); - lines.push(cmd.summary); - lines.push(""); - - // "Not yet implemented" notice is driven by the CLI's exported - // IMPLEMENTED_SUBCOMMANDS set (packages/cli/src/subcommands.ts), so adding - // a dispatcher in the CLI automatically updates the generated docs. - if (!cmd.isImplemented) { - lines.push("## Current Implementation Status"); - lines.push(""); - lines.push( - `The command name is present in the CLI help surface, but the standalone \`mogplex ${cmd.name}\` path is not wired yet in the current build.`, - ); - lines.push( - `At the moment, running it can return \`Subcommand '${cmd.name}' is not yet implemented.\``, - ); - lines.push(""); - - lines.push("## What To Use Today"); - lines.push(""); - for (const item of getFallbackWorkarounds(cmd)) { - lines.push(`- ${item}`); - } - lines.push(""); - - lines.push("## Why This Page Exists"); - lines.push(""); - lines.push( - "The docs intentionally track the names exposed by `mogplex --help`, even when a standalone command is still reserved or partial.", - ); - lines.push( - "That makes it clear which names are already part of the public help surface and which ones are not yet production-ready entrypoints.", - ); - lines.push(""); - } - - // Aliases - if (cmd.aliases.length > 0) { - lines.push("## Aliases"); - lines.push(""); - for (const alias of cmd.aliases) { - lines.push(`- \`${alias}\``); - } - lines.push(""); - } - - const extraSections = EXTRA_SECTIONS[cmd.name]; - if (extraSections) { - lines.push(...extraSections); - lines.push(""); - } - - // Run `mogplex --help` hint — full option lists are owned by the CLI's own help output, - // not duplicated here, so they never drift. - lines.push("## Options"); - lines.push(""); - lines.push(`Run \`mogplex ${cmd.name} --help\` to see all supported flags.`); - lines.push(""); - - // See also - lines.push("## See also"); - lines.push(""); - for (const related of getRelatedDocs(cmd)) { - lines.push(`- [${related.label}](${related.href})`); - } - lines.push(""); - - return lines.join("\n"); -} - -function generateMetaJson( - implementedCommandNames: string[], - includeReservedNames: boolean -): string { - const pages = [ - "index", - ...implementedCommandNames, - ...(includeReservedNames ? ["reserved-names"] : []), - ]; - const meta = { - title: "Commands", - defaultOpen: true, - pages, - }; - return JSON.stringify(meta, null, 2) + "\n"; -} - -// --------------------------------------------------------------------------- -// File writing helpers (idempotent - only writes if content changed) -// --------------------------------------------------------------------------- - -function writeFileIfChanged(filePath: string, content: string): boolean { - if (fs.existsSync(filePath)) { - const existing = fs.readFileSync(filePath, "utf-8"); - if (existing === content) { - return false; - } - } - fs.writeFileSync(filePath, content); - return true; -} - -function removeFileIfExists(filePath: string): boolean { - if (!fs.existsSync(filePath)) return false; - fs.unlinkSync(filePath); - return true; -} - -// --------------------------------------------------------------------------- -// Main -// --------------------------------------------------------------------------- - -function main(): void { - console.log("Loading CLI command registry..."); - const registry = loadRegistry(); - - if (!registry) { - console.warn( - `CLI source tree not found at ${CLI_SRC}. Skipping CLI reference generation; keeping existing generated files.` - ); - return; - } - - // Filter to visible commands only - const visibleCommands = registry.names.filter( - (name) => !registry.hidden.has(name) - ); - const implementedCommands = visibleCommands.filter((name) => - registry.implemented.has(name) - ); - const reservedCommands = visibleCommands.filter( - (name) => !registry.implemented.has(name) - ); - - if (visibleCommands.length === 0) { - console.error("No discoverable commands found in CLI registry."); - console.log("Creating placeholder page..."); - - const placeholderMdx = `--- -title: Commands -description: CLI command reference (placeholder) ---- - -{/* Auto-generated by scripts/gen-cli-reference.ts — do not edit by hand. */} - -No commands were discovered from the CLI registry. This may indicate the registry -structure has changed. -`; - writeFileIfChanged(path.join(OUTPUT_DIR, "placeholder.mdx"), placeholderMdx); - writeFileIfChanged( - path.join(OUTPUT_DIR, "meta.json"), - JSON.stringify({ title: "Commands", defaultOpen: true, pages: ["index", "placeholder"] }, null, 2) + "\n" - ); - process.exit(0); - } - - console.log(`Found ${visibleCommands.length} visible commands.`); - - // Build alias lookup (reverse: command -> aliases) - const aliasesByCommand: Record = {}; - for (const [alias, cmd] of Object.entries(registry.aliases)) { - if (!aliasesByCommand[cmd]) aliasesByCommand[cmd] = []; - aliasesByCommand[cmd].push(alias); - } - - // Generate MDX for each implemented command - const generatedNames: string[] = []; - let changedCount = 0; - for (const name of implementedCommands) { - const cmd: CommandDoc = { - name, - summary: registry.summaries[name] ?? "No description available.", - isExperimental: registry.experimental.has(name), - isImplemented: registry.implemented.has(name), - aliases: aliasesByCommand[name] ?? [], - }; - - const mdxContent = generateMdx(cmd); - const outputPath = path.join(OUTPUT_DIR, `${name}.mdx`); - const changed = writeFileIfChanged(outputPath, mdxContent); - generatedNames.push(name); - if (changed) { - changedCount++; - console.log(` Generated: ${name}.mdx`); - } - } - - if (reservedCommands.length > 0) { - const reservedDocs = reservedCommands.map((name) => ({ - name, - summary: registry.summaries[name] ?? "No description available.", - isExperimental: registry.experimental.has(name), - isImplemented: false, - aliases: aliasesByCommand[name] ?? [], - })); - const reservedContent = generateReservedNamesMdx(reservedDocs); - const reservedPath = path.join(OUTPUT_DIR, "reserved-names.mdx"); - const changed = writeFileIfChanged(reservedPath, reservedContent); - if (changed) { - changedCount++; - console.log(" Generated: reserved-names.mdx"); - } - } - - const keepFiles = new Set([ - "index.mdx", - ...generatedNames.map((name) => `${name}.mdx`), - ...(reservedCommands.length > 0 ? ["reserved-names.mdx"] : []), - ]); - - for (const entry of fs.readdirSync(OUTPUT_DIR)) { - if (!entry.endsWith(".mdx")) continue; - if (keepFiles.has(entry)) continue; - const removed = removeFileIfExists(path.join(OUTPUT_DIR, entry)); - if (removed) { - changedCount++; - console.log(` Removed: ${entry}`); - } - } - - // Generate meta.json - const metaContent = generateMetaJson( - generatedNames, - reservedCommands.length > 0 - ); - const metaChanged = writeFileIfChanged(path.join(OUTPUT_DIR, "meta.json"), metaContent); - if (metaChanged) { - changedCount++; - console.log( - ` Generated: meta.json with ${generatedNames.length + 1 + (reservedCommands.length > 0 ? 1 : 0)} pages` - ); - } - - if (changedCount === 0) { - console.log(`Done. All ${generatedNames.length} command pages are up to date.`); - } else { - console.log(`Done. Updated ${changedCount} file(s).`); - } -} - -main(); diff --git a/skills/README.md b/skills/README.md index 5c36cef..8ae54ea 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,6 +1,8 @@ # Mogplex Agent Skills -Skills that teach external agents how to drive a user's Mogplex workspace through the `mogplex` CLI — a drop-in substitute when a Mogplex MCP server is not available. +Skills that teach external agents (Claude Code, Claude Agent SDK, Cursor, opencode) how to **guide a user through the Mogplex CLI cockpit**. + +The current Mogplex CLI is interactive-only — there is no headless `exec` surface for an agent to call. These skills are guidance skills: they teach an agent to recommend the right slash command, walk a user through the in-app login screen, and help author repo-local config. Each subdirectory is a single skill with a `SKILL.md` using standard YAML frontmatter (`name`, `description`). The format is consumable by: @@ -13,10 +15,9 @@ Each subdirectory is a single skill with a `SKILL.md` using standard YAML frontm | Skill | When it applies | | --- | --- | -| [`using-mogplex-cli`](./using-mogplex-cli) | Umbrella skill. The agent needs to interact with the user's Mogplex workspace and no Mogplex MCP is configured. | -| [`mogplex-exec`](./mogplex-exec) | Run a one-off Mogplex task non-interactively and consume structured output. | -| [`mogplex-slash`](./mogplex-slash) | Discover and execute Mogplex slash commands from the shell. | -| [`mogplex-auth`](./mogplex-auth) | Verify or establish Mogplex authentication before running other commands. | +| [`using-mogplex-cli`](./using-mogplex-cli) | Umbrella skill. The user wants help driving the Mogplex cockpit. | +| [`mogplex-slash`](./mogplex-slash) | Recommend the right slash command for a user's intent. | +| [`mogplex-auth`](./mogplex-auth) | Walk the user through the in-app login flow and troubleshoot credentials. | ## Install into Claude Code @@ -46,7 +47,7 @@ mkdir -p .claude/skills && cp -R mogplex-skills/* .claude/skills/ import { query } from "@anthropic-ai/claude-agent-sdk"; const response = query({ - prompt: "Run /status against my Mogplex workspace", + prompt: "How do I switch models in Mogplex?", options: { settingSources: ["user", "project"], // Skills loaded from settingSources' `skills/` dirs automatically @@ -56,7 +57,7 @@ const response = query({ ## Design principles -- **CLI-first.** Skills assume `mogplex` is on PATH. They never instruct the agent to read or write credential files directly. -- **Auth preflight.** Every action-performing skill tells the agent to run `mogplex login status` first and surface a clear error if unauthenticated. -- **Structured output.** Skills prefer `--json` / `--jsonl` output for anything the agent has to parse. -- **No silent writes.** Any command that mutates state is called out explicitly so the agent asks the user before running it. +- **Guidance, not execution.** Skills tell the user what to do in the cockpit. They do not try to drive the TUI. +- **Auth handoff.** Auth lives in the cockpit's login screen. Skills recommend `/login` and explain env-var precedence. +- **Repo-local config is fair game.** Skills can help the user author `AGENTS.md` and `~/.mogplex/projects//permissions.json` — those are plain files. +- **No silent writes.** Anything that mutates user-owned state is recommended to the user, not done by the agent. diff --git a/skills/mogplex-auth/SKILL.md b/skills/mogplex-auth/SKILL.md index 66d2025..8c2debb 100644 --- a/skills/mogplex-auth/SKILL.md +++ b/skills/mogplex-auth/SKILL.md @@ -1,15 +1,15 @@ --- name: mogplex-auth -description: Verifies or establishes Mogplex CLI authentication before running other Mogplex commands. Use when `mogplex login status` shows no credential, a Mogplex command fails with an auth error, or the user asks to sign in, switch accounts, or inspect credential state. +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 preflight +# Mogplex auth -Every action against Mogplex needs a credential. Run this skill first whenever another skill tells you to "handle auth" or when a 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 (do not try to override this) +## Resolution order -Mogplex picks credentials in a fixed 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. @@ -26,117 +26,91 @@ Mogplex picks credentials in a fixed order: | Cohere | `COHERE_API_KEY` | | Vercel | `VERCEL_API_TOKEN` | -2. **Stored credentials** in `~/.mogplex/auth.json`. -3. **No credentials** → interactive prompt (TUI) or a clear failure in non-interactive contexts. +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. -## Check current state - -```bash -mogplex login status -``` - -Read the output, do not read the file. The command prints a safe summary and never reveals secret material. - -Possible outcomes: +## Establish auth -| `login status` says | What it means | -| --- | --- | -| `mogplex` credential present | Account-backed login is active (unless an env var overrides it). | -| a provider entry (e.g. `openai`) | Direct provider credential stored locally. | -| nothing stored | No disk credential — will fall back to env vars, else fail. | +### Preferred: account-backed browser login -Then sanity-check env vars in the current process: +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. ```bash -env | grep -E '^(MOGPLEX|ANTHROPIC|OPENAI|GOOGLE_GENERATIVE_AI|GROQ|MISTRAL|DEEPSEEK|XAI|COHERE|VERCEL)_' | sed 's/=.*/=/' +mogplex +# pick "Sign in with Mogplex" on the login screen ``` -Never print the full value. +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. -## Establish auth +Account-backed login unlocks synced model catalog, remote MCP server definitions, and hosted model access. -### Preferred: account-backed browser login +### Alternative: store a provider key in-app -The user runs this themselves — it opens a browser flow: +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`. -```bash -mogplex login -``` +Supported providers: Anthropic, OpenAI, Google, Groq, Mistral, DeepSeek, xAI, Cohere, Vercel AI Gateway. + +### Alternative: provider env var -Do not attempt to drive the browser. Hand off to the user with exactly this instruction and wait for them to confirm it completed. Then re-check: +For CI or ephemeral shells: ```bash -mogplex login status +export OPENAI_API_KEY=sk-... +mogplex ``` -Account-backed login unlocks synced model catalog, remote MCP server definitions, and hosted model access. +Do not write keys into shell rc files on the user's behalf. Suggest it; let them do it. -### Alternative: direct provider env var +## Sanity-check env vars (advisory) -For CI, ephemeral shells, or when the user does not want credentials written to disk: +You can sanity-check which env vars are set without printing values: ```bash -export OPENAI_API_KEY=sk-... -mogplex exec "..." +env | grep -E '^(MOGPLEX|ANTHROPIC|OPENAI|GOOGLE_GENERATIVE_AI|GROQ|MISTRAL|DEEPSEEK|XAI|COHERE|VERCEL)_' | sed 's/=.*/=/' ``` -Do not write keys into shell rc files on the user's behalf. Suggest it; let them do it. +Never echo a raw key. -### Alternative: stored provider key +## Troubleshooting -Inside a live session, the user runs `/login ` and pastes the key into the TUI. You cannot do this for them. +| 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). | -## Troubleshooting decision tree +## Sign out -``` -auth error from a mogplex command - │ - ▼ -run `mogplex login status` - │ - ▼ -credential shown? ── no ──► is an env var set for any provider? - │ │ - │ yes ──► env var may be malformed; print a - │ │ redacted preview and ask user to verify - │ no ──► ask user to run `mogplex login` - │ - yes - │ - ▼ -does the session use that credential? - │ - no ──► an env var is overriding it; unset it or clear it from the - │ current shell, then retry - yes ──► account login succeeded but hosted account lacks model access; - direct user to Mogplex web settings to add a provider key +```text +/logout # type in the composer ``` -## Signing out +Or, before attaching to a run: ```bash -# Inside a live session only: -/logout +mogplex --attach run_abc123 --logout ``` Three things to remember: -- Env vars still win on the next session. -- The current process may still hold the old adapter; restart for certainty. -- Logging out of Mogplex clears hosted state — model catalog sync and remote MCP definitions vanish locally. +- **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 `~/.mogplex/auth.json` directly. +- 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 `mogplex login` would give them an account-backed token instead. +- 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](../using-mogplex-cli/SKILL.md) -- [Authentication guide](https://mogplex.dev/cli/guides/authentication) +- [Authentication guide](https://www.mogplex.com/cli/guides/authentication) +- [Configuration and Flags](https://www.mogplex.com/cli/guides/configuration-and-flags) diff --git a/skills/mogplex-exec/SKILL.md b/skills/mogplex-exec/SKILL.md deleted file mode 100644 index fb73fa8..0000000 --- a/skills/mogplex-exec/SKILL.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -name: mogplex-exec -description: Runs a one-off, non-interactive Mogplex task from the shell and captures a final result with exit code. Use when the agent needs to execute a single prompt against the user's Mogplex account, run a slash command without opening the TUI, or pipe a Mogplex result into another tool. ---- - -# Mogplex exec mode - -`mogplex exec` runs a single task and exits. Use it whenever you need one result, not a conversation. - -## Preflight - -```bash -mogplex login status -``` - -If no credential is reported and no provider env var is set, stop and handle auth first (see `mogplex-auth`). - -## Two equivalent entrypoints - -```bash -mogplex exec "review the staged diff for regressions" -mogplex "review the staged diff for regressions" -``` - -Prefer the explicit `exec` form in scripts, CI, and agent-written commands — it will never be mistaken for a subcommand name if Mogplex adds new top-level commands later. - -## Structured output - -Use one of these flags when another program (including you, the agent) will parse the result: - -```bash -mogplex exec --json "summarize this repository" -mogplex exec --jsonl "review the staged diff for correctness issues" -mogplex exec --output json "…" -mogplex exec --output jsonl "…" -``` - -- `--json` → single final object when the task completes. -- `--jsonl` → one JSON object per event, streamed as the task runs. Best when you want to surface progress or react to intermediate events. - -Do not parse the default text output. It is tuned for humans and is not stable. - -## Slash commands in exec mode - -If the prompt starts with `/`, `exec` routes it through the slash registry: - -```bash -mogplex exec "/status" -mogplex exec "/mcp" -mogplex exec "/logs --lines=100" -mogplex exec "/skills list" -``` - -This is the canonical shell path to run a slash command. See [`mogplex-slash`](../mogplex-slash/SKILL.md) for discovery. - -## Local image paths - -Exec understands local image paths embedded in the prompt and forwards them as structured image inputs. Pass absolute paths when available: - -```bash -mogplex exec "describe /Users/me/Downloads/shot.png" -``` - -## Exit codes - -`mogplex exec` exits with the engine's final exit code. Treat non-zero as failure and surface the stderr output to the user rather than retrying blindly. - -## When NOT to use exec - -- Multi-turn conversation → instruct the user to run `mogplex` interactively instead. -- Anything that requires TUI input (plan confirmation, model picker) → use a live session. -- Long-running background work → prefer a Mogplex sandbox or a Trigger.dev-style job; exec is for synchronous, bounded tasks. - -## Good patterns - -```bash -# Run and capture to a file for further processing -mogplex exec --json "list the skills configured in this workspace" > /tmp/skills.json - -# Pipe JSONL events into a consumer -mogplex exec --jsonl "refactor the auth module" | jq -c 'select(.type=="tool_result")' - -# CI: fail the job if the review found regressions -if ! mogplex exec --json "/review" > review.json; then - cat review.json >&2 - exit 1 -fi -``` - -## Common mistakes - -- Parsing text output. Always pass `--json` or `--jsonl` when the caller is a program. -- Using `exec` for conversational work. One prompt, one result. -- Forgetting `--help` is the source of truth: `mogplex exec --help` reflects the installed version exactly. - -## See also - -- [mogplex-slash](../mogplex-slash/SKILL.md) — slash-command discovery and execution -- [mogplex-auth](../mogplex-auth/SKILL.md) — auth preflight -- [Exec mode guide](https://mogplex.dev/cli/guides/exec-mode) diff --git a/skills/mogplex-slash/SKILL.md b/skills/mogplex-slash/SKILL.md index 1b1a70f..23c4aec 100644 --- a/skills/mogplex-slash/SKILL.md +++ b/skills/mogplex-slash/SKILL.md @@ -1,99 +1,76 @@ --- name: mogplex-slash -description: Discovers and runs Mogplex slash commands from the shell via `mogplex slash list` and `mogplex exec "/..."`. Use when the user asks for a slash command like /status, /mcp, /skills, /sandbox, or /logs, or when a project stores commands in `.agents/commands/` or `~/.mogplex/commands/`. +description: Recommends the right Mogplex slash command for a user's intent and explains what each command does in the cockpit composer. Use when the user asks how to start, pause, kill, attach, model-switch, approve, or export a Mogplex run. --- # Mogplex slash commands -Slash commands are Mogplex's control surface — session control, local tooling, project scripts. They are NOT prompts sent to a model; they are registered actions. +The Mogplex CLI's command surface is **slash commands** in the cockpit composer. They run inside the interactive TUI — not from the shell. Use this skill to tell the user which slash command to type. -## Preflight +## Run control -```bash -mogplex login status -``` +| Intent | Slash command | +| --- | --- | +| Start a new run | `/run ` | +| Pause the active run | `/pause` | +| Resume a paused run | `/resume` | +| Cancel the active run | `/kill` | -Most slash commands require auth. If unauthenticated, resolve that first (see `mogplex-auth`). +## Surface inspection (open a drawer) -## Discover the registry +| Intent | Slash command | +| --- | --- | +| List agents on the active run | `/agents` | +| Per-MCP-server status | `/mcp` | +| Browse memory | `/memory` | +| Inspect a patch | `/diff` | +| Tokens, cost, projection | `/cost` | -Always inspect what actually exists in the current environment before depending on a command: +## Cockpit control -```bash -mogplex slash list --json -``` +| Intent | Slash command | +| --- | --- | +| Switch models mid-run | `/model` | +| Set permission mode | `/permissions ` | +| Show the resolved permission state | `/permissions` (no arg) | +| Serialize the run | `/export` | +| Open the command palette | `/help` | +| Clear the composer | `/clear` | +| Quit the cockpit | `/quit` (alias `/exit`) | -Why JSON: the registry is machine-readable there, with command metadata (name, description, scope). Do not hand-parse the text form. +## Auth -The registry includes three sources: +| Intent | Slash command | +| --- | --- | +| Open the in-app login flow | `/login` | +| Clear stored credentials | `/logout` | -1. **Built-ins** shipped with the CLI (`/status`, `/mcp`, `/skills`, `/sandbox`, `/logs`, `/model`, `/approvals`, `/compact`, `/clear`, `/init`, `/review`, `/config`, `/login`, `/logout`, `/quit`, `/help`). -2. **Project commands** from `.agents/commands/*.md` in the current repo. -3. **User commands** from `~/.mogplex/commands/*.md`. +## When the user says… -## Execute a slash command +| User says | You recommend | +| --- | --- | +| "Run a task on this repo" | Open `mogplex` and type `/run ` | +| "Pull up that run from CI" | `mogplex --attach ` | +| "Switch to Sonnet" | Type `/model` in the composer | +| "Approve all pending tool calls" | Open the Approval drawer (use Command Palette via `/help` if not visible) and approve from there | +| "Run unattended for the next hour" | `/permissions auto` — flag the safety implications | +| "Save what just happened" | `/export` and pick Markdown for human-readable, JSON/JSONL for tooling | +| "Get out" | Double-tap Ctrl+C within 1500ms, or `/quit` | -Use `exec` — the `slash` top-level command is only for inspection: +## What you cannot do -```bash -mogplex exec "/status" -mogplex exec "/mcp" -mogplex exec "/config list" -mogplex exec "/skills list" -mogplex exec "/logs --lines=100" -mogplex exec "/sandbox peek" -``` +- Run a slash command from the shell. There is no `mogplex slash` subcommand; slash commands only execute inside the running cockpit. +- See which slash commands are available without launching the cockpit. The registry is built into the binary; `/help` inside the cockpit shows the live list. +- Drive the cockpit on the user's behalf. Tell them what to type. -Pass `--json` when you need to parse the output: +## Safety -```bash -mogplex exec --json "/status" -mogplex exec --json "/skills list" -``` - -## High-value built-ins for agents - -| Command | Purpose | Safe to run without asking? | -| --- | --- | --- | -| `/status` | Model, usage, approval mode, cwd | yes, read-only | -| `/skills list` | Installed Mogplex skills | yes, read-only | -| `/mcp` | Configured MCP servers | yes, read-only | -| `/config list` | Current config values | yes, read-only | -| `/logs --lines=N` | Recent session errors | yes, logs are redacted | -| `/sandbox peek` | Inspect sandbox state | yes, read-only | -| `/config set …` | Mutate config | no, ask user first | -| `/sandbox kill` | Destroy sandbox state | no, ask user first | -| `/logout` | Remove stored credentials | no, ask user first | - -## Project-local slash commands - -When the user mentions a command you do not recognize (e.g. `/deploy-preview`), it is likely project-local. Check: - -```bash -ls .agents/commands/ 2>/dev/null -ls ~/.mogplex/commands/ 2>/dev/null -``` - -Each `.md` file in those directories registers a slash command. Read the file to understand what it does before executing it. - -## If a command is missing - -Work through this checklist before telling the user a command does not exist: - -1. `mogplex slash list --json` to confirm the registry in the current runtime. -2. Check `.agents/commands/` for a project-scoped override or addition. -3. Check `~/.mogplex/commands/` for a personal command. -4. The capability may exist only as a top-level command (e.g. `mogplex login`) rather than a slash command. Run `mogplex --help`. -5. The capability may be listed in `--help` but not yet implemented as a standalone subcommand. Try the slash form inside `exec "/..."`. - -## Common mistakes - -- Running `mogplex slash /status` (it does not execute slash commands). -- Assuming every `/` item you see in a doc is available in the user's build — always confirm with `slash list --json`. -- Running mutating slash commands (`/config set`, `/sandbox kill`, `/logout`) without user confirmation. +- `/permissions auto` is the explicit user opt-in to "no questions asked." Recommend `/permissions approval` (the default) for normal use. +- `/kill` cancels the active run immediately and interrupts in-flight tool calls. Confirm before suggesting it on a long run. +- `/logout` clears stored credentials including hosted Mogplex state (synced model catalog, remote MCP). Confirm before suggesting. ## See also -- [mogplex-exec](../mogplex-exec/SKILL.md) — the execution path for slash commands -- [mogplex-auth](../mogplex-auth/SKILL.md) — auth preflight -- [Slash commands guide](https://mogplex.dev/cli/guides/slash-commands) +- [using-mogplex-cli](../using-mogplex-cli/SKILL.md) +- [mogplex-auth](../mogplex-auth/SKILL.md) +- [Slash command reference](https://www.mogplex.com/cli/commands) diff --git a/skills/using-mogplex-cli/SKILL.md b/skills/using-mogplex-cli/SKILL.md index 8095c8a..5a8def2 100644 --- a/skills/using-mogplex-cli/SKILL.md +++ b/skills/using-mogplex-cli/SKILL.md @@ -1,40 +1,44 @@ --- name: using-mogplex-cli -description: Umbrella skill for driving a user's Mogplex workspace through the `mogplex` CLI when no Mogplex MCP server is available. Use when the user asks to run a Mogplex workspace action, execute a Mogplex slash command, or use Mogplex skills, agents, or memories from outside the Mogplex web app. Also triggers on mentions of "mogplex", ".agents/commands/", or "~/.mogplex/". +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/". --- # Using the Mogplex CLI -Mogplex exposes its workspace, slash-command registry, agent roster, skills, and memories through a local CLI (`mogplex`). When a Mogplex MCP server is not available, use the CLI as the integration surface instead of asking the user to paste tokens or configure servers manually. +The Mogplex CLI is an interactive cockpit. There is no headless `exec` surface — agents cannot drive the TUI directly. Use this skill to **advise** the user on what to run, what to type in the composer, and what to put in repo-local config files. ## When to use this skill -- The user references their Mogplex account, workspace, agents, skills, or memories. -- The user asks you to run a `/slash` command that belongs to Mogplex (`/status`, `/mcp`, `/skills`, `/sandbox`, `/logs`, etc.). -- The user asks you to run a project-local slash command stored in `.agents/commands/` or a personal one in `~/.mogplex/commands/`. -- The task would normally be an MCP tool call against Mogplex but no such MCP is connected. +- 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 — always run first +## Preflight -Before any command that talks to Mogplex, verify the CLI is installed and authenticated. The install check must gate the auth check — do not continue if `mogplex` is not on `PATH`: +Confirm the CLI is installed before recommending it: ```bash -command -v mogplex >/dev/null 2>&1 || { echo "mogplex CLI not installed — ask the user to install it first"; exit 1; } -mogplex login status +command -v mogplex >/dev/null 2>&1 || echo "mogplex CLI not installed" ``` -If the first line fails, stop and tell the user to install the CLI (point them at [Installation](https://mogplex.dev/cli/installation)) before running anything else. If `login status` runs but shows no stored credential and no provider env var is set, follow [`mogplex-auth`](../mogplex-auth/SKILL.md). Do not attempt to edit `~/.mogplex/auth.json` directly. +If it's missing, point the user at https://www.mogplex.com/cli/installation. -## Core command map +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. -| Intent | Command | Reference skill | -| --- | --- | --- | -| Run a one-off prompt, get a final result | `mogplex exec ""` | [mogplex-exec](../mogplex-exec/SKILL.md) | -| Get machine-readable output | `mogplex exec --json ""` | [mogplex-exec](../mogplex-exec/SKILL.md) | -| List available slash commands | `mogplex slash list --json` | [mogplex-slash](../mogplex-slash/SKILL.md) | -| Run a slash command non-interactively | `mogplex exec "/status"` | [mogplex-slash](../mogplex-slash/SKILL.md) | -| Check auth state | `mogplex login status` | [mogplex-auth](../mogplex-auth/SKILL.md) | -| Start a live session | `mogplex` | — (hand off to user) | +## Core guidance map + +| Intent | What to tell the user | +| --- | --- | +| Start a run | Launch `mogplex`, then type `/run ` in the composer. | +| Attach to an in-flight run | `mogplex --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 https://www.mogplex.com/cli/commands. ## Decision flow @@ -42,38 +46,43 @@ If the first line fails, stop and tell the user to install the CLI (point them a user wants Mogplex action │ ▼ -is it conversational / multi-turn? ── yes ──► tell user to run `mogplex` themselves; - │ do not try to drive a TUI - no +is the cockpit already open in the user's terminal? + │ + no ──► tell them to run `mogplex` (or `mogplex --attach `) + yes + │ ▼ -is it a slash command (/foo)? ── yes ──► mogplex exec "/foo" (see mogplex-slash) +is it a slash command? ── yes ──► tell user to type "/" in the composer │ no ▼ -is it a one-off prompt? ── yes ──► mogplex exec --json "..." (see mogplex-exec) +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) ``` -## Reading output +## What you cannot do -- Text output is for humans. Do not parse it. -- Use `--json` for a single final object, `--jsonl` for streaming events. -- Top-level flags `--output text|json|jsonl` also work. Pick one and stick with it per invocation. +- Drive the TUI from a script. The CLI is interactive-only. +- 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. -## Known limits +## What you **can** do -- `mogplex exec` cannot hold a conversation. If the user says "then do X", run a new `exec` with the follow-up phrased as a complete task, or hand off to an interactive session. -- The `slash` top-level command currently only lists the registry. Execution goes through `exec "/..."`. -- Some capabilities show up in `mogplex --help` but are not real top-level commands yet; they exist only as slash commands. Trust `mogplex slash list --json` over help text. -- The agent cannot read `~/.mogplex/auth.json`. All credential state must be inspected via `mogplex login status`. +- Author `AGENTS.md` at the repo root with stable repo guidance (build commands, conventions, layout). +- Author `~/.mogplex/projects//permissions.json` with `allow` / `deny` / `ask` rules — see https://www.mogplex.com/cli/concepts/permissions for the schema. +- Recommend env-var escape hatches (`MOGPLEX_TRANSPORT`, `MOGPLEX_ATTACH_RUN_ID`, provider keys) — see https://www.mogplex.com/cli/guides/configuration-and-flags. ## Safety -- Any slash command that mutates state (`/config set`, `/logout`, `/sandbox kill`) should be confirmed with the user before running. Mogplex does not sandbox the CLI itself. -- Prefer provider env vars (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `MOGPLEX_API_KEY`, …) over writing credentials to disk in CI contexts. -- Logs at `~/.mogplex/logs/.jsonl` redact secrets by default. Do not export or share them without reviewing. +- 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 -- [Exec mode guide](https://mogplex.dev/cli/guides/exec-mode) -- [Slash commands guide](https://mogplex.dev/cli/guides/slash-commands) -- [Authentication guide](https://mogplex.dev/cli/guides/authentication) +- [mogplex-slash](../mogplex-slash/SKILL.md) — recommending slash commands +- [mogplex-auth](../mogplex-auth/SKILL.md) — guiding the login flow +- [Slash Commands guide](https://www.mogplex.com/cli/guides/slash-commands) From 97cd2d5ac0055d79e613fc2b0e78958d50080125 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 27 Apr 2026 16:04:11 -0400 Subject: [PATCH 2/3] docs(cli): address PR 29 review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add missing `import { Callout }` to cli/skills/index.mdx so the guidance Callout renders. - Replace stale "drive Mogplex through the CLI" copy on the Skills card in cli/index.mdx with guidance-only framing. - Spell out the "project rules can only loosen" footgun in cli/concepts/permissions.mdx (with a warn Callout) and in cli/guides/project-commands.mdx — a project `deny` cannot tighten what global or the mode default already allows. - Make the install preflight in using-mogplex-cli skill fail-fast on a missing binary (`exit 1` instead of `echo`), so skill-aware hosts gate correctly. Mirrored in both the canonical SKILL.md and the docs page. Co-Authored-By: Claude Opus 4.7 (1M context) --- content/docs/cli/concepts/permissions.mdx | 10 +++++++++- content/docs/cli/guides/project-commands.mdx | 2 +- content/docs/cli/index.mdx | 2 +- content/docs/cli/skills/index.mdx | 2 ++ content/docs/cli/skills/using-mogplex-cli.mdx | 4 ++-- skills/using-mogplex-cli/SKILL.md | 4 ++-- 6 files changed, 17 insertions(+), 7 deletions(-) diff --git a/content/docs/cli/concepts/permissions.mdx b/content/docs/cli/concepts/permissions.mdx index 3c16c6b..52b6de0 100644 --- a/content/docs/cli/concepts/permissions.mdx +++ b/content/docs/cli/concepts/permissions.mdx @@ -3,6 +3,8 @@ title: Permissions description: Two-mode permission model — `approval` and `auto` — with global and per-project rules layered on disk. --- +import { Callout } from 'fumadocs-ui/components/callout'; + The CLI's permission system has two halves: 1. A **mode** that sets the baseline: `approval` (default, asks before touching the workspace) or `auto` (run anything without asking). @@ -59,7 +61,13 @@ Each rule has one of three sources: `default`, `global`, or `project`. The resol 1. **Built-in defaults** for the active mode. 2. **Global rules** from `~/.mogplex/permissions.json`. -3. **Project rules** from `~/.mogplex/projects//permissions.json` — projects can be **more permissive** than the global file. +3. **Project rules** from `~/.mogplex/projects//permissions.json`. + +For each pattern, the most permissive level wins: `allow` beats `ask` beats `deny`. A `deny` only takes effect when no other layer (mode default, global, or project) marks the same pattern `allow` or `ask`. In other words, a layer can only **loosen** what an outer layer already restricts — it cannot tighten it. + + + **A project `deny` cannot override a global `allow`.** If `~/.mogplex/permissions.json` allows `bash:rm -rf *`, adding the same pattern to a project `deny` list will not block it. To restrict a pattern in a single repo, remove it from the global `allow` list and re-add it as `allow` only in the projects where it should run. This applies to mode defaults too: a global file cannot tighten what the active mode's built-in defaults already allow. + The slash status output (`/permissions`) explains why a pattern landed in `allow` vs `ask` vs `deny`, including which file it came from. diff --git a/content/docs/cli/guides/project-commands.mdx b/content/docs/cli/guides/project-commands.mdx index f0a6b34..3032a72 100644 --- a/content/docs/cli/guides/project-commands.mdx +++ b/content/docs/cli/guides/project-commands.mdx @@ -34,7 +34,7 @@ Permission rules can be set globally or per-project. The project file lives at: ~/.mogplex/projects//permissions.json ``` -It can override the mode and add `allow` / `deny` / `ask` rules that are layered **on top of** the global rules. Projects can be more permissive than the global file. +It can override the mode and add `allow` / `deny` / `ask` rules that are layered **on top of** the global rules. Projects can only be **more permissive** than the global file — a project `deny` cannot tighten something the global file (or the mode default) already allows. See [Concepts → Permissions](/cli/concepts/permissions#how-rules-resolve) for the resolver rules. Example — make a single sandbox repo run unattended while the global policy stays strict: diff --git a/content/docs/cli/index.mdx b/content/docs/cli/index.mdx index a9a3ff3..d15d8b4 100644 --- a/content/docs/cli/index.mdx +++ b/content/docs/cli/index.mdx @@ -19,7 +19,7 @@ diffs · cost · tokens · model routing · approval gates · process c - + ## Where the CLI fits diff --git a/content/docs/cli/skills/index.mdx b/content/docs/cli/skills/index.mdx index 1482b66..60fa82f 100644 --- a/content/docs/cli/skills/index.mdx +++ b/content/docs/cli/skills/index.mdx @@ -3,6 +3,8 @@ title: Skills description: Agent Skills that teach external agents (Claude Code, Claude Agent SDK, Cursor, opencode) how to guide a user through the Mogplex CLI cockpit. --- +import { Callout } from 'fumadocs-ui/components/callout'; + Mogplex ships a set of [Anthropic Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) that teach a skill-aware agent how to help users drive the Mogplex CLI. diff --git a/content/docs/cli/skills/using-mogplex-cli.mdx b/content/docs/cli/skills/using-mogplex-cli.mdx index bcad985..3898f7a 100644 --- a/content/docs/cli/skills/using-mogplex-cli.mdx +++ b/content/docs/cli/skills/using-mogplex-cli.mdx @@ -29,10 +29,10 @@ The Mogplex CLI is an interactive cockpit. There is no headless `exec` surface Confirm the CLI is installed before recommending it: ```bash -command -v mogplex >/dev/null 2>&1 || echo "mogplex CLI not installed" +command -v mogplex >/dev/null 2>&1 || { echo "mogplex CLI not installed" >&2; exit 1; } ``` -If it's missing, point the user at [Installation](https://www.mogplex.com/cli/installation). +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. diff --git a/skills/using-mogplex-cli/SKILL.md b/skills/using-mogplex-cli/SKILL.md index 5a8def2..4a94496 100644 --- a/skills/using-mogplex-cli/SKILL.md +++ b/skills/using-mogplex-cli/SKILL.md @@ -18,10 +18,10 @@ The Mogplex CLI is an interactive cockpit. There is no headless `exec` surface Confirm the CLI is installed before recommending it: ```bash -command -v mogplex >/dev/null 2>&1 || echo "mogplex CLI not installed" +command -v mogplex >/dev/null 2>&1 || { echo "mogplex CLI not installed" >&2; exit 1; } ``` -If it's missing, point the user at https://www.mogplex.com/cli/installation. +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 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. From dfd5d0afafc0e9c217a5361c41881ae6ef4c713d Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Mon, 27 Apr 2026 16:15:15 -0400 Subject: [PATCH 3/3] docs(cli): second pass on PR 29 review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add missing `import { Callout }` to cli/quickstart.mdx (build was rendering, but the import is required for consistency and to avoid silent fallthrough on future fumadocs upgrades). - Reword the on-disk layout comment in cli/concepts/permissions.mdx from `# project (overrides)` to `# project-scoped (can only loosen)` so skim-readers don't form the wrong mental model before hitting the resolver section. - Reword the mogplex-slash skill description to stop pairing "attach" with slash-command verbs — attach is `mogplex --attach `, not `/attach`. Mirrored in canonical SKILL.md and the docs page. - Cross-link the deprecated `CODEX_HOME` note from the auth guide so users with stale env vars find the migration path without leaving the page. Co-Authored-By: Claude Opus 4.7 (1M context) --- content/docs/cli/concepts/permissions.mdx | 4 ++-- content/docs/cli/guides/authentication.mdx | 2 +- content/docs/cli/quickstart.mdx | 2 ++ content/docs/cli/skills/mogplex-slash.mdx | 2 +- skills/mogplex-slash/SKILL.md | 2 +- 5 files changed, 7 insertions(+), 5 deletions(-) diff --git a/content/docs/cli/concepts/permissions.mdx b/content/docs/cli/concepts/permissions.mdx index 52b6de0..74ad3ab 100644 --- a/content/docs/cli/concepts/permissions.mdx +++ b/content/docs/cli/concepts/permissions.mdx @@ -28,11 +28,11 @@ The new mode applies on the next `/run` (the process transport reads permissions ## On-disk layout -Two files, in order of precedence: +Two files, in scope order. Both layer additively — see [How rules resolve](#how-rules-resolve) for what wins when they disagree. ``` ~/.mogplex/permissions.json # global -~/.mogplex/projects//permissions.json # project (overrides) +~/.mogplex/projects//permissions.json # project-scoped (can only loosen) ``` Both follow the same shape: diff --git a/content/docs/cli/guides/authentication.mdx b/content/docs/cli/guides/authentication.mdx index da23415..86e36fc 100644 --- a/content/docs/cli/guides/authentication.mdx +++ b/content/docs/cli/guides/authentication.mdx @@ -26,7 +26,7 @@ When the CLI starts up, it resolves credentials in this order: | Cohere | `COHERE_API_KEY` | | Vercel | `VERCEL_API_TOKEN` | -2. **Stored credentials** in `~/.mogplex/auth.json` (mode `0600`). +2. **Stored credentials** in `~/.mogplex/auth.json` (mode `0600`). If you previously used Codex and have `CODEX_HOME` set, the CLI still honors it but it is deprecated — set `MOGPLEX_HOME` instead. See [Configuration and Flags → Storage](/cli/guides/configuration-and-flags#storage). 3. **No credentials** → the in-app **login screen** appears (or, in non-interactive contexts, a clear failure). diff --git a/content/docs/cli/quickstart.mdx b/content/docs/cli/quickstart.mdx index 566a4e4..d49fc96 100644 --- a/content/docs/cli/quickstart.mdx +++ b/content/docs/cli/quickstart.mdx @@ -3,6 +3,8 @@ title: Quickstart description: Install, sign in, start a run, and confirm the CLI cockpit is working end-to-end. --- +import { Callout } from 'fumadocs-ui/components/callout'; + The shortest useful loop: 1. install the binary diff --git a/content/docs/cli/skills/mogplex-slash.mdx b/content/docs/cli/skills/mogplex-slash.mdx index 46ffbf4..5349268 100644 --- a/content/docs/cli/skills/mogplex-slash.mdx +++ b/content/docs/cli/skills/mogplex-slash.mdx @@ -11,7 +11,7 @@ This page mirrors the canonical `SKILL.md` at [`skills/mogplex-slash/SKILL.md`]( ```yaml name: mogplex-slash -description: Recommends the right Mogplex slash command for a user's intent and explains what each command does in the cockpit composer. Use when the user asks how to start, pause, kill, attach, model-switch, approve, or export a Mogplex run. +description: Recommends the right Mogplex slash command for a user's intent and explains what each command does in the cockpit composer. Use when the user asks how to start, pause, kill, or control a Mogplex run, attach to one from CI, switch models, manage approvals, or export. ``` ## Body diff --git a/skills/mogplex-slash/SKILL.md b/skills/mogplex-slash/SKILL.md index 23c4aec..1f4ee61 100644 --- a/skills/mogplex-slash/SKILL.md +++ b/skills/mogplex-slash/SKILL.md @@ -1,6 +1,6 @@ --- name: mogplex-slash -description: Recommends the right Mogplex slash command for a user's intent and explains what each command does in the cockpit composer. Use when the user asks how to start, pause, kill, attach, model-switch, approve, or export a Mogplex run. +description: Recommends the right Mogplex slash command for a user's intent and explains what each command does in the cockpit composer. Use when the user asks how to start, pause, kill, or control a Mogplex run, attach to one from CI, switch models, manage approvals, or export. --- # Mogplex slash commands