`gtmesh upgrade`

Re-applies the engine-owned scaffold files into your project, refreshing them to the current version without overwriting anything you’ve edited.


gtmesh upgrade [--dry] [--with-defaults]

What it does

A scaffolded mesh repo contains two kinds of files: engine-owned files (the plumbing init laid down and the engine maintains) and project-owned files (your config, reference data, per-type schemas, and templates). After you bump the gtmesh CLI itself, gtmesh upgrade brings the engine-owned files in your project up to the new version.

It’s careful about your work:

Engine-owned files are refreshed only if you haven’t touched them. If you have edited one, the new version lands beside it as <file>.new for you to merge by hand — your edit is never clobbered.
Project-owned files (config, reference data, your per-type schemas, templates) are never overwritten.
It’s idempotent — running it again when you’re already current is a no-op.

Use --dry to see the plan first. Use --with-defaults to also drop the new project-file defaults next to yours (as *.default) so you can hand-merge any changed defaults.

upgrade refreshes the files inside an existing project. Bumping the gtmesh CLI binary itself is a separate step — see the full workflow in Installation.

Arguments & flags

Option	Description	Default
`--dry`	Report the plan without writing anything	off
`--with-defaults`	Also write changed project-file defaults as `*.default` for hand-merging	off

The global options (--project, --json, --quiet) also apply.

Reads & writes

Consumes: the bundled scaffold assets for the installed CLI version, compared against your project’s files.
Produces: refreshed engine-owned files; <file>.new beside any engine file you’ve edited; and, with --with-defaults, *.default copies of changed project-file defaults. With --dry, produces only a plan — read-only.
Commits: review the refreshed files and merge any .new / .default sidecars, then commit.

Examples


gtmesh upgrade --dry              # preview what would change
gtmesh upgrade                    # refresh engine-owned files in place
gtmesh upgrade --with-defaults    # also surface changed project-file defaults to hand-merge

Installation — the full upgrade workflow, including bumping the CLI itself.
Reference — the version-exact flag list.

gtmesh upgrade