VS Code Actions

A dedicated reference for the ArchPilot VS Code actions, Inspector workflows, files they touch, safety expectations, and common usage patterns.

Why it matters

Use this page when you want to know which ArchPilot action to run in VS Code, what it changes locally, and how it fits into initialization, validation, review, CI, and Cloud upload.

How to use this page

ArchPilot's VS Code extension is organized around command-palette actions, the Architecture Inspector, Next Steps, finding actions, and generated artifact links.

The tables below use the public action label a user sees in VS Code. When the same workflow has a CLI equivalent, the closest CLI command is listed. When it does not, the page says VS Code only or No direct CLI equivalent.

Local actions read or update repository artifacts. Cloud actions upload only after a user connects an organization API token and intentionally uploads a governance snapshot.

Preview and open actions are read-only.
Generation actions create missing files, refresh the architecture model, or regenerate reports.
Cloud and replacement actions require explicit user intent.

Start and setup

Use these actions when a repository is new to ArchPilot or when the architecture model needs to catch up with the current codebase.

Setup actions

Action	Where to find it	CLI equivalent	Use when	Output
Initialize Architecture	Command Palette, Inspector first-run flow	`archpilot init`	A repository does not have ArchPilot architecture metadata yet, or the Inspector prompts you to initialize.	Smart Init proposal, editable setup values, and local architecture files after you apply the wizard.
Run Smart Init	Next Steps, Inspector first-run flow	`archpilot smart-init-proposal`	You want ArchPilot to detect repository structure and propose a starting architecture setup.	Detected topology, stacks, modules, resources, and editable architecture setup values.
Open Architecture Inspector	Command Palette	No direct CLI equivalent	You want a local dashboard for setup, validation, findings, modules, reports, drift, and Cloud status.	Inspector view over the current local artifacts. Opening the Inspector does not change files by itself.
Open Architecture Config	Inspector Actions menu	No direct CLI equivalent	You want to inspect or manually edit the current architecture model.	Opens `.archpilot/architecture.json`.
Preview Setup Changes	Inspector Actions menu	`archpilot init refresh --preview`	You want to see what ArchPilot would update after rescanning the repository.	Preview of detected modules, components, resources, dependency graph updates, and setup artifacts without writing files.
Refresh Architecture Setup	Inspector Overview, Inspector Actions menu	`archpilot init refresh --apply`	You reviewed the setup preview and want ArchPilot to refresh the architecture model from the current codebase.	Refreshed architecture setup plus regenerated architecture map and dependency reports.
Review Architecture Model	Inspector Actions menu, Next Steps	`archpilot architecture-model refresh`	You want to choose governed modules from discovered candidates before updating the architecture model.	Updated architecture model and optional cleanup of generated contracts for removed governed modules.
Generate Missing Config & Contracts	Command Palette, Inspector Overview, Inspector Actions menu, Next Steps	`archpilot bootstrap --with-contracts`	Validation or Next Steps says dependency rules, layer rules, or module contracts are missing.	Missing config files and module contracts, plus refreshed setup next-step guidance.
Bootstrap Architecture Config	Command Palette	`archpilot bootstrap`	You need dependency and layer config but do not want to generate contracts in the same action.	Missing dependency/layer config files and setup next-step guidance.
Bootstrap Missing Config	Inspector Actions menu, Next Steps	`archpilot bootstrap` or `archpilot bootstrap --with-contracts`	The Inspector highlights missing dependency/layer config or missing contracts during setup.	Missing setup files are created without overwriting existing files.
Generate Module Contracts	Command Palette, Inspector Actions menu, Next Steps	`archpilot contracts generate`	The architecture model has modules but contract files are missing or contracts need to match the current model.	Generated missing module contracts and refreshed contract registry entries.
Generate Module	Command Palette	No direct CLI equivalent	You want VS Code to scaffold a new TypeScript modular-monolith module.	New module files, optional API files, optional SQL migration, and optional OpenAPI/docs updates.

Validate and review

Use these actions during everyday development and architecture review.

Validation and review actions

Action	Where to find it	CLI equivalent	Use when	Output
Run Validation	Command Palette, Inspector Overview, Inspector Actions menu, Next Steps	`archpilot validate`	You changed code, architecture metadata, contracts, policy, exceptions, or suppressions.	Findings, health/readiness scores, validation report, architecture summary, review artifacts, governance report, and impact context.
Reload Inspector Data	Inspector Actions menu	No direct CLI equivalent	You want the Inspector to reload current report artifacts without running validation.	Refreshed Inspector UI based on existing local files.
Review Findings	Inspector Findings tab, Next Steps	No direct CLI equivalent	You want to inspect current architecture findings before choosing fixes or governance actions.	Findings view focused on the current local validation artifacts.
Review Drift	Inspector Drift tab, Next Steps	No direct CLI equivalent	You want to inspect baseline comparison results in the Inspector.	Drift view based on the latest baseline and drift report.
Analyze Architecture Impact	Command Palette, Inspector Actions menu	`archpilot impact`	You want to understand the blast radius of a module or file path.	Impact analysis Markdown and JSON reports.
Run Architecture Map	Inspector Actions menu	`archpilot map`	You want to regenerate the architecture map and dependency graph.	Architecture map, dependency graph JSON, module-boundary report, and map JSON.
Generate Diagrams	Inspector Actions menu	`archpilot diagrams generate`	You want visual architecture diagram artifacts from the current model.	Mermaid, SVG, and JSON diagram artifacts.
Show Health History	Inspector Actions menu, Inspector History tab	`archpilot health history`	You want to inspect previous architecture health snapshots and trends.	Health history shown in the Inspector from local history artifacts.
Generate Review Report	Command Palette, Inspector Overview, Inspector Actions menu, Next Steps	`archpilot review generate`	You want a shareable architecture review report from the latest validation summary.	Architecture review report Markdown and JSON.
Open Review Report	Inspector Overview, Inspector Actions menu	No direct CLI equivalent	The review report already exists and you want to read it in VS Code.	Opens `.archpilot/reports/architecture-review-report.md`.
Explain Validation Rule	Command Palette, finding actions	No direct CLI equivalent	You want plain-language guidance for a validation rule or finding.	Rule explanation and fix guidance in VS Code.
Apply Quick Fix	Command Palette, finding actions	`archpilot fix --rule <RULE_ID>`	A finding has a supported safe quick fix.	Creates supported missing files for that finding and refreshes setup guidance.
Apply All Safe Quick Fixes	Command Palette, Inspector Actions menu	`archpilot fix --safe`	You want ArchPilot to apply all supported conservative create-file fixes.	Created safe-fix files, refreshed setup guidance, and refreshed validation in the Inspector.

Governance configuration

Policy, ADR, exception, and safety actions

Action	Where to find it	CLI equivalent	Use when	Output
Initialize Validation Config	Command Palette	No direct CLI equivalent	You want a local file for disabled rules or severity overrides.	Creates or opens `.archpilot/validation-config.jsonc`.
Configure Policy Enforcement	Command Palette, Inspector Actions menu, Next Steps	`archpilot policy init`	You want explicit local policy thresholds for pass, warn, require-ADR, or fail outcomes.	Creates or opens `.archpilot/policy.json`.
Manage Exceptions	Command Palette, Inspector Actions menu, Next Steps	`archpilot exception init`, `archpilot exception list`, `archpilot exception add ...`, `archpilot exception remove ...`	A finding is known, approved, and should remain visible as an exception rather than being ignored.	Creates or opens `.archpilot/exceptions.json`; use the CLI commands to list, add, or remove exception entries.
Create Exceptions	Next Steps	`archpilot exception add ...` after `archpilot exception init`	Next Steps recommends documenting acceptable temporary violations after reviewing current findings.	Approved exception entries recorded in `.archpilot/exceptions.json`.
Configure Safety Controls	Command Palette, Inspector Actions menu	`archpilot safety init`	A validation result recommends rollout or rollback evidence for a risky architecture change.	Creates or opens rollback plan and feature-flag artifacts under `.archpilot/rollout/`.
Open Rollback Plan	Inspector Actions menu	No direct CLI equivalent	You already have a rollback plan and want to edit it.	Opens `.archpilot/rollout/rollback-plan.md`.
Create Rollback Plan	Inspector Actions menu	`archpilot safety init`	The rollback plan is missing and you want to create only that safety artifact from VS Code.	Creates `.archpilot/rollout/rollback-plan.md` if missing and opens it.
Open Feature Flag Config	Inspector Actions menu	No direct CLI equivalent	You already have feature-flag rollout config and want to edit it.	Opens `.archpilot/rollout/feature-flags.json`.
Create Feature Flag Config	Inspector Actions menu	`archpilot safety init`	The feature-flag config is missing and you want to create only that safety artifact from VS Code.	Creates `.archpilot/rollout/feature-flags.json` if missing and opens it.
Generate Required ADR Scaffolds	Command Palette, Inspector Actions menu, Next Steps	No direct CLI equivalent; use `archpilot adr create <title>` for custom ADRs	Validation indicates ADR coverage is needed for current architecture decisions.	Suggested ADR markdown files under `docs/adrs/`, after user selection and confirmation.
Create ADR	Inspector Actions menu	`archpilot adr create`	You want to create a custom architecture decision record from VS Code.	A new ADR markdown file under `docs/adrs/`.
List ADRs	Inspector Actions menu	`archpilot adr list`	You want to see which ADRs ArchPilot can discover.	ADR list in VS Code output.
Show Suppressions	Inspector Actions menu	`archpilot suppressions show`	You want to inspect active local suppressions.	Suppression list in VS Code output.

Cloud

Use these actions when local validation results need to connect to ArchPilot Cloud for shared history and governance visibility.

Cloud actions

Action	Where to find it	CLI equivalent	Use when	Output
Manage Cloud Connection	Command Palette, Inspector Actions menu, Next Steps	`archpilot cloud status`, `archpilot cloud connect`, `archpilot cloud disconnect`	You want to save, validate, remove, or inspect the repository's Cloud upload connection.	Cloud settings in `.archpilot/config.json`, or local-only mode when disconnected.
Upload Governance Snapshot Now	Command Palette, Inspector Actions menu, Next Steps	`archpilot governance upload`	Validation artifacts are current and you want repository findings/history in ArchPilot Cloud.	Governance snapshot uploaded to Cloud. If required local artifacts are missing, VS Code refreshes validation first.
Learn about Cloud	Inspector Actions menu	No direct CLI equivalent	You want product documentation for Cloud before connecting or uploading.	Opens ArchPilot Cloud documentation in your browser.
Open Cloud Dashboard	Inspector Actions menu	No direct CLI equivalent	You want to open the Cloud workspace from VS Code.	Opens the resolved ArchPilot Cloud dashboard URL.
Disconnect	Inspector Actions menu	`archpilot cloud disconnect`	You want to remove the stored Cloud connection from this repository.	Updates `.archpilot/config.json` and leaves local validation available.

CI, badges, and project context

Automation and visibility actions

Action	Where to find it	CLI equivalent	Use when	Output
Setup GitHub CI Validation + Upload	Command Palette, Inspector Actions menu, Next Steps	`archpilot ci github`	You want GitHub Actions to run validation in pull requests and optionally upload from main.	A GitHub Actions workflow file. Existing workflow replacement requires confirmation.
Run CI Validation	Next Steps	`archpilot validate --ci`	You want to run the same validation mode used by CI before relying on the branch result.	CI-mode validation result with policy-aware exit behavior.
Publish Badges	Inspector Actions menu, Next Steps	`archpilot badges publish`	You want the README-facing ArchPilot Score badge to reflect the latest score artifacts.	Refreshed `badges/architecture-score.svg` for the latest architecture score.
Show Project Info	Inspector Actions menu	`archpilot project show`	You want to inspect repository identity metadata before upload or review.	Project identity details in VS Code output.
Create Drift Baseline	Inspector Drift tab, Next Steps	`archpilot baseline create`	The current validated architecture is the accepted reference for future drift checks.	A baseline snapshot for later comparison.
Run Drift Check	Inspector Drift tab, Next Steps	`archpilot baseline check`	A baseline exists and you want to compare the current architecture against it.	Drift comparison report and Inspector drift state.

Recommended workflow for new projects

Open the repository in VS Code and run ArchPilot: Initialize Architecture.
Review the Smart Init detection summary, edit modules/components/resources, and apply initialization.
Run ArchPilot: Run Validation and inspect setup gaps before treating findings as architecture violations.
Generate missing contracts and missing config once the architecture model looks right.
Rerun validation, review the Architecture Summary and Validation Report, then commit the initialized ArchPilot files.
Generate the CI workflow and add Cloud upload only after local validation is stable.

Recommended workflow for existing projects

Run Smart Init and spend extra time on module roots, component boundaries, resources, and discovery defaults.
Run full validation and separate setup gaps from true architecture violations.
Generate missing config/contracts only after the detected model has been reviewed.
Use Preview Setup Changes and Review Architecture Model before applying setup refreshes or governed-module changes.
Use Analyze Impact during refactors, but keep full validation as the release and upload gate.
Connect to Cloud and upload the first governance snapshot after the local reports are current.

Architecture review workflow

Run full validation on the branch under review.
Open the Inspector Findings, Component Summary, and Cross-component Dependencies views.
Generate Review Report or use the refreshed review reports from validation.
Review errors first, then warnings, then guidance findings and setup gaps.
Document accepted intentional drift with ADRs, exceptions, or policy updates instead of ignoring it informally.
Rerun validation, upload the governance snapshot if the result is accepted, and keep the report artifacts with the review record.

Getting Started Smart Init Architecture Inspector Validation & Findings CLI Command Reference Governance Upload

Next steps

Validation & Findings Dependency Rules & Module Contracts