Quickstart

Install

uv tool install scaffold-guard
scaffold-guard version

Create A Project

Start the guided setup and answer the prompts. This example assumes you enter my_project as the project name and keep the default minimal profile.

scaffold-guard init
cd my_project
scaffold-guard check
scaffold-guard validate --quick

Use the command reference for the full CLI surface, including inspect-diff, validate, upgrade, publish, compile-rules, doctor, and version.

Profile choices:

Profile	Meaning
minimal	Guardrails only; no Python or TypeScript source scaffold
python	Python package scaffold with src/, tests, docs, and uv
typescript	TypeScript package scaffold with npm and configurable TypeScript tooling
monorepo	Python + TypeScript workspaces using an application, library, or custom layout

Generated projects include CI and local development defaults, but the user-facing CLI remains the installed scaffold-guard command.

For non-interactive use with defaults, pass the options as flags:

scaffold-guard init my_project --agent all

If you already created and entered a project folder, run the same guided setup command from that folder. Press Enter at the project-name prompt to use the current directory. Existing unrelated files are preserved; if a generated destination such as README.md already exists, ScaffoldGuard stops unless you rerun with --force.

scaffold-guard init

Use one adapter when you only need one agent surface:

scaffold-guard init codex_demo --agent codex
scaffold-guard init claude_demo --agent claude
scaffold-guard init cursor_demo --agent cursor

Use GitLab CI instead of GitHub Actions:

scaffold-guard init gitlab_demo --ci gitlab

Use the python profile when you want a full Python package layout. Guided setup asks for Ruff linting strictness, Python type-checking strictness, and the Python type checker. Strict Ruff plus mypy and Pyright are enabled by default, but Ruff and type checking can each be set to standard or off.

scaffold-guard init python_demo --guided
cd python_demo
uv sync --all-groups
scaffold-guard validate --quick

Use the typescript profile when you want a TypeScript package with npm scripts. Strict compiler mode, Biome, and Vitest are enabled by default and can be changed during guided setup or with flags:

scaffold-guard init ts_demo --profile typescript
cd ts_demo
npm install
scaffold-guard validate --quick

Use the monorepo profile when Python and TypeScript should live in one repository. Guided setup asks for the workspace layout and both Python and TypeScript tool choices. The default application layout generates apps/api and apps/web:

scaffold-guard init app_demo --profile monorepo
cd app_demo
uv sync --all-groups
npm install
scaffold-guard validate --quick

The library layout generates packages/core and packages/client. Select it non-interactively with:

scaffold-guard init sdk_demo --profile monorepo --monorepo-layout library

The custom layout requires both workspace flags. Each value must be a safe relative directory, and the two paths must not overlap:

scaffold-guard init custom_demo --profile monorepo --monorepo-layout custom \
  --python-workspace services/api --typescript-workspace clients/web

Preview Or Refresh Files

Preview a new project without writing files:

scaffold-guard init demo --dry-run

Refresh managed instruction files from inside a generated project:

scaffold-guard compile-rules --dry-run
scaffold-guard compile-rules --force

compile-rules default regeneration only proceeds when each existing managed instruction file exactly matches the content ScaffoldGuard would render. A generated marker alone is not proof that the file can be replaced. Use --force only after review when you intentionally want to replace managed generated files.

Preview a generated-project upgrade before writing files:

scaffold-guard upgrade

Apply only after reviewing the preview and explicitly choosing to write:

scaffold-guard upgrade --apply
scaffold-guard check
scaffold-guard validate

upgrade is read-only by default. It reconciles only hash-clean managed files, limits structured migrations to reserved metadata in scaffold-guard.toml and the scaffold-guard development requirement or tool-carrier in pyproject.toml, and never touches seed files. A manifest-less 0.1.x project whose managed files exactly match a packaged baseline is adopted without flags. Use --accept-legacy PATH only for a reviewed, recognized, marker-bearing managed file that differs; unmarked CI or config files require manual resolution. Orphans are reported and never deleted or pruned.