CLI Commands

Global options

These options are available on all commands:

Option	Description
`--version`, `-V`	Print the Archgate version
`--help`, `-h`	Show help for any command

archgate --version
archgate check --help

Authenticate with GitHub to access Archgate editor plugins.

archgate login

Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores both in ~/.archgate/credentials.

Credentials are required to install editor plugins via archgate init --install-plugin. The CLI itself (check, init, mcp, etc.) works without login.

Subcommands

Subcommand	Description
`archgate login`	Authenticate (skips if already logged in)
`archgate login status`	Show current authentication status
`archgate login logout`	Remove stored credentials
`archgate login refresh`	Re-authenticate and claim a new token

Examples

archgate login

Authenticating with GitHub...

Open https://github.com/login/device in your browser
and enter the code: ABCD-1234

Waiting for authorization...
GitHub user: yourname
Claiming archgate plugin token...

Authenticated as yourname. Plugin access is now available.
Run `archgate init` to set up a project with the archgate plugin.

Check login status:

archgate login status

Logged in as yourname (since 2026-02-28)

Log out:

archgate login logout

Re-authenticate:

archgate login refresh

archgate init

Initialize Archgate governance in the current project.

archgate init [options]

Creates the .archgate/ directory with an example ADR, companion rules file, and linter configuration. Optionally configures editor integration for AI agent workflows and installs the Archgate editor plugin.

Options

Option	Default	Description
`--editor <editor>`	`claude`	Editor integration to configure (`claude`, `cursor`)
`--install-plugin`	auto	Install the Archgate editor plugin (requires prior `archgate login`)

When --install-plugin is passed, the CLI installs the Archgate plugin for the selected editor. If the flag is omitted, the CLI auto-detects: it installs the plugin when valid credentials exist (from a previous archgate login) and skips otherwise.

Plugin installation behavior

Claude Code: If the claude CLI is on your PATH, the plugin is installed automatically via claude plugin marketplace add and claude plugin install. If the claude CLI is not found, the command prints the manual installation commands instead.

Cursor: The plugin bundle is downloaded from plugins.archgate.dev and extracted into the .cursor/ directory.

Output

Initialized Archgate governance in /path/to/project
  adrs/          - architecture decision records
  lint/          - linter-specific rules
  .claude/       - Claude Code settings configured

Archgate plugin installed for Claude Code.

When --editor cursor is used, the output shows .cursor/ instead of .claude/.

Generated structure

.archgate/
  adrs/
    ARCH-001-example.md          # Example ADR
    ARCH-001-example.rules.ts    # Example rules file
  lint/
    archgate.config.ts           # Archgate configuration

archgate check

Run all automated ADR compliance checks against the codebase.

archgate check [options]

Loads every ADR with rules: true in its frontmatter, executes the companion .rules.ts file, and reports violations with file paths and line numbers.

Options

Option	Description
`--staged`	Only check git-staged files (useful for pre-commit hooks)
`--json`	Machine-readable JSON output
`--ci`	GitHub Actions annotation format
`--adr <id>`	Only check rules from a specific ADR
`--verbose`	Show passing rules and timing info

Exit codes

Code	Meaning
0	All rules pass. No violations found.
1	One or more violations detected.
2	Internal error (e.g., malformed ADR or rule).

Examples

Check the entire project:

archgate check

Check only staged files before committing:

archgate check --staged

Check a single ADR:

archgate check --adr ARCH-001

Get JSON output for CI integration:

archgate check --json

Get GitHub Actions annotations:

archgate check --ci

JSON output format

When --json is used, the output is a single JSON object:

{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "truncated": false,
  "results": [
    {
      "adrId": "ARCH-001",
      "ruleId": "register-function-export",
      "description": "Command file must export a register*Command function",
      "status": "fail",
      "totalViolations": 1,
      "shownViolations": 1,
      "violations": [
        {
          "message": "Command file must export a register*Command function",
          "file": "src/commands/broken.ts",
          "severity": "error"
        }
      ],
      "durationMs": 12
    }
  ],
  "durationMs": 42
}

archgate adr create

Create a new ADR interactively or via flags.

archgate adr create [options]

When run without --title and --domain, the command prompts interactively for the domain, title, and optional file patterns. When both --title and --domain are provided, it runs non-interactively.

The ADR ID is auto-generated with the domain prefix and the next available sequence number (e.g., ARCH-002, BE-001).

Options

Option	Description
`--title <title>`	ADR title (skip interactive prompt)
`--domain <domain>`	ADR domain (`backend`, `frontend`, `data`, `architecture`, `general`)
`--files <patterns>`	File patterns, comma-separated
`--body <markdown>`	Full ADR body markdown (skip template)
`--rules`	Set `rules: true` in frontmatter
`--json`	Output as JSON

Examples

Interactive mode:

archgate adr create

Non-interactive mode:

archgate adr create \
  --title "API Response Envelope" \
  --domain backend \
  --files "src/api/**/*.ts" \
  --rules

archgate adr list

List all ADRs in the project.

archgate adr list [options]

Options

Option	Description
`--json`	Output as JSON
`--domain <domain>`	Filter by domain

Examples

List all ADRs in table format:

archgate adr list

ID          Domain        Rules  Title
────────────────────────────────────────────────────────
ARCH-001    architecture  true   Command Structure
ARCH-002    architecture  true   Error Handling
BE-001      backend       true   API Response Envelope

List ADRs as JSON:

archgate adr list --json

Filter by domain:

archgate adr list --domain backend

archgate adr show

Print a specific ADR by ID.

archgate adr show <id>

Prints the full ADR content (frontmatter and body) to stdout.

Arguments

Argument	Description
`<id>`	ADR ID (e.g., `ARCH-001`, `BE-003`)

Example

archgate adr show ARCH-001

archgate adr update

Update an existing ADR by ID.

archgate adr update --id <id> --body <markdown> [options]

Replaces the ADR body with the provided markdown. Frontmatter fields (--title, --domain, --files, --rules) are updated only when explicitly passed; otherwise the existing values are preserved.

Options

Option	Required	Description
`--id <id>`	Yes	ADR ID to update (e.g., `ARCH-001`)
`--body <markdown>`	Yes	Full replacement ADR body markdown
`--title <title>`	No	New ADR title (preserves existing if omitted)
`--domain <domain>`	No	New domain (`backend`, `frontend`, `data`, `architecture`, `general`)
`--files <patterns>`	No	New file patterns, comma-separated (preserves existing if omitted)
`--rules`	No	Set `rules: true` in frontmatter
`--json`	No	Output as JSON

Example

archgate adr update \
  --id ARCH-001 \
  --title "Updated Command Structure" \
  --body "## Context\n\nUpdated context..."

archgate mcp

Start the MCP server for AI agent integration.

archgate mcp

Launches an MCP server using stdio transport. The server exposes tools for checking ADR compliance, listing ADRs, and retrieving review context. See the MCP Tools reference for the full list of available tools and resources.

The server starts even when no .archgate/ directory is found. In that case, tools return guidance directing the agent to initialize governance first.

Configuration

Add to your project’s MCP configuration (.mcp.json at the project root):

{
  "mcpServers": {
    "archgate": {
      "command": "archgate",
      "args": ["mcp"]
    }
  }
}

Running archgate init creates this configuration automatically for your editor.

archgate upgrade

Upgrade Archgate to the latest version via npm.

archgate upgrade

Checks the npm registry for the latest published version. If a newer version is available, runs npm install -g archgate@latest to upgrade. If already up-to-date, prints a message and exits.

Example

archgate upgrade

Checking for latest Archgate release...
Upgrading 0.3.0 -> 0.4.0...
Archgate upgraded to 0.4.0 successfully.

archgate clean

Remove the CLI cache directory.

archgate clean

Removes ~/.archgate/, which stores cached data such as update check timestamps. Safe to run at any time — the directory is recreated automatically when needed.

Example

archgate clean

/home/user/.archgate cleaned up