Skip to content

cli.md

Latest commit

 

History

History
194 lines (137 loc) · 8.39 KB

cli.md

File metadata and controls

194 lines (137 loc) · 8.39 KB
Raw
title Standalone CLI
description Run the devtools from the command line, build a static report, or start an MCP server.
Three commands from one binary. A local devtools server, an offline report, and an MCP server for coding agents.

Standalone CLI

The package installs an ng-devtools binary. Run it from the root of your Angular workspace, or point it there with --root. It scans the source files in that folder, so it works without starting your app.

Commands

Command What it does
dev Starts a local server with the devtools UI.
build Writes a static copy of the devtools with the scan.
mcp Starts an MCP server over stdio for coding agents.

ng-devtools --version prints the package version. An unknown command or flag prints one error line and exits with code 1. ng-devtools --help lists the commands and flags.

Flags for every command

Flag What it does
--root <dir> The project folder to scan. The default is NG_DEVTOOLS_ROOT, then the working directory.
--config <file> A JSON file with the devtools options. The default is NG_DEVTOOLS_CONFIG, then ng-devtools.config.json in the project folder, if it exists.
--read-only Sets agent.readOnly: drops the agent tools that act on the page or the server. See Inspectors and agent tools.

If the project folder has no angular.json and no package.json that depends on @angular/core, the CLI prints a warning on stderr, because the scans find nothing there.

Config file

The file holds the same options as createNgDevtools(), as JSON:

// ng-devtools.config.json
{
  "inspectors": {"analog": false},
  "agent": {"readOnly": true},
  "redaction": {"secretNames": ["passport"]}
}

A missing --config file or invalid JSON stops the command with an error.

Run it without installing

npx @santoshyadavdev/ng-devtools dev
pnpm dlx @santoshyadavdev/ng-devtools dev
yarn dlx @santoshyadavdev/ng-devtools dev
bunx @santoshyadavdev/ng-devtools dev

Run the installed binary

With the package installed in your project, call the binary through your package manager:

npx ng-devtools dev
npx ng-devtools build --outDir dist-report
npx ng-devtools mcp

Dev server

Start it

The default command starts a local server with the devtools UI. dev is optional: npx @santoshyadavdev/ng-devtools does the same.

npx @santoshyadavdev/ng-devtools dev --port 9999 --open

When the server is ready, it prints the version, the panel URL and the MCP endpoint:

  ng-devtools v0.0.5
  Panel: http://localhost:9999/
  MCP:   http://localhost:9999/__mcp

If you pass no --port and port 9999 is taken, it also prints the port it uses instead.

Dev server flags

Flag What it does
--port <port> Port to listen on. The default is 9999. If it is taken, a random free port is used.
--host <host> Host to bind to. The default is localhost.
--open, --no-open Open the browser on start, or not.
--no-auth Turn off the one-time code the server asks for.
--mcp, --no-mcp Mount the MCP endpoint at /__mcp, or not. It is on by default.
The server binds to localhost by default and asks for a one-time code. Changing --host or passing --no-auth widens who can reach it. See Access and redaction.

What it shows

No page is connected to the CLI server. The tabs show what your source declares:

For live data, mount the devtools in your app's own server. See Angular CLI and Express or Vite and Analog.

Static report

Build it

build writes a self-contained static copy of the devtools with the source scan baked in: components, routes, signals, providers, pipes, NgRx declarations and build metadata.

npx @santoshyadavdev/ng-devtools build --outDir dist-report

Report flags

Flag What it does
--outDir <dir> Output directory. The default is dist-static. It is emptied first.
--pretty Pretty-print the data files. They get larger on disk.
--force Empty --outDir even when it holds files that are not a previous report.

Output folder checks

The build deletes everything in --outDir before it writes the report. To protect your files, it stops with an error when --outDir is:

  • the working directory or one of its parents, even with --force. With --root, this covers both the folder you ran the command from and the --root folder,
  • a file, or a folder that is not empty and has no __connection.json (so it is not a previous report), unless you pass --force.

Open or host it

The output is static files. Open it offline or host it on any static file server. It is a snapshot of your source at build time, so rebuild it after code changes.

MCP server

Start it over stdio

mcp starts an *MCP server over stdio for coding agents:

npx @santoshyadavdev/ng-devtools mcp

Your agent client runs this command for you. MCP server covers client setup.

Source scan only

The stdio server has no page connected, so it registers only the tools that read your source files. The tools that need a page, such as highlight, navigate, form-action and the forms and router tools, are left out. For live data, point your agent at the HTTP endpoint of a running app instead. On a hub it lives at /__devframes/__mcp.

FAQ

No. All three commands read your source files. Only live data needs a running app with the overlay loaded. The root of your Angular workspace. The scan starts from the current directory, or from the folder you pass with --root. Without --port, the server picks a random free port and prints it. Pass --port to choose one yourself.

Where to next

Client setup for stdio, and the HTTP endpoint for live data. Mount the hub in your app for live inspectors.