CLI tool for Monarch - Static codebase flow mapping and visualization
npm install monarch-code-graph

Command-line interface for Monarch - static codebase flow mapping and visualization.
Install globally to use monarch as a command anywhere:
``bashUsing npm
npm install -g monarch-code-graph
After installation, the
monarch command will be available globally:`bash
monarch --version
monarch --help
`$3
Install as a dev dependency in your project:
`bash
npm install --save-dev monarch-code-graph
`Then run via npx or package.json scripts:
`bash
npx monarch analyze ./src
`$3
If you're developing Monarch or want the latest version:
`bash
Clone the repository
git clone https://github.com/your-username/monarch.git
cd monarchInstall dependencies
pnpm installBuild all packages
pnpm buildLink CLI globally
cd packages/cli
pnpm link --global
`Commands
$3
All-in-one command that analyzes your codebase, detects changes, and starts the visualization server. This is the recommended way to use Monarch during development.
`bash
monarch run [path] [options]
`Alias:
monarch rWhat it does:
1. Checks if a graph artifact already exists
2. If exists, analyzes the codebase and compares for changes
3. If no changes detected, skips regeneration (fast!)
4. If changes detected, generates a new artifact
5. Starts the visualization server
6. Opens the browser (with
--open flag)Arguments:
| Argument | Description | Default |
|----------|-------------|---------|
|
path | Path to the codebase to analyze | . (current directory) |Options:
| Option | Description | Default |
|--------|-------------|---------|
|
-o, --output | Output artifact file path | monarch-graph.json |
| -e, --exporter | Exporter to use (mock, codeql-ts) | mock |
| -p, --port | Port for visualization server | 3000 |
| --open | Open browser automatically | false |
| -f, --force | Force regeneration even if no changes | false |Examples:
`bash
Quick start - analyze and visualize
monarch run ./src --openRun on custom port
monarch run ./src -p 8080 --openForce regeneration
monarch run ./src --forceWith custom output file
monarch r ./src -o my-graph.json
`---
$3
Initialize a new Monarch project in the current directory.
`bash
monarch init [options]
`Options:
| Option | Description |
|--------|-------------|
|
-f, --force | Overwrite existing configuration |Example:
`bash
Create monarch.json configuration file
monarch initOverwrite existing config
monarch init --force
`This creates a
monarch.json configuration file and suggests .gitignore entries.---
$3
Analyze a codebase and generate a flow artifact.
`bash
monarch analyze [path] [options]
`Alias:
monarch aArguments:
| Argument | Description | Default |
|----------|-------------|---------|
|
path | Path to the codebase to analyze | . (current directory) |Options:
| Option | Description | Default |
|--------|-------------|---------|
|
-o, --output | Output artifact file path | monarch-graph.json |
| -e, --exporter | Exporter to use (mock, codeql-ts) | mock |
| -w, --watch | Watch for changes and re-analyze | false |Examples:
`bash
Analyze current directory
monarch analyzeAnalyze a specific path
monarch analyze ./srcSpecify output file
monarch analyze ./src -o my-graph.jsonUse CodeQL exporter (requires CodeQL CLI)
monarch analyze ./src --exporter codeql-tsShort alias
monarch a ./src -o graph.json
`Exporters:
| Exporter | Description | Requirements |
|----------|-------------|--------------|
|
mock | Fast regex-based TypeScript analysis | None |
| codeql-ts | Production-grade CodeQL analysis | CodeQL CLI |---
$3
Compare two graph artifacts and show changes.
`bash
monarch diff [options]
`Alias:
monarch dArguments:
| Argument | Description |
|----------|-------------|
|
baseline | Path to the baseline artifact |
| current | Path to the current artifact |Options:
| Option | Description | Default |
|--------|-------------|---------|
|
-f, --format | Output format (text, json, markdown) | text |
| --exit-on-changes | Exit with code 1 if changes detected | false |
| --only | Show only specific changes (functions, modules, edges) | - |Examples:
`bash
Compare two artifacts (text output)
monarch diff baseline.json current.jsonJSON output for programmatic use
monarch diff baseline.json current.json --format jsonMarkdown output for reports
monarch diff baseline.json current.json --format markdownCI mode - fail if changes detected
monarch diff baseline.json current.json --exit-on-changesShow only function changes
monarch diff baseline.json current.json --only functions
`Exit Codes:
| Code | Meaning |
|------|---------|
|
0 | No changes detected (or --exit-on-changes not set) |
| 1 | Changes detected (with --exit-on-changes) or error |---
$3
Start the visualization UI server.
`bash
monarch serve [options]
`Alias:
monarch sOptions:
| Option | Description | Default |
|--------|-------------|---------|
|
-p, --port | Port to serve on | 3000 |
| -a, --artifact | Artifact file path | monarch-graph.json |
| --open | Open browser automatically | false |Examples:
`bash
Start server with defaults
monarch serveCustom port
monarch serve --port 8080Specify artifact and open browser
monarch serve --artifact my-graph.json --openShort alias
monarch s -p 4000
`---
$3
List contents of a graph artifact.
`bash
monarch list [artifact] [options]
`Alias:
monarch lsArguments:
| Argument | Description | Default |
|----------|-------------|---------|
|
artifact | Path to artifact file | monarch-graph.json |Options:
| Option | Description | Default |
|--------|-------------|---------|
|
-t, --type | Filter by type (functions, modules, components, edges) | - |
| --json | Output as JSON | false |Examples:
`bash
List all contents
monarch listList specific artifact
monarch list my-graph.jsonShow only functions
monarch list --type functionsJSON output
monarch list --jsonShow only modules as JSON
monarch list --type modules --jsonShort alias
monarch ls my-graph.json -t edges
`Configuration File
Create a
monarch.json file in your project root:`json
{
"exporter": "mock",
"output": "monarch-graph.json",
"include": [
"src/*/.ts",
"src/*/.tsx"
],
"exclude": [
"*/.test.ts",
"*/.spec.ts",
"/node_modules/"
]
}
`CI/CD Integration
$3
Add to your workflow:
`yaml
name: CodeFlow Analysison: [push, pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- run: pnpm install
- name: Generate artifact
run: npx monarch analyze ./src -o artifact.json
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: monarch-artifact
path: artifact.json
`$3
`yaml
- name: Generate current
run: npx monarch analyze ./src -o current.json... checkout base branch and generate baseline ...
- name: Compare
run: npx monarch diff baseline.json current.json --format markdown >> $GITHUB_STEP_SUMMARY
`Programmatic Usage
The CLI can also be used programmatically:
`typescript
import { analyzeCommand, diffCommand } from 'monarch-cli';// Analyze
await analyzeCommand('./src', {
output: 'graph.json',
exporter: 'mock',
watch: false,
});
// Diff
await diffCommand('baseline.json', 'current.json', {
format: 'json',
exitOnChanges: false,
});
`Building from Source
`bash
Clone repository
git clone https://github.com/your-username/monarch.git
cd monarchInstall dependencies
pnpm installBuild all packages (required - CLI depends on other packages)
pnpm buildRun CLI directly
node packages/cli/dist/cli.js --helpOr link globally
cd packages/cli
pnpm link --global
monarch --help
`Development
`bash
Run tests
pnpm --filter monarch-cli testWatch mode
pnpm --filter monarch-cli test:watchType check
pnpm --filter monarch-cli typecheckBuild only CLI
pnpm --filter monarch-cli build
`Troubleshooting
$3
Ensure global npm/pnpm binaries are in your PATH:
`bash
npm
export PATH="$PATH:$(npm config get prefix)/bin"pnpm
export PATH="$PATH:$(pnpm config get prefix)/bin"
`$3
1. Verify CodeQL CLI is installed:
`bash
codeql --version
`2. If not installed, download from CodeQL CLI Binaries
3. Ensure the target project has JavaScript/TypeScript files
$3
The default artifact path is
monarch-graph.json in the current directory. Specify the path explicitly:`bash
monarch list ./path/to/artifact.json
monarch serve --artifact ./path/to/artifact.json
``Proprietary License - All rights reserved. See LICENSE for details.