cli-reference.md

CLI Reference

Auto-generated from mechanic-desktop v0.5.0 on 2026-09-30

This document lists all available Mechanic CLI commands and their input parameters. Examples are invocation templates: replace placeholders and supply valid values for your addon. Empty arrays/objects and numeric samples illustrate JSON types, not every command's validation rules. For complete schemas and mutation metadata, use mech --json call commands.list.

Quick Reference

Command	Description
commands.list	List command schemas and mutation metadata
dashboard.metrics	Get the latest reload and test metrics from the local histor...
diagnostic.metrics	Read bounded desktop overhead and optional explicitly select...
diagnostic.targets	List deterministic client/account/character/profile diagnost...
server.shutdown	Gracefully shut down the Mechanic Desktop server
sv.discover	Automatically discover SavedVariables paths for all WoW flav...
sv.parse	Parse a WoW SavedVariables file and extract !Mechanic data
system.pick_file	Open a native file picker dialog to select a file (Windows o...
addon.complexity	Detect code complexity issues in a WoW addon (nesting, long ...
addon.create	Create a new WoW addon from a template
addon.deadcode	Detect dead code in a WoW addon (unused functions, orphaned ...
addon.deprecations	Scan a WoW addon's Lua files for deprecated API calls
addon.format	Run StyLua formatter on a WoW addon
addon.lint	Run Luacheck linter on a WoW addon
addon.output	Get all addon output (errors, tests, console) for agent cons...
addon.security	Detect security issues in a WoW addon (combat lockdown, secr...
addon.sync	Preflight and create addon junction links; supports dry_run
addon.test	Run Busted unit tests on a WoW addon
addon.validate	Validate a WoW addon's .toc file for common issues
changelog.add	Add an entry to the addon's CHANGELOG.md
git.commit	Stage all addon changes and create a git commit limited to t...
git.tag	Create an annotated git tag for an addon release
release.all	Preflight and run version bump, changelog, commit and tag; s...
version.bump	Update the version in a WoW addon's .toc file
atlas.scan	Scan wow-ui-source for atlas icons and generate searchable i...
atlas.search	Search Blizzard UI atlas icons by name pattern (supports wil...
locale.extract	Extract potential localizable strings from addon code
locale.validate	Validate locale coverage against the enUS baseline
env.status	Get Mechanic environment configuration and status
libs.check	Check addon library status against libs.json config
libs.init	Creates a libs.json config file from currently installed lib...
libs.sync	Sync addon libraries based on libs.json config
tools.status	Check the status of development tools (luacheck, stylua, etc...
api.download	Download FrameXML from Townlong Yak and optionally refresh A...
api.generate	Generate APIDefs Lua files from api_database.json for Mechan...
api.info	Get detailed information about a specific WoW API
api.list	List APIs by namespace or category
api.populate	Parse Blizzard API documentation and generate api_database.j...
api.queue	Queue API tests for in-game execution. After running this, /...
api.refresh	Full refresh: parse Blizzard docs and regenerate all APIDefs...
api.search	Search WoW APIs by name pattern. Works offline (reads static...
api.stats	Get statistics about available WoW APIs
lua.queue	Queue Lua code snippets for in-game execution. After running...
lua.results	Get results from the last Lua eval queue execution
sandbox.exec	Execute Lua code in a restricted sandbox with WoW API stubs....
sandbox.generate	Generate WoW API stubs from APIDefs for sandbox testing. A n...
sandbox.status	Get status of generated WoW API stubs
sandbox.test	Run an addon's *_spec.lua tests (Core/ and Tests/) in the re...
perf.baseline	Record a performance baseline measurement for an addon
perf.compare	Compare current performance against baseline and detect regr...
perf.list	List all addons with performance baselines
perf.report	Generate a performance report showing history and trends
assets.list	List asset files in an addon's assets_source and assets fold...
assets.sync	Sync addon assets: convert PNG to TGA and copy other files f...
research.query	Search the web for addon development information using Gemin...
fencore-catalog	Get full catalog of FenCore logic domains and functions
fencore-info	Get detailed info about a specific FenCore function
fencore-search	Search FenCore functions by name or description
docs.generate	Generate CLI reference documentation from registered command...
docs.stale	Detect stale or broken documentation in a WoW addon

---

Core Commands

commands.list

List command schemas and mutation metadata

Parameters: None

Example:

mech call commands.list '{}'

---

dashboard.metrics

Get the latest reload and test metrics from the local history

Parameters: None

Example:

mech call dashboard.metrics '{}'

---

diagnostic.metrics

Read bounded desktop overhead and optional explicitly selected addon snapshot

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)	Explicit target to include its last saved addon overhead snapshot

Example:

mech call diagnostic.metrics '{}'

---

diagnostic.targets

List deterministic client/account/character/profile diagnostic targets

Parameters: None

Example:

mech call diagnostic.targets '{}'

---

server.shutdown

Gracefully shut down the Mechanic Desktop server

Parameters: None

Example:

mech call server.shutdown '{}'

---

sv.discover

Automatically discover SavedVariables paths for all WoW flavors

Parameters: None

Example:

mech call sv.discover '{}'

---

sv.parse

Parse a WoW SavedVariables file and extract !Mechanic data

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)
file_path	string	Yes	Absolute path to the !Mechanic.lua file

Example:

mech call sv.parse '{"file_path": "<file_path>"}'

---

system.pick_file

Open a native file picker dialog to select a file (Windows only)

Parameters:

Field	Type	Required	Description
title	string	No (default: 'Select File')	Title of the dialog window
filter	string	No (default: 'All Files (*.*)|*.*')	File filter (e.g., 'Text Files (.txt)|.txt')

Example:

mech call system.pick_file '{}'

---

Development Commands

addon.complexity

Detect code complexity issues in a WoW addon (nesting, long functions, magic numbers)

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to analyze
path	string | null	No (default: None)	Override path to addon folder
categories	array | null	No (default: None)	Specific categories to check (default: all)
max_nesting	integer	No (default: 5)	Maximum allowed nesting depth
max_function_lines	integer	No (default: 100)	Maximum lines per function
max_file_lines	integer	No (default: 500)	Maximum lines per file
limit	integer	No (default: 200)	Maximum issues returned, most severe first (counts cover all issues)

Example:

mech call addon.complexity '{"addon": "<addon>"}'

---

addon.create

Create a new WoW addon from a template

Parameters:

Field	Type	Required	Description
name	string	Yes	Name for the new addon
template	string | null	No (default: None)	Template to use (defaults to _TemplateAddon)
author	string | null	No (default: None)	Author name for metadata

Example:

mech call addon.create '{"name": "<name>"}'

---

addon.deadcode

Detect dead code in a WoW addon (unused functions, orphaned files, etc.)

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to analyze
path	string | null	No (default: None)	Override path to addon folder
categories	array | null	No (default: None)	Specific categories to check (default: all)
include_suspicious	boolean	No (default: True)	Include lower-confidence findings
limit	integer	No (default: 200)	Maximum issues returned, most severe first (counts cover all issues)

Example:

mech call addon.deadcode '{"addon": "<addon>"}'

---

addon.deprecations

Scan a WoW addon's Lua files for deprecated API calls

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to scan
path	string | null	No (default: None)	Override path to addon folder
category	string | null	No (default: None)	Filter by category (e.g., spells, items, containers)
min_severity	string	No (default: 'warning')	Minimum severity: info, warning, or error

Example:

mech call addon.deprecations '{"addon": "<addon>"}'

---

addon.format

Run StyLua formatter on a WoW addon

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to format
path	string | null	No (default: None)	Override path to addon folder
check	boolean	No (default: False)	Only check formatting, don't modify files

Example:

mech call addon.format '{"addon": "<addon>"}'

---

addon.lint

Run Luacheck linter on a WoW addon

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to lint
path	string | null	No (default: None)	Override path to addon folder

Example:

mech call addon.lint '{"addon": "<addon>"}'

---

addon.output

Get all addon output (errors, tests, console) for agent consumption. Use agent_mode=true for compressed output.

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)
agent_mode	boolean	No (default: False)	Enable smart compression for AI agents

Example:

mech addon.output

---

addon.security

Detect security issues in a WoW addon (combat lockdown, secret values, taint)

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to analyze
path	string | null	No (default: None)	Override path to addon folder
categories	array | null	No (default: None)	Specific categories to check (default: all)
include_suspicious	boolean	No (default: True)	Include lower-confidence findings
limit	integer	No (default: 200)	Maximum issues returned, most severe first (counts cover all issues)

Example:

mech call addon.security '{"addon": "<addon>"}'

---

addon.sync

Preflight and create addon junction links; supports dry_run

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to sync
flavors	array | null	No (default: None)	WoW flavors to sync to (defaults to all)
dry_run	boolean	No (default: False)	Validate and preview junctions without creating directories or links

Example:

mech call addon.sync '{"addon": "<addon>"}'

---

addon.test

Run Busted unit tests on a WoW addon

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to test
path	string | null	No (default: None)	Override path to addon folder
coverage	boolean	No (default: False)	Generate code coverage report

Example:

mech call addon.test '{"addon": "<addon>"}'

---

addon.validate

Validate a WoW addon's .toc file for common issues

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to operate on
path	string | null	No (default: None)	Override path to addon folder

Example:

mech call addon.validate '{"addon": "<addon>"}'

---

Release Commands

changelog.add

Add an entry to the addon's CHANGELOG.md

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
version	string	Yes	Version for the changelog entry
message	string	Yes	Change description
category	string	No (default: 'Changed')	Category: Added, Changed, Deprecated, Removed, Fixed, Security
path	string | null	No (default: None)	Override path to addon folder

Example:

mech call changelog.add '{"addon": "<addon>","version": "<version>","message": "<message>"}'

---

git.commit

Stage all addon changes and create a git commit limited to the addon folder

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
message	string	Yes	Commit message
path	string | null	No (default: None)	Override path to addon folder

Example:

mech call git.commit '{"addon": "<addon>","message": "<message>"}'

---

git.tag

Create an annotated git tag for an addon release

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
version	string	Yes	Version to tag (e.g., '1.2.0')
message	string | null	No (default: None)	Tag message (defaults to version)
path	string | null	No (default: None)	Override path to addon folder

Example:

mech call git.tag '{"addon": "<addon>","version": "<version>"}'

---

release.all

Preflight and run version bump, changelog, commit and tag; supports dry_run

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
version	string	Yes	New version string
message	string	Yes	Changelog entry and release description
category	string	No (default: 'Changed')	Changelog category
path	string | null	No (default: None)	Override path
dry_run	boolean	No (default: False)	Validate and preview without changing files, index, commits or tags

Example:

mech call release.all '{"addon": "<addon>","version": "<version>","message": "<message>"}'

---

version.bump

Update the version in a WoW addon's .toc file

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
version	string	Yes	New version string (e.g., '1.2.0')
path	string | null	No (default: None)	Override path to addon folder

Example:

mech call version.bump '{"addon": "<addon>","version": "<version>"}'

---

Localization Commands

atlas.scan

Scan wow-ui-source for atlas icons and generate searchable index

Parameters:

Field	Type	Required	Description
source_path	string	Yes	Path to wow-ui-source repository root
output_path	string | null	No (default: None)	Output path for atlas_index.json (defaults to data_dir)

Example:

mech call atlas.scan '{"source_path": "<source_path>"}'

---

atlas.search

Search Blizzard UI atlas icons by name pattern (supports wildcards)

Parameters:

Field	Type	Required	Description
query	string	Yes	Search query for atlas icons (supports * wildcards)
limit	integer	No (default: 20)	Maximum results to return
include_files	boolean	No (default: False)	Include source file paths in results

Example:

mech call atlas.search '{"query": "<query>"}'

---

locale.extract

Extract potential localizable strings from addon code

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
path	string | null	No (default: None)	Override path to addon folder

Example:

mech call locale.extract '{"addon": "<addon>"}'

---

locale.validate

Validate locale coverage against the enUS baseline

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to validate
path	string | null	No (default: None)	Override path to addon folder

Example:

mech call locale.validate '{"addon": "<addon>"}'

---

Environment Commands

env.status

Get Mechanic environment configuration and status

Parameters: None

Example:

mech call env.status '{}'

---

libs.check

Check addon library status against libs.json config

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to check

Example:

mech call libs.check '{"addon": "<addon>"}'

---

libs.init

Creates a libs.json config file from currently installed libraries. ⚠️ Will NOT overwrite existing config unless overwrite=true is set.

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
mode	string	No (default: 'include')	Config mode: 'include' (whitelist) or 'exclude' (blocklist)
overwrite	boolean	No (default: False)	Overwrite existing libs.json

Example:

mech call libs.init '{"addon": "<addon>"}'

---

libs.sync

Sync addon libraries based on libs.json config

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to sync
source	string | null	No (default: None)	Source library path (defaults to <dev_path>/Libs, then <dev_path>/MechanicLocal/Libs)
dry_run	boolean	No (default: False)	Preview changes without applying
force	boolean	No (default: False)	Force update existing libraries (replaces them)
remove_extra	boolean	No (default: False)	Remove libraries not in config

Example:

mech call libs.sync '{"addon": "<addon>"}'

---

Tools Commands

tools.status

Check the status of development tools (luacheck, stylua, etc.)

Parameters: None

Example:

mech call tools.status '{}'

---

API Reference Commands

api.download

Download FrameXML from Townlong Yak and optionally refresh API definitions

Parameters:

Field	Type	Required	Description
build_id	string | null	No (default: None)	Build ID to download (digits only, e.g., '64889'). Required.
output_path	string | null	No (default: None)	Where to extract the download. Defaults to <data_dir>/framexml/{version}
refresh	boolean	No (default: True)	Run api.refresh after download

Example:

mech call api.download '{}'

---

api.generate

Generate APIDefs Lua files from api_database.json for Mechanic (defaults to the repository's Mechanic/UI/APIDefs)

Parameters:

Field	Type	Required	Description
database_path	string | null	No (default: None)	Path to api_database.json (defaults to data_dir)
output_path	string | null	No (default: None)	Output folder for APIDefs (defaults to the repository's Mechanic/UI/APIDefs). Must be named 'APIDefs' unless allow_any_output_dir is set.
allow_any_output_dir	boolean	No (default: False)	Allow an output folder that is not named 'APIDefs'

Example:

mech call api.generate '{}'

---

api.info

Get detailed information about a specific WoW API

Parameters:

Field	Type	Required	Description
api_name	string	Yes	Full API name (e.g., C_Spell.GetSpellInfo)

Example:

mech call api.info '{"api_name": "<api_name>"}'

---

api.list

List APIs by namespace or category

Parameters:

Field	Type	Required	Description
namespace	string | null	No (default: None)	Namespace to list (e.g., C_Spell)
category	string | null	No (default: None)	Category to list
limit	integer	No (default: 50)	Max results

Example:

mech call api.list '{}'

---

api.populate

Parse Blizzard API documentation and generate api_database.json

Parameters:

Field	Type	Required	Description
source_path	string	Yes	Path to wow-ui-source repository root
output_path	string | null	No (default: None)	Output path for api_database.json (defaults to data_dir)

Example:

mech call api.populate '{"source_path": "<source_path>"}'

---

api.queue

Queue API tests for in-game execution. After running this, /reload in WoW to execute tests.

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)
apis	array	Yes	List of API names to queue for testing
params	object | null	No (default: None)	Optional parameters per API: {'C_Spell.GetSpellInfo': {'spellID': 8690}}

Example:

mech call api.queue '{"apis": []}'

---

api.refresh

Full refresh: parse Blizzard docs and regenerate all APIDefs in one step

Parameters:

Field	Type	Required	Description
source_path	string	Yes	Path to wow-ui-source repository root or Townlong Yak extract
output_path	string | null	No (default: None)	APIDefs output folder (see api.generate)
database_path	string | null	No (default: None)	api_database.json location (defaults to data_dir)
allow_any_output_dir	boolean	No (default: False)	Allow an output folder that is not named 'APIDefs'

Example:

mech call api.refresh '{"source_path": "<source_path>"}'

---

api.search

Search WoW APIs by name pattern. Works offline (reads static definitions).

Parameters:

Field	Type	Required	Description
query	string	Yes	Search pattern (supports * wildcards)
category	string | null	No (default: None)	Filter by category
namespace	string | null	No (default: None)	Filter by namespace
limit	integer	No (default: 20)	Max results to return

Example:

mech call api.search '{"query": "<query>"}'

---

api.stats

Get statistics about available WoW APIs

Parameters: None

Example:

mech call api.stats '{}'

---

Testing Commands

lua.queue

Queue Lua code snippets for in-game execution. After running this, /reload in WoW to execute.

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)
code	array	Yes	List of Lua code snippets to execute. Each snippet should return a value.
labels	array | null	No (default: None)	Optional labels for each snippet (for easier identification in results)

Example:

mech call lua.queue '{"code": []}'

---

lua.results

Get results from the last Lua eval queue execution

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)

Example:

mech call lua.results '{}'

---

sandbox.exec

Execute Lua code in a restricted sandbox with WoW API stubs. User code sees only whitelisted globals (no os, io, package, debug, require, dofile, loadfile, string.dump or bytecode loading); runs for at most 30s and prints at most 256 KB.

Parameters:

Field	Type	Required	Description
code	string	Yes	Lua code to execute
addon	string | null	No (default: None)	Name of addon to load before execution (looks in dev folder)
load_stubs	boolean	No (default: True)	Whether to load WoW API stubs

Example:

mech call sandbox.exec '{"code": "<code>"}'

---

sandbox.generate

Generate WoW API stubs from APIDefs for sandbox testing. A namespace is regenerated in place; existing stubs are kept unless force is set or the APIDefs are newer.

Parameters:

Field	Type	Required	Description
namespace	string | null	No (default: None)	Specific namespace to regenerate in place (e.g., 'C_Spell'); the other namespaces in an existing stubs file are kept. If not provided, generates all.
force	boolean	No (default: False)	Regenerate all stubs even if they are newer than the APIDefs

Example:

mech call sandbox.generate '{}'

---

sandbox.status

Get status of generated WoW API stubs

Parameters: None

Example:

mech call sandbox.status '{}'

---

sandbox.test

Run an addon's *_spec.lua tests (Core/ and Tests/) in the restricted sandbox with WoW API stubs and the bundled busted-style framework. filter limits tests by name; failures are listed first.

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of addon to test (looks in dev folder)
filter	string | null	No (default: None)	Only run tests whose full name contains this text (case-insensitive)

Example:

mech call sandbox.test '{"addon": "<addon>"}'

---

Performance Commands

perf.baseline

Record a performance baseline measurement for an addon

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
version	string	Yes	Version being measured
memory_kb	number	Yes	Memory usage in KB
cpu_ms	number	Yes	CPU time in milliseconds

Example:

mech call perf.baseline '{"addon": "<addon>","version": "<version>","memory_kb": 0,"cpu_ms": 0}'

---

perf.compare

Compare current performance against baseline and detect regressions

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
memory_kb	number	Yes	Current memory usage in KB
cpu_ms	number	Yes	Current CPU time in milliseconds
memory_threshold	number	No (default: 1.5)	Memory increase factor that triggers warning
cpu_threshold	number	No (default: 2.0)	CPU increase factor that triggers warning

Example:

mech call perf.compare '{"addon": "<addon>","memory_kb": 0,"cpu_ms": 0}'

---

perf.list

List all addons with performance baselines

Parameters: None

Example:

mech call perf.list '{}'

---

perf.report

Generate a performance report showing history and trends

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon
limit	integer	No (default: 10)	Number of recent measurements to show

Example:

mech call perf.report '{"addon": "<addon>"}'

---

Assets Commands

assets.list

List asset files in an addon's assets_source and assets folders

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon

Example:

mech call assets.list '{"addon": "<addon>"}'

---

assets.sync

Sync addon assets: convert PNG to TGA and copy other files from assets_source to assets; removes only files a previous sync generated; supports dry_run

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to sync assets for
dry_run	boolean	No (default: False)	Report what would be converted, copied and removed without changing files

Example:

mech call assets.sync '{"addon": "<addon>"}'

---

Research Commands

research.query

Search the web for addon development information using Gemini with Google Search grounding

Parameters:

Field	Type	Required	Description
query	string	Yes	Search query or question
mode	string	No (default: 'fast')	Search mode: 'fast' (Gemini Flash, ~15-30s) or 'thinking' (Gemini Pro, ~30-90s)
json_output	boolean	No (default: False)	Request structured JSON response

Example:

mech call research.query '{"query": "<query>"}'

---

FenCore Commands

fencore-catalog

Get full catalog of FenCore logic domains and functions

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)

Example:

mech call fencore-catalog '{}'

---

fencore-info

Get detailed info about a specific FenCore function

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)
domain	string	Yes	Domain name (e.g., 'Math')
function	string	Yes	Function name (e.g., 'Clamp')

Example:

mech call fencore-info '{"domain": "<domain>","function": "<function>"}'

---

fencore-search

Search FenCore functions by name or description

Parameters:

Field	Type	Required	Description
target	object | null	No (default: None)
query	string	Yes	Search query (partial match on name or description)
limit	integer	No (default: 20)	Maximum results to return

Example:

mech call fencore-search '{"query": "<query>"}'

---

Documentation Commands

docs.generate

Generate CLI reference documentation from registered commands

Parameters:

Field	Type	Required	Description
output_path	string | null	No (default: None)	Output file path. Defaults to docs/cli-reference.md
format	string	No (default: 'markdown')	Output format: 'markdown' or 'json'

Example:

mech call docs.generate '{}'

---

docs.stale

Detect stale or broken documentation in a WoW addon

Parameters:

Field	Type	Required	Description
addon	string	Yes	Name of the addon to analyze
path	string | null	No (default: None)	Override path to addon folder
include_suspicious	boolean	No (default: True)	Include lower-confidence findings
commits_threshold	integer	No (default: 10)	Flag docs not updated in this many code commits
limit	integer	No (default: 200)	Maximum issues returned, most severe first (counts cover all issues)

Example:

mech call docs.stale '{"addon": "<addon>"}'

---

Usage Notes

Global Flags

Flag	Description
--json	Output raw JSON (for parsing)
--quiet	Suppress non-essential output
--agent	Smart compression for AI agents

Calling Commands

# Standard call with JSON input
mech call <command> '{"param": "value"}'

# Standard call without input
mech call <command> '{}'

# The one dedicated shortcut
mech addon.output  # Direct command shortcut

---

Generated by mech call docs.generate