Monarch CLI

Command-line interface for Monarch - static codebase flow mapping and visualization.

Installation

$3

Install globally to use monarch as a command anywhere:

``bash


Using npm

npm install -g monarch-code-graph

Using pnpm

pnpm add -g monarch-code-graph

Using yarn

yarn global add 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 monarch

Install dependencies

pnpm install

Build all packages

pnpm build

Link 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 r

What 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 --open

Run on custom port

monarch run ./src -p 8080 --open

Force regeneration

monarch run ./src --force

With 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 init

Overwrite 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 a

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 |
| -w, --watch | Watch for changes and re-analyze | false |

Examples:
`bash


Analyze current directory

monarch analyze

Analyze a specific path

monarch analyze ./src

Specify output file

monarch analyze ./src -o my-graph.json

Use CodeQL exporter (requires CodeQL CLI)

monarch analyze ./src --exporter codeql-ts

Short 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 d

Arguments:
| 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.json

JSON output for programmatic use

monarch diff baseline.json current.json --format json

Markdown output for reports

monarch diff baseline.json current.json --format markdown

CI mode - fail if changes detected

monarch diff baseline.json current.json --exit-on-changes

Show 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 s

Options:
| 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 serve

Custom port

monarch serve --port 8080

Specify artifact and open browser

monarch serve --artifact my-graph.json --open

Short alias

monarch s -p 4000
`

---

$3

List contents of a graph artifact.

`bash
monarch list [artifact] [options]
`

Alias: monarch ls

Arguments:
| 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 list

List specific artifact

monarch list my-graph.json

Show only functions

monarch list --type functions

JSON output

monarch list --json

Show only modules as JSON

monarch list --type modules --json

Short 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 Analysis

on: [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 monarch

Install dependencies

pnpm install

Build all packages (required - CLI depends on other packages)

pnpm build

Run CLI directly

node packages/cli/dist/cli.js --help

Or link globally

cd packages/cli
pnpm link --global
monarch --help
`

Development

`bash


Run tests

pnpm --filter monarch-cli test

Watch mode

pnpm --filter monarch-cli test:watch

Type check

pnpm --filter monarch-cli typecheck

Build 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
``

License

Proprietary License - All rights reserved. See LICENSE for details.