create-project

create-project generates repositories from template catalogs. It is designed for Nix flake-backed template sources and supports Git + jj colocated workflows. By default, it reads templates from github:monarchic-ai/create-project-templates. Private repositories can use git+ssh://git@github.com/OWNER/REPO.git.

Usage

create-project list --template-source ../create-project-templates
create-project list --json --template-source ../create-project-templates
create-project list --language rust --tag nix --template-source ../create-project-templates
create-project list --category web-app --framework react --template-source ../create-project-templates
create-project search react --template-source ../create-project-templates
create-project search rust --json --language rust --template-source ../create-project-templates
create-project show rust-cli --template-source ../create-project-templates
create-project validate --template-source ../create-project-templates
create-project validate --strict --template-source ../create-project-templates
create-project report --template-source ../create-project-templates
create-project report --json --template-source ../create-project-templates
create-project schema --json
create-project new rust-cli --name my-tool --dry-run --template-source ../create-project-templates
create-project new rust-cli --name my-tool --dry-run --print-plan --json --template-source ../create-project-templates
create-project new rust-cli --name my-tool --template-source ../create-project-templates
create-project new rust-cli --name my-tool --write-metadata --template-source ../create-project-templates
create-project doctor ./my-tool
create-project doctor ./my-tool --json
create-project verify ./my-tool --template rust-cli --template-source ../create-project-templates
create-project verify ./my-tool
create-project verify ./my-tool --template rust-cli --dry-run --json --template-source ../create-project-templates
create-project upgrade --metadata metadata.json --template-source ../create-project-templates
create-project upgrade ./my-tool --template-source ../create-project-templates
create-project upgrade --metadata metadata.json --template-source ../create-project-templates --json
create-project template init my-template --template-source ../create-project-templates --name "My Template" --description "A project template." --category cli --language nix --quality-tier minimal --tag nix --check "nix flake check" --required-tool nix --ci github-actions --package-manager none --runtime nix

Useful options:

• --layout flat|project-dir|worktree-nested
• --input-json values.json
• --var key=value
• --metadata-json
• --write-metadata
• --dry-run
• --print-plan --json
• --license MIT
• --vcs git-jj|git|none
• --no-github-templates

Template placeholders use ASCII markers such as @@cp:name@@.

Template catalogs are validated before listing, inspection, metadata output, or generation. Discovery metadata includes category, language, frameworks, tags, quality_tier, package_manager, runtime, ci, maturity, services, verification metadata, and checks so callers can filter catalogs without reading template files directly. list supports --category, --language, --quality-tier, --offline, --network-required, repeated --package-manager, --runtime, --maturity, repeated --framework, repeated --tag, repeated --check, repeated --system, repeated --tool, repeated --ci, and repeated --service filters. search accepts the same filters and matches the query against ids, names, descriptions, tier, category, language, frameworks, tags, checks, package manager, runtime, CI, maturity, and services.

Generated values are validated before any destination files are created. Language-aware templates reject values that would break package metadata, such as invalid npm package/bin names, Cargo package or crate names, Python project or module names, and Tauri identifier segments. Dry-run JSON includes warnings, required_tools, would_write_count, would_inject_count, and would_skip so callers can inspect the full generation plan without mutating the filesystem. --metadata-json prints stdout-only compatibility metadata covering the CLI version, template id, catalog version, minimum CLI version, template source, resolved source path, source provenance, layout, VCS mode, injected GitHub template setting, license action, generated-file manifest, and rendered values. --write-metadata writes the same compatibility metadata to .create-project.json in the generated project root.

Catalogs can declare required_tools, supported_layouts, generated_value_rules, post_generation_checks, network_required, supported_systems, verification_notes, package_manager, runtime, ci, maturity, and services for each template. The CLI uses these fields when present and falls back to built-in rules for older catalogs. doctor checks generated projects for unresolved placeholders, GitHub issue/PR templates, VCS state, compatibility metadata, and common package metadata names. verify runs a template's post_generation_checks from a generated project directory and can infer template/source from .create-project.json; explicit --template and --template-source values override metadata. template init creates a starter template plus catalog entry for catalog authors. It accepts metadata flags such as --package-manager, --runtime, --ci, --maturity, --service, --network-required, --system, and --verification-notes so new entries can be strict-validation ready without manual catalog editing. upgrade reads saved compatibility metadata or a generated project path and reports read-only advisory upgrade status, template drift, project drift, and likely user edits against the current catalog. Use --output-plan to write the JSON upgrade report to a file. validate --strict adds catalog authoring checks for release-ready template sources, including required discovery metadata, layout support, post-generation checks, and production template files such as CI, release, Dependabot, README, and expected lockfiles. report summarizes catalog health and emits advisory compatibility scores for template selection and maintenance.

Catalogs may also include catalog_version, min_cli_version, and updated_at metadata. These fields are reported in JSON output when present. Remote GitHub Actions verification for published tags requires an authenticated gh session or GH_TOKEN and is intentionally checked separately from local verification.

Quality tiers are descriptive: minimal templates are intentionally small starters, standard templates include normal package/app checks, and production is reserved for templates with stronger operational defaults.

See docs/template-matrix.md for the supported template catalog matrix and docs/template-authoring.md for the template authoring workflow. See docs/template-selection.md for guidance on choosing templates and reading compatibility scores. See CHANGELOG.md for release notes.

Install and Update

Install with Nix:

nix run github:monarchic-ai/create-project/v0.13.0 -- --help
nix profile install github:monarchic-ai/create-project/v0.13.0

Install from source:

git clone https://github.com/monarchic-ai/create-project
cd create-project
nix build .#default

Install from GitHub Releases by downloading the create-project-x86_64-linux asset and verifying it with create-project-x86_64-linux.sha256.

Pin template sources for reproducible generation:

create-project new rust-cli --name my-tool --template-source github:monarchic-ai/create-project-templates/v0.13.0
create-project new rust-cli --name my-tool --template-source git+ssh://git@github.com/OWNER/PRIVATE-TEMPLATES.git
create-project new rust-cli --name my-tool --template-source ../create-project-templates

To update, install a newer CLI, choose a newer template source ref, then run create-project upgrade <project> --template-source <new-source> for projects generated with --write-metadata, or use create-project upgrade --metadata metadata.json --template-source <new-source> against previously saved --metadata-json output.

Verification

nix develop -c cargo fmt --check
nix develop -c cargo clippy --all-targets -- -D warnings
nix develop -c cargo test --workspace --all-targets
nix develop -c ./scripts/e2e.sh ../../create-project-templates/create-project-templates
nix develop -c ./scripts/snapshot.sh ../../create-project-templates/create-project-templates
nix flake check
nix build .#default
nix develop -c ./scripts/verify-release.sh monarchic-ai/create-project v0.13.0