Installation

Install gtmesh

pnpm add -g gtmesh            # global install
# …or from a source checkout:
pnpm install && pnpm build && pnpm link --global

Check it worked with gtmesh --version. Then scaffold a project with gtmesh init (or gtmesh init --from-discovery …) and follow the walkthrough. The full command list is in the Reference.

Provider access (Ahrefs)

gtmesh runs entirely offline except extract --source ahrefs and the research pulls, which need an Ahrefs API token in the environment. Never commit it:

export AHREFS_API_TOKEN=…

Everything else — plan, apply, the lifecycle, types — works with no network and no token.

Upgrade the CLI

Bump the installed gtmesh to the latest release:

pnpm add -g gtmesh@latest                       # global install
# …or, from a source checkout:
git pull && pnpm install && pnpm build

Upgrade a project (gtmesh upgrade)

Separate from upgrading the binary: once a newer gtmesh ships improved engine-owned scaffold files, gtmesh upgrade re-applies them into an existing mesh repo — without clobbering your edits or your project files.

gtmesh upgrade --dry            # preview: added / refreshed / *.new / default-available / skipped
gtmesh upgrade                  # apply it
gtmesh upgrade --with-defaults  # also fetch changed project-file defaults as *.default to hand-merge

• Engine-owned files (the docs, the shared schema base schemas/common.schema.yaml, the capability skills) are refreshed if you haven’t touched them; if you have, the new version lands beside yours as <file>.new — your edit is never overwritten.
• Project-owned files (your config, reference data, per-type schemas, templates, foundation, strategy) are never overwritten. If the engine’s default for one improves, upgrade reports it (default-available); --with-defaults writes that new default as <name>.default.<ext> so you can merge selectively.
• New files are added; files removed from the bundle are reported, not deleted. Idempotent — a second run with no changes does nothing.