CLI Reference
Every command, flag, and option.
Local browser workspace
Run myflames ui to import saved plans, inspect charts and
operators, compare plans, and export reports. The built interface ships with
Python; Node.js is not needed. Plans stay in memory until the page closes or
reloads. Live database capture remains available through the CLI.
--port PORT chooses a local port; the default selects an
available port. --no-browser prints the URL without opening a
browser. Press Ctrl+C to stop the server.
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
myflames ui [--port PORT] [--no-browser]digest, ranked advise findings, a
check exit-code gate, and an MCP server. See
Agent & CI subcommands below.
Rendering options
| Option | Default | Description |
|---|---|---|
capture | Estimated plan | Capture live plans, run statistics and optional trace; use --mode analyze to execute. See query workspace. |
explore | Visual Explain | Interactive HTML with --metric, --focus, --collapse, and --selected. |
--type TYPE | flamegraph | flamegraph, bargraph, treemap, diagram, tree, workbench |
--output FILE, -o | stdout | .html = self-contained report; .svg = responsive SVG. JSON sidecar auto-written alongside. |
--width N | 1800 / 1200 | SVG width in pixels |
--height N | 32 | Frame height (flamegraph only) |
--colors SCHEME | hot | hot, mem, io, red, green, blue (flamegraph only) |
--title TEXT | MySQL Query Plan | Chart title shown in the SVG header |
--inverted | off | Icicle graph — roots at the top (flamegraph only) |
--no-enhance | off | Disable detailed tooltips (flamegraph only) |
Live connection
Same flags as the mysql CLI. Providing -h enables live mode.
| Option | Description |
|---|---|
-h HOST, --host | Connect to this host (enables live mode) |
-P PORT | Port number (default: 3306) |
-u USER | Username |
-p[PASS] | Password. -p alone prompts; -p'secret' inline. |
-D DB | Default database |
-e SQL, --execute | Query to EXPLAIN ANALYZE (required in live mode) |
--ssl-mode MODE | DISABLED, PREFERRED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY |
--ssl-ca PATH | CA certificate file for TLS verification |
--ssl-cert PATH | Client certificate for mutual TLS |
--ssl-key PATH | Client private key for mutual TLS |
--mysql-binary PATH | Override mysql/mariadb binary autodetection |
--no-collect-schema | Skip SHOW CREATE TABLE collection |
--no-collect-stats | Skip information_schema.tables row/size collection |
--no-collect-variables | Skip SHOW SESSION VARIABLES collection |
--defaults-extra-file and never appear in ps, environment variables, or logs. The temp file is deleted on exit.
JSON sidecar
| Option | Description |
|---|---|
| (default) | Auto-writes <output>.json alongside the HTML/SVG |
--sidecar PATH | Write sidecar to a specific path |
--no-sidecar | Suppress sidecar generation |
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 deltaSide-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 guideInteractive 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 lessonGenerate self-contained HTML lessons that animate database algorithms. See the Teach Lessons index for the full catalog.
| Option | Description |
|---|---|
lesson | Lesson name: btree, bnl, hash, join, lru, filesort, tmp, icp, index_merge |
--output FILE, -o | Write HTML to file (default: stdout) |
--title TEXT | Override the lesson title |
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 JSONBare 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.
| Option | Description |
|---|---|
--cost | Show the token + $ saving of the digest vs the raw plan, instead of the digest text |
--tokenizer {heuristic,claude,gpt} | How to count tokens for --cost/--json. heuristic (offline default, no key/network), claude (Anthropic count_tokens; needs myflames[tokens] + ANTHROPIC_API_KEY), gpt (tiktoken; exact for GPT, keyless; needs myflames[gpt]) |
--show-prompts | Print the raw-plan prompt and digest prompt side by side |
--json | Emit the savings comparison as machine-readable JSON (implies --cost) |
--model MODEL_ID | Pricing/counting model id (default claude-sonnet-4-6) |
--output FILE, -o | Write to a file instead of stdout |
tokens alias still works (it warns on stderr and defaults to --cost); use digest instead.myflames advise
myflames advise explain.json # ranked warnings + suggestions (text)
myflames advise explain.json --json # same, machine-readable, each with a confidenceA 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 codeA CI / pre-commit / agent-loop gate. Exits 1 if any trigger
matches, 0 if the plan is clean, 2 on bad input.
| Option | Description |
|---|---|
--fail-on LIST | Comma-separated triggers: warning categories (full_scan, filesort, temp_table, bnl, hash_join, index_merge, nonsargable_join, env), severities (error, warn, info), or any (default) |
--quiet, -q | Suppress per-match output; rely on the exit code |
myflames-mcp — MCP server
pip install 'myflames[mcp]'
claude mcp add myflames -- myflames-mcpExposes 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
| Option | Description |
|---|---|
--query SQL | Embed the original SQL in the output for reference |
--query-file PATH | Read the original SQL from a file |
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:
| Code | Meaning |
|---|---|
0 | Success (and, for check, the plan is clean — no trigger matched) |
1 | check gate tripped: a --fail-on trigger matched |
2 | Bad input: parse failure, missing file, connection error, or invalid arguments |
Errors and comparison matching
Render and compare commands report unreadable or invalid inputs and
output-write failures on stderr with exit code 2. Exit code 1 is reserved
for a matching check finding.
Comparisons retain repeated operators with the same label, pairing occurrences in traversal order. When a query rewrite reorders identical operators, inspect the plans to confirm the pairing.