Skip to content
Archgate

Quick Start

1. Install Archgate

Section titled “1. Install Archgate”

If you have not installed the CLI yet:

Terminal window
# Standalone (no Node.js required)
curl -fsSL https://cli.archgate.dev/install-unix | sh


# Or via npm
npm install -g archgate

See the Installation page for all options, including Windows and custom install directories.

2. Initialize your project

Section titled “2. Initialize your project”

Navigate to your project root and run the init command:

Terminal window
cd my-project
archgate init

This creates the .archgate/ directory with the following structure:

.archgate/
  adrs/
    GEN-001-example.md   # Example ADR (rules: false)
  lint/
    README.md            # Conventions for linter-specific rules
  rules.d.ts              # Type definitions for .rules.ts files

The generated files give you a working example to build on.

3. Edit the example ADR

Section titled “3. Edit the example ADR”

Open .archgate/adrs/GEN-001-example.md. Every ADR starts with YAML frontmatter that defines its identity:

---
id: GEN-001
title: Example Architecture Decision
domain: general
rules: false
---
  • id: Unique identifier. Convention is <PREFIX>-NNN (e.g. ARCH-001, GEN-001) but any string works.
  • title: Human-readable name for the decision.
  • domain: Groups related ADRs together (architecture, backend, frontend, data, or general).
  • rules: Set to true if this ADR has a companion .rules.ts file with automated checks. The generated example ships with rules: false.
  • files: Optional glob patterns that scope which files the rules apply to. Omit it to scope the whole project.

Below the frontmatter, write the decision in Markdown. Archgate does not enforce a specific section structure, but the recommended sections are: Context, Decision, Do’s and Don’ts, Consequences, Compliance, and References.

4. Add a companion rules file

Section titled “4. Add a companion rules file”

Create a .rules.ts file next to your ADR with the same name prefix (e.g. GEN-001-example.rules.ts for the generated example). Then set rules: true in the ADR’s frontmatter — archgate check only loads a companion rules file when the ADR opts in. Rules are written in TypeScript using the RuleSet type:

/// <reference path="../rules.d.ts" />


export default {
  rules: {
    "no-console-error": {
      description: "Use logError() instead of console.error()",
      async check(ctx) {
        for (const file of ctx.scopedFiles) {
          const matches = await ctx.grep(file, /console\.error\(/);
          for (const match of matches) {
            ctx.report.violation({
              message: "Use logError() instead of console.error()",
              file: match.file,
              line: match.line,
              fix: "Import logError from your helpers and use it instead",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;

Each rule has a unique key, a description, and an async check function. Inside check, you have access to:

  • ctx.scopedFiles: Files matching the ADR’s files glob patterns.
  • ctx.grep(file, pattern): Search a file for regex matches, returning file paths and line numbers.
  • ctx.report.violation(): Report a violation with a message, file path, line number, and optional fix suggestion.

5. Run checks

Section titled “5. Run checks”

Run the compliance checker against your codebase:

Terminal window
archgate check

Archgate loads every ADR with rules: true, executes its companion rules file, and prints results. The exit code tells you the outcome:

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

To check only staged files (useful in pre-commit hooks or CI):

Terminal window
archgate check --staged

What’s next?

Section titled “What’s next?”

Now that you have a working setup, dive deeper:

Understand the concepts:

  • ADRs: What Architecture Decision Records are and how Archgate uses them.
  • Rules: How companion .rules.ts files turn decisions into automated checks.
  • Domains: How domains group related ADRs and scope file matching.

Write your own:

  • Writing ADRs: Learn the full ADR format and best practices for writing effective decisions.
  • Writing Rules: Explore the rule API, advanced patterns, and how to test your rules.
  • Common Rule Patterns: Copy-pasteable patterns for dependency checks, naming conventions, and more.

Integrate into your workflow: