App Inspection

Six read-only commands cluster on this page. None of them mutate state — they read your project (or, for wheels lookup, the CLI’s own docs index), print what they find, and exit. Reach for them when you’re diagnosing an unfamiliar setup or getting a quick inventory of an app you haven’t touched in a while.

You’ll use this for:

• Seeing every route your application declares without opening config/routes.cfm.
• Checking the installed framework version, datasource name, and server status at a glance.
• Counting models, controllers, views, and tests — and finding outliers with --verbose.
• Sweeping the codebase for TODO, FIXME, and OPTIMIZE markers before a release.
• Running a health check when something is misconfigured and you don’t know where to start.
• Looking up a framework function’s parameters, or a guide topic, without a browser or a network connection.

wheels routes

Print the dispatch table for the running application — every route declared in config/routes.cfm plus any that framework defaults register at boot.

Synopsis

wheels routes [--filter=<text>] [--format=text|json]

Description

wheels routes HTTP-dispatches to the development server at /wheels/cli?command=routes&format=json and formats the returned route table. That means it requires a running server — start one with wheels start first. If no server is detected on any configured port, the command prints an error and exits without output.

The route table comes from the running application, so it includes the framework’s own /wheels/* routes. The text output is a columnar listing: HTTP method, pattern, and controller#action with the route name in parentheses, followed by a <n> route(s) count.

Flags

Flag	Description
--filter=<text>	Show only routes whose name, pattern, or controller#action contains this text (case-insensitive). When nothing matches, prints No routes match '<text>'.
--format=<format>	text (default, aligned table) or json (the route array as JSON).

Example

illustrative — server required

wheels routes

Sample output (trimmed):

METHOD  PATTERN                               CONTROLLER#ACTION
-----------------------------------------------------------------------------------
GET     /wheels/info                          wheels.public#info  (wheelsInfo)
...
GET     /posts                                posts#index  (posts)
GET     /posts/new                            posts#new  (newPost)
POST    /posts                                posts#create  (posts)
GET     /                                     main#index  (root)

41 route(s)

Server required

If the command prints No running Wheels server detected. Start one with: wheels start, boot the dev server in another terminal and re-run. The inspector only exists inside the framework runtime.

wheels info

Summarise the project’s environment in a short block — CLI version, installed framework version, engine, datasource, and whether a server is running.

Synopsis

wheels info

Description

wheels info reads the project locally (no server required) and emits a human-readable summary. It detects the Wheels version from vendor/wheels/wheels.json, the datasource from config/settings.cfm, the presence of .env and lucee.json, and counts any .resources(…) calls in config/routes.cfm plus the CFC files under app/models/. It also calls detectServerPort() to report whether the dev server is currently up.

When the current directory is not a Wheels project (no vendor/wheels/ present), the command prints a single line saying so and exits.

Flags

None. wheels info takes no flags — ignore any reference to --json or --quiet; those were never wired up.

Output stream

Output is written to stdout. If you’re piping wheels info into another tool, it reads from stdout directly — no 2> redirection needed. The process exits successfully either way; no non-zero exit is raised when the summary is empty.

Example

wheels info

Sample output (trimmed):

Wheels CLI v4.0.0

Project:  /path/to/myblog
Wheels:   v4.0.0
Engine:   Lucee (LuCLI module)
Database: myblog
Env file: .env found
Config:   lucee.json found
Routes:   3 resource route(s)
Models:   5 model(s)
Server:   not running

The first line is preceded by a small Wheels banner in some terminals — reproduce it in full only if your docs workflow requires it.

wheels stats

Count files, lines of code, comments, and blanks by category (models, controllers, views, tests, and so on), then print a totals row and a code-to-test ratio.

Synopsis

wheels stats [--verbose | -v]

Flags

Flag	Description
--verbose, -v	Append a “Top 10 Largest Files” list after the totals row. Useful when hunting for views or controllers that have grown past the point of sanity.

Example

wheels stats

Sample output (trimmed):

Code Statistics
======================================================================
Category       Files    LOC   Comments   Blanks   Total
----------------------------------------------------------------------
Models             5    142         18       31     191
Controllers        6    287         42       68     397
Views             24    512         12       94     618
Tests             18    634         56      112     802
----------------------------------------------------------------------
Total             53   1575        128      305    2008

Code-to-test ratio: 1:0.67
Average lines/file: 29

wheels notes

Scan the project for inline annotations (TODO, FIXME, OPTIMIZE by default) and print each hit with its file path, line number, and the text after the marker.

Synopsis

wheels notes [--annotations=<list>] [--custom=<tag>]

Flags

Flag	Description
--annotations=<list>	Comma-separated list of markers to search for. Default: TODO,FIXME,OPTIMIZE. Case-insensitive.
--custom=<tag>	Additional single marker to include alongside the defaults (or the list set with --annotations=).

Example

wheels notes

Sample output (trimmed):

TODO (2):
  app/controllers/Posts.cfc:47 -- paginate once we break 100 posts
  app/models/User.cfc:112 -- extract password policy into a validator

FIXME (1):
  app/views/posts/show.cfm:23 -- escape HTML in the excerpt

Summary: 3 annotations (2 TODO, 1 FIXME)

When nothing matches, the command prints No annotations found. in green and exits.

wheels doctor

Run a battery of health checks against the project — required and recommended directories, required config files, write permissions, whether a datasource is configured, migration and test file counts, framework availability, and mixin collisions — and print a list of passes, warnings, and issues with an overall status. It reads files only; it does not connect to the database.

Synopsis

wheels doctor [--verbose | -v]

Flags

Flag	Description
--verbose, -v	Always print the list of passed checks. Without this flag, passes are shown only when the overall status is HEALTHY (i.e., zero issues and zero warnings).

Example

wheels doctor

Sample output (trimmed):

Wheels Health Check
========================================

Warnings (2):
  ! Missing recommended directory: tests/
  ! Missing recommended directory: tests/specs/

Status: WARNING

Recommendations:
  * Run 'wheels generate test' to add test coverage

Status is one of HEALTHY, WARNING, or CRITICAL. HEALTHY and WARNING exit 0; CRITICAL exits non-zero, so wheels doctor can gate a script. Issues (red) indicate the project cannot run as configured; warnings (yellow) flag things that work but look off; recommendations (cyan) are optional suggestions keyed off what the checks found.

wheels lookup

Look up the Wheels API reference and the guides offline. The CLI ships a docs index for its own framework version: every API function with its parameters and examples, and every guide section. It needs no network, no running server, and no project. AI assistants reach the same lookup through the lookup MCP tool.

Synopsis

wheels lookup <query> [--kind=all|api|guides] [--limit=5] [--format=text|json]

Arguments and flags

Argument / flag	Default	Description
<query>	(required)	A function name (findAll, findAll(), model.findAll), a phrase (nested resources), or an id from an earlier result (api:model.findAll, guides:basics/routing#nested-resources).
--kind	all	api searches only the API reference, guides only the guides.
--limit	5	The most results to list, from 1 to 20.
--format	text	json prints the result as JSON.

What it returns

• A function name prints the whole API entry: the signature and return type, where it’s available (model, controller, mapper, and so on), the description, every parameter with its type, default and description, the example, and the link to api.wheels.dev. A name that exists in several places (delete on a model object and on the route mapper) prints each one; model.delete narrows it to one.
• Anything else lists the best matches, guide sections and API functions together, each with a snippet, its link, and an id. Pass that id back to print the whole entry.
• Nothing matching prints No matches and exits 0.

Examples

wheels lookup findAll
wheels lookup "nested resources"
wheels lookup "background job retry" --kind=guides --limit=3
wheels lookup "guides:basics/routing#nested-resources"

The index describes the framework version the CLI was built with. When you run the CLI from a source checkout there’s no index until you build one with node tools/build/scripts/build-docs-index.mjs; until then wheels lookup says so and exits non-zero. For the browsable HTML docs offline, use wheels docs fetch.

Common workflows

Quick setup verification

wheels doctor

Run this first when a project acts strangely or when you’ve just cloned someone else’s app. If the status is HEALTHY or WARNING, you can usually start the server; CRITICAL means something is structurally wrong.

See what exists

illustrative — shell operators not supported

wheels info && wheels stats && wheels routes

Three commands, in order, give you: versions and environment, artifact counts, and the routing table. Run this after inheriting an app to orient yourself in under a minute. (Remember wheels routes needs a running server.)

Find stale work

wheels notes --annotations=TODO,FIXME,HACK,XXX

Sweep before a release. Widen the marker list with --annotations= or tack on a single extra tag with --custom=DEPRECATED.

Related commands

Configuration Where the settings that info and doctor read from actually live.

Creating a Project wheels new — produces the layout that doctor validates.

Code Quality wheels analyze, wheels validate — deeper diagnostic surfaces.

Upgrade wheels upgrade — run after info flags an outdated framework version.