archgate adr

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. Built-ins: backend, frontend, data, architecture, general. Custom domains must first be registered via archgate adr domain add. | | --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. Built-ins: backend, frontend, data, architecture, general. Custom domains must first be registered via archgate adr domain add. | | --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 adr domain

Manage custom ADR domains. Custom domains are name → ID-prefix mappings persisted in .archgate/config.json and merged with the five built-ins (backend, frontend, data, architecture, general) at read time.

Use this command when a decision doesn’t cleanly fit any built-in domain. Before registering a new one, check whether the decision can be folded under an existing domain — built-ins are the default and a custom domain should only be introduced when no built-in is a genuine fit.

archgate adr domain <subcommand> [options]

Subcommands

| Subcommand | Description | | ----------------------------------------- | -------------------------------------------------------------- | | archgate adr domain list | Show all merged (built-in + custom) domains and their prefixes | | archgate adr domain add <name> <prefix> | Register a custom domain | | archgate adr domain remove <name> | Unregister a custom domain (built-ins cannot be removed) |

Naming rules

• <name> — lowercase kebab-case, 2–32 chars (e.g., security, ml-ops)
• <prefix> — uppercase letters, digits, or underscores, 2–10 chars (e.g., SEC, MLOPS)
• Custom names and prefixes cannot collide with built-ins or with any other custom entry.

Options

| Option | Applies to | Description | | -------- | --------------- | -------------- | | --json | all subcommands | Output as JSON |

Examples

List built-in and custom domains:

archgate adr domain list

Domain          Prefix    Source
────────────────────────────────
architecture    ARCH      default
backend         BE        default
data            DATA      default
frontend        FE        default
general         GEN       default
security        SEC       custom

Register a custom domain:

archgate adr domain add security SEC

Remove a custom domain:

archgate adr domain remove security

---

archgate adr import

Import ADRs from the registry or a git repository.

archgate adr import <source...> [options]

The command clones the source, reads ADR files, remaps IDs to fit the local project’s sequence, and writes them to .archgate/adrs/. It tracks imports in .archgate/imports.json so they can later be checked for upstream updates via archgate adr sync.

Arguments

| Argument | Description | | ------------- | ------------------------------------------------ | | <source...> | Registry path(s), org/repo/path, or git URL(s) |

Options

| Option | Description | | ----------- | ------------------------------- | | --yes | Skip confirmation prompt | | --json | Output as JSON | | --dry-run | Preview changes without writing | | --list | List previously imported ADRs |

Examples

Import from the registry:

archgate adr import archgate/packs/typescript

Import from a git repository:

archgate adr import https://github.com/acme/adr-packs.git

Preview what would be imported without writing any files:

archgate adr import archgate/packs/typescript --dry-run

Import non-interactively (skip confirmation):

archgate adr import archgate/packs/typescript --yes

List previously imported ADRs:

archgate adr import --list

---

archgate adr sync

Check for upstream updates to imported ADRs.

archgate adr sync [source...] [options]

The command compares local imported ADRs against their upstream source and shows which sections changed. In interactive mode, it prompts for each changed ADR with three choices: keep local, take upstream, or skip.

Arguments

| Argument | Description | | ------------- | ------------------------------------------------------ | | [source...] | Optional source filter(s) — sync only matching imports |

Options

| Option | Description | | --------- | ---------------------------------------- | | --check | Exit 1 if upstream has updates (CI mode) | | --yes | Skip confirmation prompts | | --json | Output as JSON |

Examples

Check all imported ADRs for upstream updates:

archgate adr sync

Check only imports from a specific source:

archgate adr sync archgate/packs/typescript

CI mode — fail the build if any imported ADR is outdated:

archgate adr sync --check

Accept all upstream updates non-interactively:

archgate adr sync --yes