# Configuration and Flags (/cli/guides/configuration-and-flags)





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

<Callout>
  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.
</Callout>

## Launcher flags [#launcher-flags]

| Flag               | What it does                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| `--attach <runId>` | 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).                                 |

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

## Environment variables [#environment-variables]

### Auth escape hatches [#auth-escape-hatches]

See the table in [Authentication → Resolution order](/cli/guides/authentication#resolution-order).
Provider env vars are compatibility and development escape hatches; normal
Mogplex usage should start with account-backed login.

### Transport selection [#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](/cli/concepts/transports) for the selection rules.

### Storage [#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` [#configtoml]

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 [#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 [#configuring-permissions]

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

## Configuring MCP [#configuring-mcp]

MCP servers are configured in [Web Settings](/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](/configure-and-extend/connections-and-mcp) for the
full connection model.

## See also [#see-also]

* [Authentication](/cli/guides/authentication)
* [Concepts → Transports](/cli/concepts/transports)
* [Concepts → Permissions](/cli/concepts/permissions)
* [Connections and MCP](/configure-and-extend/connections-and-mcp)