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, vscode, copilot, opencode)
--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: Downloads an authenticated tarball of skills, agents, and hooks into ~/.cursor/. Also writes .cursor/hooks.json to the project for cloud agent compatibility. No CLI detection needed.

opencode: Requires the opencode CLI to be on your PATH — if it’s not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory ($XDG_CONFIG_HOME/opencode/agents/, falling back to $HOME/.config/opencode/agents/ on every platform including Windows — opencode uses XDG paths via xdg-basedir and does not read %APPDATA%). No files are written to the project tree. See the opencode integration guide for details.

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/ for project-level files and notes that user-scope components were installed to ~/.cursor/.

Base branch detection

When run inside a git repository, archgate init auto-detects the base branch and saves it to .archgate/config.json as the baseBranch field. This allows archgate check to skip branch detection on every run, saving 1-4 git subprocess calls.

The detection tries origin/HEAD, origin/main, origin/master, local main, and local master (first match wins). If none are found (e.g., not a git repo), no baseBranch is written.

Re-running archgate init does not overwrite a manually configured baseBranch. See Configuration — baseBranch for details.

Generated structure

.archgate/
  adrs/
    GEN-001-example.md           # Example ADR
    GEN-001-example.rules.ts     # Example rules file
  lint/
    README.md                    # Linter rules guide