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
configure	Open the local web configuration UI (credential entry + host setup)
open	Bring an already-running configure dashboard to the front
service	Install / inspect / remove the always-on configure service
upgrade	Upgrade mureo and its plugins (also re-deploys skills)
byod	Bring Your Own Data — analyse ad-account data locally, no OAuth
demo	Scaffold a self-contained demo workspace
providers	Install / list / remove official MCP providers (Google Ads, Meta, GA4)
install-desktop	Wire mureo into Claude Desktop chat (macOS)
learn	Append insights to the diagnostic knowledge base
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 as native slash skills (~/.claude/skills/)
5. Skills (~/.claude/skills/) — bundled operational + shared skills, plus any plugin-provided native slash skills discovered via the mureo.native_skills entry-point group (#439)

mureo configure (the browser UI) deploys the same skills — bundled and plugin native — when it runs basic setup.

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.

Configure UI & Always-On Service

mureo configure normally runs the browser UI on demand and stops when idle. To keep it running across reboots — so the dashboard (including the read-only Reports tab) is always reachable — register it as a user-level auto-start service.

# Open the configure UI (or surface the already-running one)
mureo configure
mureo open                 # bring an already-running configure UI to the front

# Run headless as a long-lived daemon (no browser, no idle timeout).
# This is what the service backend invokes; you rarely run it by hand.
mureo configure --serve --port 7613

# Auto-start service (user-level: launchd on macOS, systemd --user on
# Linux, Task Scheduler on Windows — never root/admin daemon).
mureo service install      # register + start now (runs at every login)
mureo service status       # show installed / running state + the URL
mureo service restart      # restart in place to pick up a new version
mureo service uninstall    # remove the auto-start registration

Notes:

• Windows: mureo service install registers an on-logon Scheduled Task. Creating it writes to the Task Scheduler root, which needs an elevated shell — run it from a PowerShell opened via Run as administrator (being in the Administrators group is not enough). The task itself then runs at logon with your normal (non-elevated) rights.
• After upgrading mureo, run mureo service restart so the running daemon picks up the new code (Task Scheduler and the supervisors do not relaunch a cleanly-exited process automatically on every platform).
• The configure dashboard’s About tab also has a Restart configure button that does the same thing from the browser: a managed service restarts via its supervisor, while an interactive mureo configure restarts itself in place. The page waits for the server to come back and reloads automatically.

Maintenance Commands

mureo upgrade upgrades mureo and its plugins inside the current (pipx) venv in one pip invocation — pipx upgrade mureo only touches the primary package, leaving same-venv plugins behind.

mureo upgrade              # upgrade mureo itself
mureo upgrade --all        # upgrade mureo + every installed `mureo-*` plugin
mureo upgrade --dry-run    # print the pip command without running it
mureo upgrade --no-refresh # upgrade the package(s) only; skip the post-upgrade refresh

After a successful upgrade, mureo runs a post-upgrade refresh so the new code actually takes effect: it re-deploys the bundled skills into ~/.claude/skills/ and any plugin-provided native slash skills (the mureo.native_skills entry-point group, #439) into both ~/.claude/skills/ and ~/.codex/skills/, upgrades the installed credential-guard hooks, and restarts the always-on service. The refresh only touches a host that already has a skills directory, so it never force-installs skills you removed on purpose. Pass --no-refresh to upgrade the package(s) alone.

The configure UI’s About mureo tab surfaces the same capability for GUI users: it shows installed versions, checks the index for newer mureo / plugin releases in the background, and offers a one-click “update all” button.

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.