CLI Reference

Every command, flag, and option.

Synopsis

myflames [options] [explain.json]
myflames -h HOST -u USER -p -D DB -e 'SQL' -o report.html
myflames compare before.json after.json --output diff.html
myflames digest explain.json [--cost] [--tokenizer claude|gpt]
myflames advise explain.json [--json]
myflames check  explain.json --fail-on full_scan,filesort
myflames teach <lesson> [-o file.html]
myflames guide

Rendering options

Live connection

Same flags as the mysql CLI. Providing -h enables live mode.

JSON sidecar

Subcommands

myflames compare (alias: diff)

myflames compare before.json after.json --output diff.html
myflames diff    before.json after.json --digest   # token-cheap text diff for an LLM
myflames diff    before.json after.json --json     # structured compare-1.0 delta

Side-by-side before/after comparison showing total time delta, per-operator self-time/rows/loops changes, and new/resolved warnings. Default output is an HTML report; --digest emits a compact text diff (for pasting into an LLM) and --json emits the structured compare-1.0 delta.

myflames guide

myflames guide

Interactive guide that helps you pick the right view type for your situation.

myflames teach

myflames teach              # list available lessons
myflames teach btree -o btree.html   # render a lesson

Generate self-contained HTML lessons that animate database algorithms. See the Teach Lessons index for the full catalog.

Agent & CI subcommands

These serve AI agents and pipelines, not just human eyes. A raw EXPLAIN ANALYZE FORMAT=JSON plan is verbose and noisy; an LLM burns tokens parsing it before it can reason, and an SVG is invisible to an agent. myflames parses and analyzes a plan once, then projects it many ways.

myflames digest

myflames digest explain.json                 # compact, LLM-ready digest (pipe to your model)
myflames digest explain.json --cost          # tokens + $ saved vs pasting the raw plan
myflames digest explain.json --cost --tokenizer claude   # exact Claude counts (your key)
myflames digest explain.json --cost --tokenizer gpt      # exact GPT counts (tiktoken, keyless)
myflames digest explain.json --show-prompts   # print both prompts (raw vs digest)
myflames digest explain.json --json           # the savings comparison as JSON

Bare digest emits the compact, source-grounded digest of a plan (summary, warnings, fixes, plan skeleton) at a fraction of the tokens of the raw JSON. --cost shows the token and dollar saving instead of the digest.

myflames advise

myflames advise explain.json          # ranked warnings + suggestions (text)
myflames advise explain.json --json   # same, machine-readable, each with a confidence

A ranked list of advisor findings — warnings and tuning suggestions, each carrying a confidence — for an agent to act on. (Deprecated alias: findings.)

myflames check

myflames check explain.json --fail-on full_scan,filesort   # CI gate
myflames check explain.json --fail-on any -q               # silent; rely on exit code

A CI / pre-commit / agent-loop gate. Exits 1 if any trigger matches, 0 if the plan is clean, 2 on bad input.

myflames-mcp — MCP server

pip install 'myflames[mcp]'
claude mcp add myflames -- myflames-mcp

Exposes myflames as tools an MCP client (Claude Code, Cursor, any agent) can call directly: analyze_plan, digest_plan, compare_plans, explain_optimizer_switch, and explain_query. Only the transport needs the extra; the tool logic is stdlib and unit-tested.

Query embedding

Environment variables

Core myflames reads no environment variables — all configuration is through CLI flags. The one exception is opt-in: digest --cost --tokenizer claude reads ANTHROPIC_API_KEY from the environment and hands it straight to the Anthropic SDK to call count_tokens. The key is never written to a file, the sidecar, or the output; if it is unset, the command falls back to the offline estimate with a one-line note.

Exit codes

The check, digest, and advise subcommands follow a stable 0/1/2 contract for use in agent loops and CI: