Command reference

The mago analyze command is the entry point for running Mago's static type checker.

TIP

For global options that can be used with any command, see the Command-Line Interface overview. Remember to specify global options before the analyze command.

Usage: mago analyze [OPTIONS] [PATHS]...

TIP

mago analyse is a convenient alias for mago analyze. Both can be used interchangeably.

Arguments

[PATHS]...

Optional. A list of specific files or directories to analyze. If you provide paths here, they will be used instead of the paths defined in your mago.toml configuration.

Options

Flag, Alias(es)	Description
--no-stubs	Analyze the project without loading the built-in PHP stubs for the standard library.
--staged	Only analyze files that are staged in git. Designed for pre-commit hooks. Fails if not in a git repository.
--stdin-input	Read file content from stdin and use the single path argument for baseline and reporting. Intended for editor integrations (e.g. unsaved buffers). Requires exactly one path.
--watch	Enable watch mode for continuous analysis. Re-runs analysis when files change. See Watch Mode below.
--list-codes	List all available analyzer issue codes in JSON format.
--help, -h	Print the help summary for the command.

Reading from stdin (editor integration)

When using an editor or IDE that can pipe unsaved buffer content, you can run the analyzer on that content while still using the real file path for baseline lookup and issue locations:

cat src/Example.php | mago analyze --stdin-input src/Example.php

You must pass exactly one path; it is used as the logical file name (workspace-relative) for baseline matching and diagnostics. The path is normalized (e.g. ./src/Example.php is treated like src/Example.php). This mode conflicts with --staged and --watch.

Shared Reporting and Fixing Options

The analyze command shares a common set of options with other Mago tools for reporting, fixing, and baseline management.

See the Shared Reporting and Fixing Options documentation.

Watch Mode

When --watch is enabled, the analyzer continuously monitors your workspace for changes and automatically re-runs analysis whenever PHP files are modified, created, or deleted.

mago analyze --watch

Automatic Restart

In addition to PHP file changes, the analyzer watches for changes to project configuration files. When any of the following files change, the analyzer automatically restarts with the reloaded configuration:

• Configuration file — the mago.toml (or whichever config file was loaded)
• Baseline file — if configured via analyzer.baseline
• composer.json and composer.lock

This means you can edit your mago.toml (e.g., add an ignore rule or change a setting) and the analyzer will pick up the changes without needing to manually restart.

TIP

If no configuration file exists when watch mode starts, the analyzer watches for the creation of any supported config file (mago.toml, mago.yaml, mago.json, etc.) and restarts when one appears.

Press Ctrl+C to stop watching.