CLI Command Reference | ArchPilot Docs

Search docs

Docs search

CLI Command Reference

A user-facing reference for the main ArchPilot CLI workflows: initialization, validation, history, policy, exceptions, review generation, governance upload, and related architecture tooling.

Why it matters

This reference groups the most important commands by workflow so teams can find the right architecture validation or governance action quickly.

How to use this reference

This page groups the current public ArchPilot command surface by workflow so teams can find the right action quickly.

The command groups below are written for product users, not repository contributors. Where this workspace provides a concrete file, workflow, or artifact, the examples here reflect that current behavior.

Setup and initialization

Use this group when you are setting up ArchPilot in a repository for the first time or refreshing the core project scaffolding.

Start with init, then add contracts and supporting files as the repository moves from initial setup into day-to-day validation.

Use Smart Init in the VS Code experience when you want ArchPilot to detect repository structure before you finalize setup.

Validate locally:

archpilot init
archpilot validate

Setup and initialization commands

Command	Purpose	When to use it	What it produces	Important note
archpilot init	Create the initial ArchPilot repository setup.	Use it the first time you add ArchPilot to a repository.	Starting configuration and architecture metadata files.	Run this before validate when the repository does not already have ArchPilot config.
archpilot bootstrap	Add or refresh the broader ArchPilot scaffolding around the repository.	Use it after init when you want the surrounding support files in place.	Supporting ArchPilot files for reporting, policy, or dependency workflows.	Bootstrap expands setup. It does not replace validate.
archpilot contracts generate	Generate module contract files for dependency and boundary checks.	Use it when your module boundaries are ready to be made explicit.	Contract files under .archpilot/contracts or the repository's current contract location.	Regenerate contracts after structural changes so validation stays aligned with the codebase.

Validation and reporting

archpilot validate is the core local command. It produces findings, scores, readiness, and report artifacts without uploading anything by itself.

ArchPilot writes validation outputs such as status, report, and history artifacts for the repository.

Validate locally:

archpilot validate

CI validation

archpilot validate --ci

Changed-scope validation

archpilot validate --changed

Diff-based validation

archpilot validate --diff --base main

Validation modes

Command	Purpose	When to use it	What it produces	Important note
archpilot validate	Run a full local validation pass.	Use in local development before opening a pull request or before governance upload.	Findings, scores, readiness, and local report artifacts.	Validation is local. It does not upload on its own.
archpilot validate --ci	Run validation in blocking automation.	Use in GitHub Actions or any other CI pipeline.	The same validation result with CI-oriented exit behavior.	This is the blocking automation path in the checked-in GitHub Actions workflow.
archpilot validate --changed	Validate the changed portion of the repository.	Use it when you want faster feedback focused on the current change.	A validation pass scoped to changed files or modules.	Use a full archpilot validate before governance upload or release decisions.
archpilot validate --diff	Validate a diff-oriented change set.	Use it during pull request review or when you want change-focused architecture feedback.	Diff-scoped architecture validation output.	This is best for review workflows, not for producing the canonical repository snapshot.
archpilot validate --base <ref>	Set the comparison base for changed or diff validation.	Use it when the base branch matters, such as feature branches against main.	Validation that resolves scope relative to the specified base.	Choose the base deliberately so changed-scope validation reflects the right comparison.

Reporting and review commands

Command	Purpose	When to use it	What it produces	Important note
archpilot report	Render a readable summary from the latest validation state.	Use it when you want a human-friendly handoff after a validation run.	A summary report based on the latest local artifacts.	Run validate first so the report reflects the current repository state.
archpilot review generate	Create review-ready artifacts from the current validation result.	Use it when you want to package findings for review before sharing them.	Local review artifacts derived from the latest validation state.	This prepares review output. It does not replace validate.
archpilot review pr	Shape review output for a pull-request workflow.	Use it when you want architecture review material aligned to a pull request discussion.	PR-oriented review output based on the current validation result.	Run validate first so the PR review reflects the latest findings.

Drift, baselines, and history

Baselines answer a different question from Cloud snapshot history. Baselines compare the current local architecture state against an accepted reference. Cloud snapshot history stores uploaded governance state over time.

Drift reports can point users to archpilot baseline create, archpilot baseline check, and archpilot baseline refresh.

Typical baseline workflow

archpilot validate
archpilot baseline create
archpilot baseline check

Baseline and history commands

Command	Purpose	When to use it	What it produces	Important note
archpilot baseline create	Capture the first accepted architecture baseline.	Use it after validation when the current state is the baseline you want to keep.	A saved baseline reference for later drift comparison.	Create a baseline only after the current architecture state is acceptable.
archpilot baseline update	Replace the accepted baseline.	Use it when the intended architecture has changed and the baseline should move forward.	An updated accepted baseline.	Update the baseline deliberately so real regressions do not disappear into the new reference.
archpilot baseline check	Compare the current state to the accepted baseline.	Use it when you want to see drift or regression against the stored reference.	Baseline comparison output and drift signals.	Run validate first so the comparison uses current artifacts.
archpilot baseline refresh	Refresh baseline artifacts after a new accepted run.	Use it when the current validated state should become the new accepted reference.	Refreshed baseline data for future comparisons.	Refresh follows acceptance. It is not a substitute for review.
archpilot history	Review architecture trend history over time.	Use it when you want to inspect how posture has changed across runs.	Local history views based on prior validation artifacts.	History helps explain trend direction. It does not replace a baseline comparison.

Architecture analysis and docs

Use this group when you need a clearer view of repository structure, blast radius, diagrams, or onboarding context.

These commands help teams inspect and explain architecture, not just validate it.

archpilot impact: inspect likely architecture blast radius or change impact when a structural change spans multiple modules.
archpilot map: generate or inspect an architecture map view from the repository model.
archpilot diagrams generate: produce diagram-oriented outputs from the architecture model when your team wants a visual summary.
archpilot docs onboarding: open or generate onboarding guidance for the repository.
archpilot project show: inspect the current project architecture context and effective local setup.

Governance and Cloud

Governance upload is separate from validation. Use it only after the repository already has current local validation artifacts.

Validation must run before upload so ArchPilot can generate the required artifacts.

Explicit flags are clearest in CI. Saved .archpilot/config.json settings are convenient for repeated local use.

Manual governance upload is available on all plans. Automatic CI upload to Cloud on main is available on paid plans.

Use explicit flags in CI so the workflow shows exactly which ArchPilot Cloud URL and token it is using.
Use saved config locally when the same repository uploads to the same ArchPilot Cloud organization repeatedly.

Use the ArchPilot Cloud URL:

https://api.archpilot.org

Validate locally:

archpilot validate

Upload explicitly:

archpilot governance upload --server https://api.archpilot.org --token <organization-api-token>

Saved Cloud connection in .archpilot/config.json

{
  "cloud": {
    "server": "https://api.archpilot.org",
    "token": "ap_live_1234567890_example",
    "uploadOnValidate": true
  }
}

Governance and Cloud commands

Command	Purpose	When to use it	What it produces	Important note
archpilot governance upload	Upload the current validated snapshot to ArchPilot Cloud.	Use it after validate when you want repository history, findings, snapshots, and governance visibility in Cloud.	A stored Cloud snapshot tied to the repository identity and organization API token.	Validate first. Upload is explicit and separate.
archpilot compliance export	Export a shareable compliance or governance view from the current result set.	Use it when you need to share governance output outside the terminal.	Exported compliance or governance artifacts from the current local result.	Run validate first so the export reflects the current repository state.

Policy, suppressions, exceptions, and safety

These commands help teams turn findings into governed workflows rather than ad hoc ignore lists.

Suppression and exception artifacts are first-class parts of the local governance workflow.

Policy, exception, and safety commands

Command	Purpose	When to use it	What it produces	Important note
archpilot policy init	Create the starting policy configuration for the repository.	Use it when you want architecture outcomes mapped to enforcement rules.	Policy configuration files for the repository.	Policy controls how findings are interpreted. It does not replace validation.
archpilot policy show	Inspect the current policy configuration.	Use it before changing policy or when reviewing enforcement behavior.	A view of the repository's current policy settings.	Use this to confirm the active policy before tuning thresholds or outcomes.
archpilot exception add	Record an explicit exception for a finding or rule outcome.	Use it when a violation is known, intentional, and should remain visible as an exception rather than being ignored.	An exception record in the repository's ArchPilot artifacts.	Prefer exceptions over informal ignores so governance history stays intact.
archpilot suppressions show	Inspect active suppressions in the repository context.	Use it when you need to understand why a finding is softened or hidden locally.	A list of active suppressions.	Suppressions and exceptions serve different purposes. Review both deliberately.
archpilot safety init / archpilot safety check	Set up and review safety evidence around higher-risk change workflows.	Use these commands when your team tracks rollout or rollback evidence alongside architecture risk.	Safety-related artifacts or checks tied to the repository workflow.	Safety workflows complement policy. They do not replace architecture validation.

ADRs and rule packs

ADR and rule-pack workflows make architecture decisions and enforcement inputs easier to reuse.

Local review artifacts can suggest archpilot adr create for architecture changes that should be documented.

archpilot adr create, list, and show: create and review architecture decision records tied to structural change.
archpilot rule-pack list, show, and apply: inspect reusable rule sets and apply them when your ArchPilot rollout standardizes enforcement across repositories.

ADR suggestion surfaced by review artifacts

archpilot adr create "document dependency governance change"

Fixes and remediation

Use fix commands to move from findings to action without leaving the ArchPilot workflow.

Preview-first workflows are the safest default because they let the team inspect what will change before applying it.

Quick fixes create missing files and missing scaffolding. They do not overwrite existing files.

Fix commands

Command	Purpose	When to use it	What it changes	Important note
archpilot fix	Run the default remediation flow for the current result.	Use it after validate when you want ArchPilot to suggest or apply the standard fix path.	Local repository files related to the current findings or setup gaps.	Start with preview when you want to inspect changes first.
archpilot fix --preview	Preview planned changes without applying them.	Use it first when a finding may affect multiple files or repository rules.	A preview of the proposed remediation.	This is the safest default and the recommended first step.
archpilot fix --safe	Restrict fixes to safer scaffold-style changes.	Use it when you want low-risk fixes first.	Missing files, missing scaffolding, or similarly safe repository updates.	Safe fixes keep the flow conservative.
archpilot fix --all	Apply the full set of available fixes.	Use it when you want bulk remediation across the current result set.	The full set of selected local fixes.	Review the result carefully after bulk remediation.
archpilot fix --rule <RULE_ID>	Target one rule's remediation path.	Use it when one rule needs focused attention.	Changes related to a single rule's remediation.	Non-safe single-rule fixes require --force.
archpilot fix --rule <RULE_ID> --force	Apply a non-safe single-rule fix deliberately.	Use it when you have reviewed the rule-specific change and want to proceed.	The targeted non-safe change for the chosen rule.	Force is required so non-safe rule fixes remain intentional.

CI and GitHub workflows

Use this group when you want ArchPilot to run in GitHub Actions and keep the repository's published architecture signals current.

Your GitHub Actions workflow is the source of truth.

GitHub Actions validation and upload commands

archpilot validate --ci
archpilot governance upload --server "https://api.archpilot.org" --token "<organization-api-token>"
archpilot badges publish

CI and GitHub commands

Command	Purpose	When to use it	What it produces	Important note
archpilot ci github	Set up GitHub Actions for ArchPilot workflows.	Use it when you are wiring ArchPilot into a repository's GitHub CI flow.	GitHub workflow scaffolding for validation and related automation.	Match the generated workflow to the repository's validation-first GitHub Actions contract.
archpilot badges publish	Refresh published architecture badge artifacts.	Use it on main after validation when you want the visible architecture badge to stay current.	Updated badge artifacts and related published outputs.	Badge publishing usually runs on main.

GitHub CI Integration Governance Upload Connect a Repository

Next steps

Supported Stacks Extension & CLI FAQ