CLI reference

Mirrored from the OSS repo

This page is auto-synced from docs/cli.md in github.com/logly/mureo. Edits belong in the OSS repo — this site is a presentation layer.

CLI Guide

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.

Installation

pip install mureo

Command Structure

mureo <subcommand-group> <command> [options]

Group	Description
setup	Environment setup (Claude Code, Cursor, Codex, Gemini)
auth	Authentication management
rollback	Inspect reversible actions recorded in STATE.json

Run mureo --help to see all available groups.

Setup Commands

Claude Code (recommended)

mureo setup claude-code

One-command setup that handles:

1. Google Ads / Meta Ads authentication (OAuth)
2. MCP server configuration (~/.claude/settings.json)
3. Credential guard (blocks AI agents from reading secrets)
4. Workflow commands (~/.claude/commands/)
5. Skills (~/.claude/skills/)

Use --skip-auth to install commands, skills, MCP config, and credential guard without running OAuth:

mureo setup claude-code --skip-auth

Cursor

mureo setup cursor

Sets up authentication and MCP configuration for Cursor. Cursor does not support workflow commands or skills.

OpenAI Codex CLI

mureo setup codex

Full parity with Claude Code. Installs:

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]).
2. Credential guard — PreToolUse hooks in ~/.codex/hooks.json (Read + Bash) that block any tool call that would touch ~/.mureo/credentials*.
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; re-running mureo setup codex also deletes stale prompt files that mureo owns, while leaving user-authored prompts alone.)
4. Shared mureo skills at ~/.codex/skills/mureo-*/.

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

Gemini CLI

mureo setup gemini

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.

Per-platform flags (all setup … subcommands)

Every setup subcommand accepts:

• --skip-auth — install MCP config (+ guard / commands / skills, where supported) without running OAuth. Auto-implied under a non-TTY invocation.
• --google-ads / --no-google-ads — override the “configure Google Ads?” prompt.
• --meta-ads / --no-meta-ads — override the “configure Meta Ads?” prompt.

Passing the platform flags alongside --skip-auth (or under a non-TTY) emits a warning and is ignored.

Authentication Commands

# Show authentication status for all platforms
mureo auth status

# Check Google Ads credentials (masked output)
mureo auth check-google

# Check Meta Ads credentials (masked output)
mureo auth check-meta

# Interactive authentication wizard (terminal prompts)
mureo auth setup

# Browser configuration UI (no terminal input needed) — supersedes the
# removed `mureo auth setup --web`
mureo configure

Credential entry has two front doors:

• mureo auth setup (terminal, default) — walks you through Google Ads / Meta Ads setup via stdin prompts. Best when you’re comfortable pasting secrets into a terminal.
• mureo configure (browser) — starts a local UI on http://127.0.0.1:<random-port>/ and opens your browser. It does the same credential entry (HTML forms + standard OAuth redirects, each field deep-linked to the right console) and the rest of Claude setup: pick the host, run basic setup, add official MCP providers, scaffold Demo/BYOD. Recommended when an AI agent (Claude Code, etc.) pointed you here, or you just prefer a GUI. (The old mureo auth setup --web was removed and folded into mureo configure.)

Both end at the same destination: ~/.mureo/credentials.json is populated and Claude (or any other MCP client) picks up mureo after a restart.

See authentication.md for details on credentials.

Rollback Commands

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.

# List every state-changing action log entry with the planner's verdict.
mureo rollback list

# Limit to one platform.
mureo rollback list --platform google_ads

# Inspect a specific entry (index as shown by `list`).
mureo rollback show 3

# Point at a non-default STATE.json location.
mureo rollback list --state-file /path/to/STATE.json

list output:

  #  timestamp            platform    status           action
------------------------------------------------------------------------
  0  2026-04-15T10:00:00  google_ads  supported        update_budget
  2  2026-04-13T12:00:00  meta_ads    partial       *  update_status
  3  2026-04-12T08:00:00  google_ads  not_supported    update_budget

* marks entries with caveats (e.g. “spend during pause is not refundable”); run mureo rollback show <#> for the full detail.

show emits JSON for scripting:

{
  "index": 0,
  "source_timestamp": "2026-04-15T10:00:00",
  "source_action": "update_budget",
  "platform": "google_ads",
  "status": "supported",
  "operation": "google_ads_budget_update",
  "params": {"budget_id": "222", "amount_micros": 10000000000},
  "caveats": [],
  "notes": ""
}

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 for the threat model.

Applying a rollback

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:

You: "Roll back action #0."
Agent: rollback_plan_get → previews the reversal.
Agent: rollback_apply({index: 0, confirm: true}) → dispatches.

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.

BYOD Commands (Bring Your Own Data)

Analyse your ad-account data locally without OAuth or a developer token. The importer accepts a single XLSX produced by either the mureo Google Ads Script (scripts/sheet-template/google-ads-script.js) or a Meta Ads Manager Saved Report. Activated automatically when ~/.mureo/byod/manifest.json registers a platform — no --byod flag exists. Adapter dispatch is by workbook header signature, so no --google-ads / --meta-ads flags on import are needed. See docs/byod.md for the full walkthrough.

Command	Description
mureo byod import <file>.xlsx	Import a Sheet bundle. Aborts if any platform present in the workbook is already imported.
mureo byod import <file>.xlsx --replace	Overwrite existing BYOD data for any platform present in the bundle.
mureo byod status	Show per-platform mode (BYOD / Live API / not configured); warns about stale entries from older mureo versions.
mureo byod remove --google-ads / --meta-ads	Remove BYOD data for one platform.
mureo byod clear	Wipe ~/.mureo/byod/ (prompts for confirmation).
mureo byod clear --yes	Skip the confirmation prompt.

Per-platform routing

The MCP server checks each platform independently at every tool dispatch. With google_ads imported but meta_ads not, a single /daily-check call uses the BYOD CSVs for Google Ads and the live API for Meta Ads. mureo byod status shows the active mix.

GA4 and Search Console are not part of the BYOD bundle pipeline — they remain on the Live API OAuth path.

Read-only guarantee

BYOD mode rejects every mutation tool. Methods whose name starts with create_, update_, delete_, remove_, add_, send_, upload_, pause_, resume_, enable_, disable_, apply_, publish_, submit_, attach_, detach_, approve_, reject_, cancel_, set_, or patch_ return:

{
  "status": "skipped_in_byod_readonly",
  "operation": "<name>",
  "note": "BYOD mode is analysis-only. This call would have written to a real ad account."
}

The agent can analyse and recommend, but never writes.

Output Format

Authentication check commands output JSON to stdout:

mureo auth check-google | jq .

{
  "developer_token": "***************abcd",
  "client_id": "123456789.apps.googleusercontent.com",
  "client_secret": "***************wxyz",
  "refresh_token": "***************efgh",
  "login_customer_id": "1234567890"
}

Secrets are masked, showing only the last 4 characters.

Ad Platform Operations

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.

See mcp-server.md for the full tool reference.