Installation

Global Installation (Recommended)

Install globally to use monarch as a command anywhere:

# 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:

monarch --version
monarch --help

Local Installation

Install as a dev dependency in your project:

npm install --save-dev monarch-code-graph

Then run via npx or package.json scripts:

npx monarch analyze ./src

From Source

If you're developing Monarch or want the latest version:

# 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

monarch run (Recommended)

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.

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 <path> | Output artifact file path | monarch-graph.json | | -e, --exporter <name> | Exporter to use (mock, codeql-ts) | mock | | -p, --port <number> | Port for visualization server | 3000 | | --open | Open browser automatically | false | | -f, --force | Force regeneration even if no changes | false |

Examples:

# 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

monarch init

Initialize a new Monarch project in the current directory.

monarch init [options]

Options: | Option | Description | |--------|-------------| | -f, --force | Overwrite existing configuration |

Example:

# Create monarch.json configuration file
monarch init

# Overwrite existing config
monarch init --force

This creates a monarch.json configuration file and suggests .gitignore entries.

monarch analyze

Analyze a codebase and generate a flow artifact.

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 <path> | Output artifact file path | monarch-graph.json | | -e, --exporter <name> | Exporter to use (mock, codeql-ts) | mock | | -w, --watch | Watch for changes and re-analyze | false |

Examples:

# 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 |

monarch diff

Compare two graph artifacts and show changes.

monarch diff <baseline> <current> [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 <type> | Output format (text, json, markdown) | text | | --exit-on-changes | Exit with code 1 if changes detected | false | | --only <type> | Show only specific changes (functions, modules, edges) | - |

Examples:

# 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 |

monarch serve

Start the visualization UI server.

monarch serve [options]

Alias: monarch s

Options: | Option | Description | Default | |--------|-------------|---------| | -p, --port <number> | Port to serve on | 3000 | | -a, --artifact <path> | Artifact file path | monarch-graph.json | | --open | Open browser automatically | false |

Examples:

# 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

monarch list

List contents of a graph artifact.

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 <type> | Filter by type (functions, modules, components, edges) | - | | --json | Output as JSON | false |

Examples:

# 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:

{
  "exporter": "mock",
  "output": "monarch-graph.json",
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx"
  ],
  "exclude": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/node_modules/**"
  ]
}

CI/CD Integration

GitHub Actions

Add to your workflow:

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

PR Diff Workflow

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

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

# 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

# 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

"Command not found: monarch"

Ensure global npm/pnpm binaries are in your PATH:

# npm
export PATH="$PATH:$(npm config get prefix)/bin"

# pnpm
export PATH="$PATH:$(pnpm config get prefix)/bin"

CodeQL Exporter Fails

1. Verify CodeQL CLI is installed:

   codeql --version

2. If not installed, download from CodeQL CLI Binaries

3. Ensure the target project has JavaScript/TypeScript files

Artifact File Not Found

The default artifact path is monarch-graph.json in the current directory. Specify the path explicitly:

monarch list ./path/to/artifact.json
monarch serve --artifact ./path/to/artifact.json

License

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