cli.md
1 # CLI Guide 2 3 mureo provides a command-line interface for setup, authentication, and environment configuration. Ad platform operations are handled through MCP tools used by AI agents, not through the CLI. 4 5 ## Installation 6 7 ```bash 8 pip install mureo 9 ``` 10 11 ## Command Structure 12 13 ``` 14 mureo <subcommand-group> <command> [options] 15 ``` 16 17 | Group | Description | 18 |-------|-------------| 19 | `setup` | Environment setup (Claude Code, Cursor, Codex, Gemini) | 20 | `auth` | Authentication management | 21 | `rollback` | Inspect reversible actions recorded in STATE.json | 22 23 Run `mureo --help` to see all available groups. 24 25 ## Setup Commands 26 27 ### Claude Code (recommended) 28 29 ```bash 30 mureo setup claude-code 31 ``` 32 33 One-command setup that handles: 34 1. Google Ads / Meta Ads authentication (OAuth) 35 2. MCP server configuration (`~/.claude/settings.json`) 36 3. Credential guard (blocks AI agents from reading secrets) 37 4. Workflow commands (`~/.claude/commands/`) 38 5. Skills (`~/.claude/skills/`) 39 40 Use `--skip-auth` to install commands, skills, MCP config, and credential guard without running OAuth: 41 42 ```bash 43 mureo setup claude-code --skip-auth 44 ``` 45 46 ### Cursor 47 48 ```bash 49 mureo setup cursor 50 ``` 51 52 Sets up authentication and MCP configuration for Cursor. Cursor does not support workflow commands or skills. 53 54 ### OpenAI Codex CLI 55 56 ```bash 57 mureo setup codex 58 ``` 59 60 Full parity with Claude Code. Installs: 61 62 1. MCP server configuration as a tagged `[mcp_servers.mureo]` block in `~/.codex/config.toml` (append-only; refuses to overwrite an untagged pre-existing `[mcp_servers.mureo]`). 63 2. Credential guard — PreToolUse hooks in `~/.codex/hooks.json` (Read + Bash) that block any tool call that would touch `~/.mureo/credentials*`. 64 3. Workflow commands as **Codex skills** at `~/.codex/skills/<command>/SKILL.md` with YAML frontmatter. Users invoke them with `$daily-check`, `$onboard`, … or via the `/skills` picker. (Codex CLI 0.117.0+ no longer surfaces `~/.codex/prompts/`, per [openai/codex#15941](https://github.com/openai/codex/issues/15941); re-running `mureo setup codex` also deletes stale prompt files that mureo owns, while leaving user-authored prompts alone.) 65 4. Shared mureo skills at `~/.codex/skills/mureo-*/`. 66 67 `--skip-auth` is supported and is auto-implied under a non-TTY subprocess (e.g. an AI agent's Bash tool) so the command can never hang on a confirm prompt. 68 69 ### Gemini CLI 70 71 ```bash 72 mureo setup gemini 73 ``` 74 75 Registers mureo as a Gemini CLI extension at `~/.gemini/extensions/mureo/gemini-extension.json` with `mcpServers.mureo` and `contextFileName: CONTEXT.md`. Operator-added top-level keys (`excludeTools`, renamed `contextFileName`) and extra `mcpServers` entries are preserved across reinstall. Gemini CLI does not support PreToolUse hooks or the `.md` command format, so those layers are not installed. 76 77 ### Per-platform flags (all `setup …` subcommands) 78 79 Every setup subcommand accepts: 80 81 - `--skip-auth` — install MCP config (+ guard / commands / skills, where supported) without running OAuth. Auto-implied under a non-TTY invocation. 82 - `--google-ads` / `--no-google-ads` — override the "configure Google Ads?" prompt. 83 - `--meta-ads` / `--no-meta-ads` — override the "configure Meta Ads?" prompt. 84 85 Passing the platform flags alongside `--skip-auth` (or under a non-TTY) emits a warning and is ignored. 86 87 ## Authentication Commands 88 89 ```bash 90 # Show authentication status for all platforms 91 mureo auth status 92 93 # Check Google Ads credentials (masked output) 94 mureo auth check-google 95 96 # Check Meta Ads credentials (masked output) 97 mureo auth check-meta 98 99 # Interactive authentication wizard (terminal prompts) 100 mureo auth setup 101 102 # Browser-based authentication wizard (no terminal input needed) 103 mureo auth setup --web 104 ``` 105 106 `mureo auth setup` has two flavours: 107 108 - **Terminal mode (default)** — walks you through Google Ads / Meta Ads setup via stdin prompts. Best when you're comfortable with pasting secrets into a terminal. 109 - **`--web` mode** — starts a local HTTP wizard on `http://127.0.0.1:<random-port>/`, opens it in your browser, and asks for the same secrets via an HTML form. Recommended when you were pointed here by an AI agent (Claude Code, etc.) that cannot itself receive terminal input safely. Every field has a deep link next to it so you know where to fetch the Developer Token / App ID / Secret from Google's or Meta's console. 110 111 Both modes end at the same destination: `~/.mureo/credentials.json` is populated and Claude Desktop (or any other MCP client) picks up mureo after a restart. 112 113 See [authentication.md](authentication.md) for details on credentials. 114 115 ## Rollback Commands 116 117 `mureo rollback` lets an operator inspect reversible actions recorded in `STATE.json`. The commands are read-only — executing a rollback still goes through the MCP dispatcher so it re-enters the same policy gate as forward actions. 118 119 ```bash 120 # List every state-changing action log entry with the planner's verdict. 121 mureo rollback list 122 123 # Limit to one platform. 124 mureo rollback list --platform google_ads 125 126 # Inspect a specific entry (index as shown by `list`). 127 mureo rollback show 3 128 129 # Point at a non-default STATE.json location. 130 mureo rollback list --state-file /path/to/STATE.json 131 ``` 132 133 `list` output: 134 135 ``` 136 # timestamp platform status action 137 ------------------------------------------------------------------------ 138 0 2026-04-15T10:00:00 google_ads supported update_budget 139 2 2026-04-13T12:00:00 meta_ads partial * update_status 140 3 2026-04-12T08:00:00 google_ads not_supported update_budget 141 ``` 142 143 `*` marks entries with caveats (e.g. "spend during pause is not refundable"); run `mureo rollback show <#>` for the full detail. 144 145 `show` emits JSON for scripting: 146 147 ```json 148 { 149 "index": 0, 150 "source_timestamp": "2026-04-15T10:00:00", 151 "source_action": "update_budget", 152 "platform": "google_ads", 153 "status": "supported", 154 "operation": "google_ads.budgets.update", 155 "params": {"budget_id": "222", "amount_micros": 10000000000}, 156 "caveats": [], 157 "notes": "" 158 } 159 ``` 160 161 A rollback entry only appears when the agent wrote a `reversible_params` hint at the time of the original action. Operations outside the planner's allow-list, or hints that smuggle unexpected parameter keys, are rejected at plan time — see [architecture.md](architecture.md#defense-in-depth-for-ai-agents) for the threat model. 162 163 ### Applying a rollback 164 165 Execution is not a CLI command — it is the `rollback.apply` MCP tool. The CLI is intentionally read-only; applying a rollback from the CLI would bypass the authentication, rate-limiting, and input-validation gate that every forward action passes through. To apply a rollback, ask the agent to call `rollback.apply` with the index shown by `mureo rollback list`: 166 167 ``` 168 You: "Roll back action #0." 169 Agent: rollback.plan.get → previews the reversal. 170 Agent: rollback.apply({index: 0, confirm: true}) → dispatches. 171 ``` 172 173 `confirm` must be the literal boolean `true` (truthy non-booleans are refused). On success the executor appends a new log entry tagged `rollback_of=<index>`; a second apply of the same index is refused. `state_file` resolves strictly inside the MCP server's current working directory — `..`-traversal and symlink escape are refused so an attacker-crafted `STATE.json` elsewhere on disk cannot be used as the reversal source. 174 175 ## Output Format 176 177 Authentication check commands output JSON to stdout: 178 179 ```bash 180 mureo auth check-google | jq . 181 ``` 182 183 ```json 184 { 185 "developer_token": "***************abcd", 186 "client_id": "123456789.apps.googleusercontent.com", 187 "client_secret": "***************wxyz", 188 "refresh_token": "***************efgh", 189 "login_customer_id": "1234567890" 190 } 191 ``` 192 193 Secrets are masked, showing only the last 4 characters. 194 195 ## Ad Platform Operations 196 197 Ad platform operations (listing campaigns, creating ads, analyzing performance, etc.) are available through **MCP tools**, not the CLI. AI agents (Claude Code, Cursor, Codex, Gemini) call these tools directly. 198 199 See [mcp-server.md](mcp-server.md) for the full tool reference.