foundry_cli 0.0.1-dev.2

CLI for Foundry — mold authoring, inspection, import, and cast workflows.

foundry_cli

Command-line interface for Foundry — mold authoring, inspection, import, and cast workflows.

Preview release. Commands and flags may change before 1.0.0.

What it does

The foundry executable wraps the foundry_core library with commands for the full mold lifecycle:

• foundry mold init — scaffold a new mold package in the current directory
• foundry mold inspect — validate mold layout and report live variable metadata from a describe session
• foundry mold derive — generate a starter mold from a pattern directory (resolves pattern annotations and .foundry/pattern.yaml replacements / lineDeletions)
• foundry mold sync — refresh an existing mold template/ from a pattern (same annotation rules as derive)
• foundry mold import — copy a mold from git or a local path
• foundry cast — run a mold cast session (live variables.dart, in-process hooks, template render) to --output
• foundry recast — replay the last successful cast from the encodable projection in .foundry/last_cast.json
• foundry finish — run only the finish hook against the last cast output

Molds are Dart packages with a root pubspec.yaml, variables.dart, a template/ tree, and optional lifecycle hooks. See the hook authoring guide, pattern annotations, and the mold pubspec schema.

Installation

Install the CLI globally with dart install:

dart install foundry_cli

The global binary is foundry (executables: foundry:), even though the pub.dev package is foundry_cli.

foundry --version

Requires Dart SDK >=3.5.0 <4.0.0.

Quick start

Scaffold a mold

foundry mold init --name=hello_mold
cd hello_mold

Derive a mold from a pattern

foundry mold derive --pattern=../demo_pattern --output=./hello_mold

Sync a mold template from a pattern

cd hello_mold
foundry mold sync --pattern=../demo_pattern

Inspect

foundry mold inspect

Cast

foundry cast . --output=../hello_out

Cast runs inside a mold cast session: a short-lived helper that imports the mold's live variables.dart and runs prepare → gather → shape → render → finish in one process with in-process hooks (no JSON round-trip between phases). See the hook authoring guide.

By default Foundry gathers variables through an interactive TUI inside that session, renders template/ into --output, and on success writes .foundry/last_cast.json in the process working directory. That file stores an encodable projection of resolved values only (JSON primitives, lists, and string-keyed maps) — non-encodable prepare seeds from the cast are not persisted.

Pass --vars and/or --vars-file to supply values in batch and skip the TUI:

foundry cast . --output=../hello_out --vars=project_name=Hello
foundry cast . --output=../hello_out --vars-file=./vars.json

Object fields accept dotted --vars paths (for example publish.host=api.example.com,publish.port=443) or a nested JSON object in --vars-file. Prefer --vars-file for deep nests. A whole-object --vars flag assignment such as publish={…} cannot be combined with publish.* dotted children; a --vars-file object value at that path can deep-merge with dotted --vars overrides.

Use --force to cast into a non-empty output directory. Use --skip-hooks=<phase> (repeatable: prepare, shape, finish) to skip individual hook phases.

Recast and finish

foundry recast
foundry finish

recast and finish also launch a mold cast session. recast re-runs the full pipeline from the encodable vars in .foundry/last_cast.json (JSON-safe values only). finish runs only the finish hook against the stored output without re-rendering templates.

See the example/ directory for a bundled mold you can inspect and cast with dart run.

CLI reference

Invocation

foundry [--version] <command> [arguments] [options]

Global flags

Flag	Description
--version	Print the CLI version and exit

Exit codes

Code	Meaning
0	Success
1	User-facing error (invalid input, mold load failure, hook abort, etc.)
2	Unexpected internal error

Commands

Command	Description
foundry mold init	Scaffold a new mold in the current directory
foundry mold derive	Derive a starter mold from a pattern directory
foundry mold sync	Sync an existing mold template from a pattern directory
foundry mold import git	Import a mold from a git repository
foundry mold import local	Import a mold from a local path
foundry mold inspect	Validate and analyze a mold
foundry cast	Cast a mold to an artifact at --output
foundry recast	Re-run the last cast
foundry finish	Run the finish hook for the last cast

foundry mold init

foundry mold init [--name=<name>]

Option	Description
--name	Mold package name (defaults to the current directory basename)

foundry mold derive

foundry mold derive --pattern=<path> [--output=<dir>] [--force]

Option	Description
--pattern	Required. Pattern directory to derive from
--output	Destination for the derived mold (defaults to the current directory; requires --force when omitted, since cwd already exists)
--force	Overwrite the destination directory if it already exists

Resolves pattern annotations and .foundry/pattern.yaml replacements / lineDeletions into the mold template/ (see pattern annotations).

foundry mold sync

foundry mold sync --pattern=<path> [--force]

Option	Description
--pattern	Required. Pattern directory to sync from
--force	Replace template/ wholesale (remove orphans); author edits outside template/ are still preserved

Syncs the mold in the current directory. Refreshes template/ from the pattern (same annotation / replacements / lineDeletions rules as derive) while preserving root pubspec.yaml, variables.dart, hooks/, and other non-template/ files.

foundry mold import git

foundry mold import git --git-url=<url> [--path=<relative/path>] [--force]

Option	Description
--git-url	Required. Git repository URL to shallow-clone
--path	Relative path to the mold within the repository
--force	Overwrite the destination directory if it already exists

foundry mold import local

foundry mold import local --path=<dir> [--force]

Option	Description
--path	Required. Local directory containing the mold
--force	Overwrite the destination directory if it already exists

foundry mold inspect

foundry mold inspect [<path>]

Argument	Description
<path>	Mold directory (defaults to the current directory)

foundry cast

foundry cast <mold-path> --output=<dir> [--force] [--skip-hooks=<phase>]
  [--vars=<k=v,…>] [--vars-file=<path>]

Runs a mold cast session (live variables.dart + in-process hooks). On success, writes .foundry/last_cast.json with an encodable vars projection only.

Argument / option	Description
<mold-path>	Required. Path to the mold directory
--output	Required. Destination directory for rendered artifacts
--force	Allow casting into a non-empty output directory
--skip-hooks	Skip a lifecycle phase (prepare, shape, or finish); repeatable
--vars	Comma-separated key=value pairs (skips the TUI)
--vars-file	Path to a JSON object of variable values (skips the TUI)

foundry recast

foundry recast [--force] [--skip-hooks=<phase>]

Replays the last successful cast via a mold cast session seeded from .foundry/last_cast.json. Stored vars are an encodable projection only.

Option	Description
--force	Allow casting into a non-empty output directory
--skip-hooks	Skip a lifecycle phase (prepare, shape, or finish); repeatable

foundry finish

foundry finish [--skip-hooks=finish]

Runs a finish-only mold cast session for the last cast (requires hooks/finish.dart unless finish is skipped and not required by policy). Seeds context from the encodable vars projection in .foundry/last_cast.json without re-rendering templates.

Option	Description
--skip-hooks	Skip the finish hook when policy allows (finish only)

Resources

• Repository README — product overview and full CLI guide
• Hook authoring guide
• Pattern annotations and .foundry/pattern.yaml
• Repository
• Issue tracker
• Changelog
• foundry_core library — embed Foundry in Dart tools

License

MIT — see LICENSE.