unreleased core preview Public

CLI reference preview

Preview the unreleased CLI reference from the current Core development commit.

Owner: Foundry Core
Source: core/docs/CLI-REFERENCE.md
Ref: 782f49b97d862e640e87c870178e600f9ce5cf83
Policy: release-bound

Component pins for v0.2.6

Component	Role	Version
core	runtime	`v0.1.24`
theme-shield	theme	`v0.1.15`
starter	reference	`v0.1.3`
docs	reference	`v0.1.4`
distribution	tooling	`v0.3.4`
restricted-component-1	consumer-reference	`v0.1.22`
restricted-component-2	consumer-reference	`v1.1.21`

The Go foundry CLI is the canonical public tool for humans, CI, AI agents, and Foundry Control integrations. It reads normal repository files, emits human summaries by default, and emits deterministic structured reports with --json.

Invocation

From a Core checkout:

go run ./cmd/foundry --help

As an installed binary:

go install ./cmd/foundry
foundry --help

The commands are identical in both forms. Examples below use foundry.

Common Conventions

Convention	Meaning
`--root <path>`	Foundry Core root; defaults to the current directory for Core-oriented commands.
`--site <path>`	Consuming Hugo site root. Prefer an absolute path in automation.
`--json`	Emit the machine report instead of a human summary.
`--dry-run`	Compute and report without writing. Required on dry-run-only task commands.
`--apply`	Explicitly authorize an implemented add-only task write.
`--force`	Permit a generator to replace an existing destination only where that command supports it. Review carefully.
Exit 0	Command or validation succeeded.
Exit 1	The command ran but its result was not OK.
Exit 2	Invalid usage, missing arguments, or a disallowed mode.

Human-friendly aliases exist for some commands, but automation should use the canonical names documented here. Treat JSON field names and manifest contracts as APIs; do not parse human summaries.

Command Map

Command	Mode	Purpose
`foundry build`	Read-only	Doctor-backed build/readiness report.
`foundry release-check`	Read-only	Stricter release readiness; site mode enables drift audits.
`foundry doctor`	Read-only	Aggregate diagnostics for Core and/or a site.
`foundry inspect`	Read-only	Discover Core contracts or inspect a site/page.
`foundry authoring-contract`	Read-only	Derive the portable structured/visual editor contract for a site.
`foundry pages`	Read-only	Inventory pages and route-floor facts in a site.
`foundry new-page`	Dry run or write	Resolve a blueprint/brief and optionally create one page.
`foundry scaffold`	Dry run or write	Create Creative or Local Service route-floor files.
`foundry route-floor`	Read-only	Report Local Service route-floor completeness.
`foundry quality-floor`	Read-only	Report Local Service quality-floor completeness.
`foundry task`	Mixed, bounded	Run portable report, dry-run, and add-only task contracts.
`foundry upgrade`	Read-only/dry run	Plan upgrades and inspect ownership, portability, and drift.
`foundry validate`	Read-only	Run focused Core and downstream contract validators.

Build, Release Check, And Doctor

foundry build [--root <core>] [--site <site>] [doctor flags] [--json]
foundry release-check [--root <core>] [--site <site>] [doctor flags] [--json]
foundry doctor [--root <core>] [--site <site>] [doctor flags] [--json]

Doctor flags:

Flag	Effect
`--include-drift-audits`	Add site shadow and ownership drift checks; requires `--site`.
`--skip-core`	Skip Core validation; requires `--site`.
`--skip-hugo`	Skip the consuming-site Hugo smoke build.
`--strict-warnings`	Treat Hugo warnings as failures.
`--browser-smoke`	Run supported browser parity checks.
`--require-browser`	Fail instead of skip when the browser lane is unavailable.

build and doctor share the aggregate engine and report shape. In site mode, release-check sets strict warnings and includes drift audits by default.

foundry doctor --json
foundry build --site /path/to/site --json
foundry release-check --site /path/to/site --json
foundry doctor --browser-smoke --require-browser --json

Inspect

Inspect Core contracts:

foundry inspect [target] [--root <core>] [--json]

Targets:

all
blocks
families
pages
handlers
compositions
content-kits
packs
section-families
discovery-gaps
motion
theme-tokens
blueprints
scaffolds
runtime
crawler-policy
manifests

With no target, Core inspection defaults to the complete inventory.

foundry inspect --json
foundry inspect blocks --json
foundry inspect section-families --json
foundry inspect discovery-gaps --json
foundry inspect theme-tokens --json
foundry inspect crawler-policy --json

Inspect a site or one page:

foundry inspect [site|route|content-path] --site <site> [--root <core>] [--json]

foundry inspect --site /path/to/site --json
foundry inspect site --site /path/to/site --json
foundry inspect /services/example/ --site /path/to/site --json
foundry inspect content/services/example/index.md --site /path/to/site --json

The page report includes bounded repo-visible context, source mapping, blocks, page/blueprint relationships, authored or inferred discovery kind, authored seo.image and service type, service-schema eligibility, canonical review date, and other contract facts suitable for an editor or AI agent.

Authoring Contract

foundry authoring-contract --site <site> [--root <core>]
  [--core-version <version>] [--site-key <key>] [--commit-sha <sha>] [--json]

Emits foundry.authoring-contract.v1 directly for Foundry Control or another portable editor. The report derives its block inventory from the Core block manifest, typed editor fields from block schemas, template structure from blueprints, and site identity from an explicit value or optional foundry-control.yaml plus Git. Without a managed site key, Core derives a portable key from the site directory name. It does not write to Core or the site.

Typed fields include a source-relative path and a preview object with a section scope and deterministic CSS selector. Consumers must query that selector inside the already-selected section wrapper. See Portable Authoring Contract for the mapping algorithm and compatibility rules.

foundry authoring-contract --site /path/to/site --json \
  > authoring-contract.json

--core-version, --site-key, and --commit-sha are snapshot overrides for packaged or exported repositories where Git/config identity cannot be resolved. The schema is schemas/foundry/authoring-contract.schema.json.

Pages

foundry pages [site-path] [--root <core>] [--site <site>] [--json]

Inventories site content and reports page/route-floor facts.

foundry pages --site /path/to/site --json

New Page

foundry new-page [--blueprint <id>] [--brief <file>] [--content-kit <id>]
  [--prompt] [--dry-run|--write] [--include-content] [--force]
  [--root <core>] [--site <site>] [--json] [--field value ...]

Key behavior:

Briefs may be Markdown, YAML, or JSON.
Explicit --field value arguments override brief values; dashes normalize to underscores (--primary-cta-url becomes primary_cta_url).
--prompt asks only for unresolved required inputs and defaults to dry-run.
--include-content includes rendered page content in the report.
Non-prompt mode writes unless --dry-run is supplied.
Existing files are refused unless --force is supplied.
Use foundry inspect blueprints --json to discover IDs and input contracts.

foundry new-page --blueprint service --prompt --dry-run --json
foundry new-page --brief /path/to/brief.yaml --site /path/to/site \
  --dry-run --include-content --json
foundry new-page --blueprint contact --site /path/to/site --prompt --write

Scaffold

foundry scaffold creative-route-floor|local-service-route-floor
  [--dry-run] [--include-content] [--force]
  [--root <core>] [--site <site>] [--json] [--field value ...]

Scaffold writes by default. Use --dry-run --json first.

foundry scaffold creative-route-floor --site /path/to/site \
  --artist-name "Creative Studio" --artist-role "Photographer" \
  --primary-email hello@example.com --dry-run --json

foundry scaffold local-service-route-floor --site /path/to/site \
  --business-name "Local Business" --service-name "Primary Service" \
  --city-name "Sample City" --region-name "Region" \
  --primary-phone "(555) 555-0100" --dry-run --json

See Creative Lane and Local Service Scaffolding.

Route Floor And Quality Floor

foundry route-floor local-service-route-floor
  [--root <core>] [--site <site>] [--json] [--field value ...]

foundry quality-floor local-service-route-floor
  [--root <core>] [--site <site>] [--json] [--field value ...]

Both commands are read-only. Route floor checks required/optional route coverage; quality floor checks local-service quality evidence and reports gaps. Established sites can map portable page roles to local routes, or document a role as not required, through data/foundry/route-floor.json. Both reports consume the same profile and expose its path in JSON output.

foundry route-floor local-service-route-floor --site /path/to/site --json
foundry quality-floor local-service-route-floor --site /path/to/site \
  --business-name "Local Business" --service-name "Primary Service" \
  --city-name "Sample City" --region-name "Region" --json

Task Commands

The backing contract is data/foundry/task-contract-manifest.json. Core tasks operate only on repo-visible inputs. Commands reject overwrite, delete, sync, provider, and managed-workflow modes.

Read-Only Reports

foundry task intake [site-path] [--root <core>] [--site <site>] [--json]
foundry task migration-audit [site-path] [--root <core>] [--site <site>] [--json]
foundry task file-presence [site-path] [--path <relative>] [--expect <relative> ...]
  [--root <core>] [--site <site>] [--json]
foundry task source-mapping [site-path] [--path <relative>]
  [--root <core>] [--site <site>] [--json]
foundry task site-update-report [site-path] --source <file> --blueprint <id>
  [--content-kit <id>] [--root <core>] [--site <site>] [--json]
foundry task validate-improve-page-report --report <file>
  [--root <core>] [--site <site>] [--json]

Task	Use it for
`intake`	Establish site/repository facts before migration or import work.
`migration-audit`	Report migration, ownership, route, and portability concerns.
`file-presence`	Inventory a path and test one or more expected relative paths.
`source-mapping`	Map content/routes to visible source files and ownership.
`site-update-report`	Describe how source records map to governed destinations.
`validate-improve-page-report`	Validate a saved improve-page report against the public contract.

Dry-Run-Only Reports

foundry task patch-preview [site-path] --dry-run
  [--source-mapping-report <file>] [--path <relative>]
  [--root <core>] [--site <site>] [--json]
foundry task improve-page [site-path] --dry-run [--path <relative>]
  [--root <core>] [--site <site>] [--json]
foundry task import-plan [site-path] --dry-run --source <file> --blueprint <id>
  [--content-kit <id>] [--root <core>] [--site <site>] [--json]
foundry task import-batch-plan [site-path] --dry-run --dry-run-report <file>
  --source <file> --blueprint <id>
  (--record-id <id>|--record-index <n>)...
  [--content-kit <id>] [--root <core>] [--site <site>] [--json]
foundry task import-batch-retry-plan [site-path] --dry-run
  --batch-apply-report <file> [--root <core>] [--site <site>] [--json]

improve-page is the canonical owner-facing page-improvement report. It may expose facts, gaps, preview copy, guardrails, and portable decision descriptors, but it does not persist approvals, generate final copy from private context, or publish. Those are Foundry Control responsibilities.

Explicit Add-Only Apply

foundry task import-apply [site-path] --apply --dry-run-report <file>
  --source <file> --blueprint <id>
  (--record-id <id>|--record-index <n>) [--content-kit <id>]
  [--root <core>] [--site <site>] [--json]

foundry task import-batch-apply [site-path] --apply --batch-plan-report <file>
  --source <file> --blueprint <id> [--content-kit <id>]
  [--root <core>] [--site <site>] [--json]

Apply is create-only, requires the reviewed report chain, and is designed to be idempotent. Existing destinations are not overwritten. Partial batch failures produce a report that can feed import-batch-retry-plan.

Example safe chain:

foundry task import-plan --dry-run --site /path/to/site \
  --source data/import/services.csv --blueprint service \
  --content-kit service-detail-starter --json > reports/import-plan.json

foundry task import-apply --apply --site /path/to/site \
  --dry-run-report reports/import-plan.json \
  --source data/import/services.csv --blueprint service \
  --content-kit service-detail-starter --record-id Botox --json

Upgrade And Drift Reports

foundry upgrade [--dry-run] [--to <bundle-or-version>]
  [--root <core>] [--site <site>] [--json]
foundry upgrade owner-inventory [--root <core>] [--site <site>] [--json]
foundry upgrade portability [--root <core>] [--site <site>] [--json]
foundry upgrade starter-drift [--root <core>] [--json]
foundry upgrade framework-drift [--root <core>] [--json]

The base upgrade command is planning-only; apply/write mode is not implemented. The reports cover:

target bundle/version planning
site-owned versus framework-owned files
portability warnings
starter/template drift
framework drift scorecards

foundry upgrade --dry-run --to v0.2.0 --site /path/to/site --json
foundry upgrade owner-inventory --site /path/to/site --json
foundry upgrade portability --site /path/to/site --json
foundry upgrade starter-drift --json
foundry upgrade framework-drift --json

Validate Commands

foundry validate <target> [target flags] [--json]

Target	Scope
`block-contracts`	Registry, options, schemas, manifests, docs, and block partial consistency.
`block-governance`	Family ownership, proof coverage, and governance state.
`content-kits`	Kit templates, tokens, manifests, and render smoke.
`creative-lane`	Creative v1 route, content, and contract expectations.
`compatibility-fixtures`	Render the fixture set and assert downstream compatibility.
`site-blocks`	Validate block usage in one consuming site.
`site-shadows`	Detect copied Core framework surfaces in a consumer.
`shell-overrides`	Detect unallowlisted shell shadows in a consumer.
`runtime`	Protected runtime helper, partial, block, and compatibility registry.
`crawler-policy`	Reviewed crawler purposes, robots applicability, named profiles, source files, and renderer contract.
`discoverability`	Rendered canonicals/index controls, schema/content agreement, internal links, freshness evidence, and agent-friendly controls.
`motion`	Motion manifest, normalized fields, profiles, patterns, and runtime hooks.
`quality`	Source/rendered a11y, SEO, performance, and template-leak gates.
`feature-flags`	Feature flag docs and template usage consistency.
`shell`	Shell schemas, fields, helpers, and compatibility contract.
`section-families`	Discovery family relationships and references.
`scaffolds`	Page, blueprint, pack, starter, route-floor, and content-model contracts.
`tasks`	Public task manifest, safety modes, report contracts, and docs.

Target-specific forms:

foundry validate block-contracts [--root <core>] [--json]
foundry validate block-governance [--root <core>] [--json]
foundry validate content-kits [--root <core>] [--json]
foundry validate creative-lane [--root <core>] [--json]
foundry validate runtime [--root <core>] [--json]
foundry validate crawler-policy [--root <core>] [--json]
foundry validate discoverability --rendered-root <public>
  [--max-review-age-days <days>] [--strict] [--json]
foundry validate motion [--root <core>] [--json]
foundry validate feature-flags [--root <core>] [--json]
foundry validate shell [--root <core>] [--json]
foundry validate section-families [--root <core>] [--json]
foundry validate scaffolds [--root <core>] [--json]
foundry validate tasks [--root <core>] [--json]

foundry validate compatibility-fixtures [fixture ...] [--root <core>]
  [--keep-temp] [--verbose] [--browser-smoke] [--require-browser] [--json]

foundry validate quality [--root <core>] [--rendered-root <public>]
  [--skip-source] [--json]

foundry validate site-blocks [site-path] [--root <core>] [--site <site>] [--json]
foundry validate site-shadows [site-path] [--root <core>] [--site <site>]
  [--allowlist <file>] [--verbose] [--json]
foundry validate shell-overrides [site-path] [--site <site>]
  [--allowlist <file>] [--verbose] [--json]

--keep-temp retains materialized compatibility fixtures for debugging. --require-browser turns a browser skip into failure. --skip-source on the quality validator is useful when checking only an already-rendered tree. --strict on the discoverability validator promotes review warnings to errors; its default review-age window is 730 days.

Recommended Command Sequences

Core Change

go test ./...
foundry doctor --json
foundry release-check --json

Add focused validators for every contract touched. The full release sequence is in Release Checklist.

Site Change

foundry inspect --site /path/to/site --json
foundry doctor --site /path/to/site --json
foundry release-check --site /path/to/site --json

AI Or Automation

foundry inspect all --json
foundry inspect --site /path/to/site --json
foundry task source-mapping --site /path/to/site --path content/example.md --json

Save reports when one command is an explicit input to another. Preserve the original report rather than reconstructing fields from memory.

Node Maintenance And Compatibility Tools

The Go CLI is canonical. These Node tools remain for artifact generation, legacy compatibility, and parity checks; Node.js 20 or newer is expected.

Artifact And Content Tools

Command	Purpose
`node scripts/build-block-manifest.js`	Regenerate `block-manifest.json` from registry/options/schemas/families.
`node scripts/generate-tailwind-safelist.js`	Regenerate the downstream Tailwind safelist.
`node scripts/create-content-draft.js --kit <id> --brief <json> [--out <file>] [--stdout] [--force]`	Low-level compatibility renderer for a content kit. Prefer `foundry new-page`.
`node scripts/save-content-kit-from-page.js --source <page.md> --config <json> [--manifest-out <file>] [--example-out <file>] [--force]`	Derive/update a reusable kit from a governed source page.

Legacy/Reference Validators

Command	Go-first equivalent or purpose
`node scripts/foundry-doctor.js [doctor flags]`	Aggregate legacy backstop for `foundry doctor`.
`node scripts/validate-block-contract.js`	`foundry validate block-contracts`
`node scripts/validate-block-governance.js`	`foundry validate block-governance`
`node scripts/validate-blocks.js [site-root]`	`foundry validate site-blocks --site <site>`
`node scripts/validate-compatibility-fixtures.js [fixture ...] [flags]`	`foundry validate compatibility-fixtures`
`node scripts/validate-content-kits.js`	`foundry validate content-kits`
`node scripts/validate-creative-lane.js`	`foundry validate creative-lane`
`node scripts/validate-feature-flags.js`	`foundry validate feature-flags`
`node scripts/validate-improve-page-report-contract.js`	Improve-page report parity/fixture backstop.
`node scripts/validate-motion-manifest.js`	`foundry validate motion`
`node scripts/validate-quality-gates.js`	`foundry validate quality` source reference.
`node scripts/validate-runtime-contracts.js`	`foundry validate runtime`
`node scripts/validate-section-family-manifest.js`	`foundry validate section-families`
`node scripts/validate-shell-contract.js [--verbose]`	`foundry validate shell`
`node scripts/validate-shell-overrides.js <site> [--allowlist <file>] [--verbose]`	`foundry validate shell-overrides`
`node scripts/validate-site-shadows.js <site> [--allowlist <file>] [--verbose]`	`foundry validate site-shadows`

Do not add a new public product command as Node-only behavior. Keep Node parity when an existing reference script protects a contract, and make the Go CLI the public surface.

Control Boundary

CLI reports can be consumed by Foundry Control, but the CLI does not own accounts, roles, approvals, comments, private credentials, final copy generated from private context, managed previews, publishing, communications, dashboards, care, or automations.

Foundry Control opportunity: Use Foundry Control when a portable CLI report needs to become a persisted, permissioned review, editing, publishing, analytics, forms, or operational workflow.