CLI Commands

Erode provides five commands for working with architecture models and analyzing change requests.

Installation

npm install -g @erode-app/cli

Or run directly with npx:

npx @erode-app/cli --help

Commands

analyze [model-path]

Analyze a change request for architecture drift.

erode analyze ./model --url https://github.com/org/repo/pull/42
erode analyze ./model --url https://gitlab.com/group/project/-/merge_requests/42
erode analyze ./model --url https://bitbucket.org/workspace/repo/pull-requests/42

Flag	Description	Default
--url <url>	Change request URL (GitHub PR, GitLab MR, or Bitbucket PR). Required.
--model-format <fmt>	Architecture model format	likec4
--format <fmt>	Output format: console, json	console
--open-pr	Create a PR with model updates (see below)
--model-repo <owner/repo>	Target repository for model PRs (defaults to the analyzed repo)
--model-ref <ref>	Branch or tag to clone from --model-repo	main
--patch-local	Patch the architecture model in-place (see below)
--dry-run	Preview without creating a PR or writing patches
--draft	Create change request as draft	true
--output-file <path>	Write structured JSON output to a file
--skip-file-filtering	Analyze all changed files (skip pattern-based filtering)
--comment	Post analysis results as a PR/MR comment
--github-actions	Write GitHub Actions outputs and step summary
--fail-on-violations	Exit with code 1 when violations are found

--patch-local behavior

--patch-local runs Stage 4 (Model Update) and writes the patched model file in-place. Combine with --dry-run to preview the patch without writing.

--open-pr behavior

--open-pr implies --patch-local. After generating the patch (Stage 4), it creates a pull request against the model repository with the updated relationship declarations.

• PRs are created as drafts by default (GitHub/GitLab). Bitbucket has no draft support.
• The PR body includes a link to the source analysis PR for traceability.
• If a subsequent analysis finds no violations, any existing model PR for that source PR is automatically closed.

Note

Relationship removals are informational only. The PR body lists relationships that may need removal, but the reviewer must remove them manually.

check [model-path]

Check local changes for architectural drift before pushing. Uses the same AI pipeline as analyze (Stages 1-3) but operates on local git diffs instead of fetching PR data from a platform API.

erode check ./model --repo https://github.com/org/repo
erode check ./model --staged
erode check ./model --branch main

Flag	Description	Default
--repo <url>	Repository URL (auto-detected from git remote if omitted)
--model-format <fmt>	Architecture model format	likec4
--staged	Only check staged changes	false
--branch <branch>	Compare against a branch (e.g. main)
--component <id>	Component ID to analyze (skips AI component selection)
--format <fmt>	Output format: console, json	console
--fail-on-violations	Exit with code 1 when violations are found
--skip-file-filtering	Analyze all changed files (skip pattern-based filtering)
--model-repo <repo>	Clone architecture model from this repository
--model-ref <ref>	Branch or tag to clone from model repository

When no flags are passed, check analyzes unstaged changes (git diff). Use --staged for pre-commit hooks and --branch main for pre-push hooks.

Git hook integration

.husky/pre-commit

erode check ./architecture --staged --fail-on-violations

# .husky/pre-push
erode check ./architecture --branch main --fail-on-violations

components [model-path]

List components from an architecture model.

erode components ./model
erode components ./model --format json

Flag	Description	Default
--model-format <fmt>	Architecture model format	likec4
--format <fmt>	Output format: table, json, yaml	table

connections [model-path]

Show component connections from an architecture model.

erode connections ./model --repo https://github.com/org/repo
erode connections ./model --repo https://gitlab.com/group/project

Flag	Description	Default
--repo <url>	Repository URL. Required.
--model-format <fmt>	Architecture model format	likec4
--output <fmt>	Output format: console, json	console

validate [model-path]

Check that all components in an architecture model have repository links.

erode validate ./model
erode validate ./model --format json

Flag	Description	Default
--model-format <fmt>	Architecture model format	likec4
--format <fmt>	Output format: table, json	table

Exits with code 1 if any components are missing repository links.

Environment variables

Erode reads configuration from environment variables and .eroderc.json. Set your platform token and AI provider API key before running any command. See Configuration for the full reference and Authentication for token permission requirements.

Example

export ERODE_GITHUB_TOKEN="ghp_..."
export ERODE_GEMINI_API_KEY="AIza..."

node packages/cli/dist/cli.js analyze ./architecture \
  --url https://github.com/acme/backend/pull/42 \
  --comment \
  --fail-on-violations

What’s next

• Configuration: environment variables for tuning diff limits, timeouts, and model overrides
• Integrations: run Erode automatically on every pull request
• AI Providers: supported providers and model selection