Configuration and Flags

Understand CLI launcher flags, environment-variable escape hatches, config.toml layers, and where Mogplex stores local state.

The CLI is configured primarily in-app, with a small launcher flag surface, environment-variable escape hatches, and advanced config.toml layers.

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.

Launcher flags

Flag	What it does
`--attach <runId>`	Attach to an in-flight run via the daemon transport. See 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).

Most day-to-day control still happens in-app through slash commands, drawers, the login screen, model picker, and permissions picker.

Environment variables

Auth escape hatches

See the table in Authentication → Resolution order. Provider env vars are compatibility and development escape hatches; normal Mogplex usage should start with account-backed login.

Transport selection

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 <runId>`.

See Concepts → Transports for the selection rules.

Storage

Variable	Effect
`MOGPLEX_HOME`	Override the home directory location (default `~/.mogplex/`).
`AGENTS_HOME`	Optional user command home. When set, slash-command discovery checks `$AGENTS_HOME/commands/` before `$MOGPLEX_HOME/commands/`.
`CODEX_HOME`	Deprecated fallback; use `MOGPLEX_HOME` instead.

`config.toml`

Mogplex can read two TOML config layers:

Path	Scope
`$MOGPLEX_HOME/config.toml`	User-level advanced defaults.
`./.mogplex/config.toml`	Project-level advanced defaults.

The runtime loader merges built-in defaults, user config, project config, environment-derived values, and launcher overrides. In normal interactive use, prefer the visible cockpit controls first:

/login and the login screen for account credentials
/permissions for permission mode
/model for current model selection
/mcp for MCP inspection and sync actions

Use config.toml when you need persistent advanced defaults that are not better owned by the current session UI.

Local state on disk

Path	Contents
`~/.mogplex/auth.json`	Mogplex token and compatibility auth state (mode `0600`).
`~/.mogplex/config.toml`	User-level advanced config.
`~/.mogplex/permissions.json`	Global permission mode and rules.
`./.mogplex/config.toml`	Project-level advanced config.
`~/.mogplex/projects/<repo-slug>/permissions.json`	Per-project permission overrides.
`~/.mogplex/logs/<session-id>.jsonl`	Structured session logs (secrets redacted).
`~/.mogplex/bin/mogplex`	The CLI binary (default install location).

All Mogplex-owned files use restrictive modes (0600 for files, 0700 for directories) so credentials and policy stay private.

Configuring permissions

Permissions are managed by editing the JSON files above or by using /permissions <mode> in the composer. See Concepts → Permissions for the on-disk schema and resolution rules.

Configuring MCP

MCP servers are configured in Web Settings and synced to the CLI when you are signed in to Mogplex. The CLI's MCP drawer surfaces what is configured and supports sync or reauth actions.

Read Connections and MCP for the full connection model.