Reference
Every gtmesh command, grouped by what you’re doing. Each entry gives the one-line
description, any positional arguments, and the flags — taken directly from the program.
For the definitive, version-exact list, run gtmesh --help or gtmesh <command> --help.
Not installed yet? See Installation.
New here? The walkthrough tells the end-to-end story, and lifecycle / tuning cover the day-to-day loops. New terms (registry, identity, bundle, mesh) are in the glossary.
Global options
These apply to every command (set them before the verb, e.g. gtmesh --project ./my-mesh status):
| Option | Description |
|---|---|
--project <dir> | Project directory (the scaffolded mesh repo). Default: . |
--json | Machine-readable output |
--quiet | Suppress non-essential output |
There is also --version (prints the gtmesh version) and --help.
Scaffold & discovery
These get a project off the ground. See the walkthrough.
init
Scaffold a mesh repo from bundled assets (tailor it with --from-discovery).
| Option | Description |
|---|---|
--force | Overwrite existing files instead of skipping them |
--from-discovery <file> | Tailor the scaffold from a gtmesh-discovery.yaml (the discovery skill’s output) |
discover
Install the project-discovery skill into an empty dir and print the prompt (pre-init bootstrap).
| Argument | Description |
|---|---|
[description...] | Optional business description woven into the printed prompt |
gtmesh discover is LLM-free: it installs the skill and hands you a prompt to paste into
Claude Code. The discovery skill then interviews you and writes gtmesh-discovery.yaml,
which feeds init --from-discovery.
harvest
Print how to run the harvest skill (entity-class term harvesting) for a configured class.
| Argument | Description |
|---|---|
[class] | The discovery class to harvest (omit to list configured classes) |
Like discover, this is a bridge to a skill — it validates the class and prints the
prompt; the harvesting itself happens in Claude Code and writes a curated seeds/<class>.csv.
Data — pull keyword data into the bag
extract
Run an adapter; append a timestamped export to data/raw/.
| Option | Description |
|---|---|
--source <source> | Adapter to run (ahrefs | csv | seeds). Default: ahrefs |
--cluster <id> | Cluster to pull (default: all configured seed clusters) |
--pull <kind> | Single pull (matching-terms | questions); default: configured pulls |
--input <file> | Source CSV (for --source csv) |
--class <id> | Discovery class to refresh (for --source seeds; default: all configured) |
--dry-run | Report the planned pulls without spending API credits |
--source ahrefs needs AHREFS_API_TOKEN set. --source csv imports a CSV with no API
budget. --source seeds refreshes the metrics for a curated discovery term list (terms
stay in seeds/<class>.csv; metrics live in data/raw/).
research
External (Ahrefs) discovery pulls used by the discovery skill: serp | keywords |
top-pages. These are subcommands (e.g. gtmesh research serp "<keyword>"); they route
networked provider access through the CLI rather than the skill.
research serp <keyword>
Pull a keyword’s SERP from Ahrefs (serp-overview); append a timestamped export to
data/raw/serp/.
| Argument / Option | Description |
|---|---|
<keyword> | The keyword to pull the SERP for (a discovery cluster head) |
--country <cc> | ISO alpha-2 country (default: taxonomy.markets[0]); required in a pre-init directory |
--top <n> | Limit to the top N organic positions |
--dry-run | Report the planned pull without spending API credits |
research keywords
Pull the keyword universe (Ahrefs matching-terms) for seed terms during discovery cycle 0;
append to data/raw/keywords/.
| Option | Description |
|---|---|
--keyword <kw> | (required) Comma-separated seed terms (e.g. "pump,water pump") |
--cluster <id> | (required) The bag-path label for the raw export |
--pull <kind> | Single pull (matching-terms | questions); default: matching-terms |
--country <cc> | ISO alpha-2 country (default: config country, else "us") |
--dry-run | Report the planned pull without spending API credits |
research top-pages <domain>
Pull a competitor domain’s top organic pages from Ahrefs; append a timestamped export to
data/raw/top-pages/.
| Argument / Option | Description |
|---|---|
<domain> | The competitor domain to pull top pages for (e.g. example.com) |
--country <cc> | ISO alpha-2 country (default: taxonomy.markets[0]); required in a pre-init directory |
--date <yyyy-mm-dd> | Metrics reporting date (default: today, UTC) |
--mode <scope> | Search scope: exact | prefix | domain | subdomains (default: subdomains) |
--limit <n> | Max pages to pull |
--dry-run | Report the planned pull without spending API credits |
Plan & apply — reconcile desired state
The core loop. plan is read-only; apply is the only writer. See the
walkthrough and tuning.
plan
Deterministic read-only diff; prints the plan and writes the planfile.
| Option | Description |
|---|---|
--out <file> | Override the plan.json output path |
plan never changes anything — it computes the same diff apply will enact, so you can
run it as often as you like. The planfile is git-ignored.
apply
Preview the plan, confirm, then execute it (idempotent; promote rows first to build them).
| Option | Description |
|---|---|
--yes | Skip the confirmation prompt (required in a non-interactive shell) |
--prune | Also delete orphaned page bundles for removed identities (destructive) |
apply is Terraform-style: it shows the intended actions and prompts Proceed? [y/N]
before writing. It only acts when there’s a difference, so it’s always safe to re-run.
Lifecycle — drive pages through their states
These set a page’s status; they are deliberate human edits to the registry. See
lifecycle.
promote
Move rows forward in the lifecycle (sets status; never builds).
| Argument | Description |
|---|---|
[slugs...] | Exact slugs to promote (composes with the selector flags) |
demote
Move rows backward in the lifecycle (sets status; never builds).
| Argument | Description |
|---|---|
[slugs...] | Exact slugs to demote (composes with the selector flags) |
Selectors (shared by promote and demote). Field predicates compose with AND;
--under is a graph walk:
| Selector | Selects |
|---|---|
--section <name> | Rows in a section |
--cluster <name> | Rows in a cluster (any axis) |
--tier <id> | Rows at a tier |
--page-type <id> | Rows of a page type |
--slug-prefix <str> | Rows whose slug starts with this prefix |
--status <state> | Scope to rows currently in this status |
--under <hub-slug> | A hub slug + everything reachable down the mesh from it |
--to <status> | Target status (default: queued for promote, backlog for demote) |
--dry-run | Preview the transition without writing |
publish <slugs...>
review/ready → published.
| Argument | Description |
|---|---|
<slugs...> | Page slugs to publish |
recreate <slugs...>
Archive a body and re-enter the write flow.
| Argument | Description |
|---|---|
<slugs...> | Page slugs to recreate |
amend <slugs...>
Re-open a sealed/published page for a light re-seal (after image placement) → needs_update.
| Argument | Description |
|---|---|
<slugs...> | Page slugs to amend |
seal <slugs...>
Validate (schema + editorial lints) then writing → review, stamp built hashes.
| Argument | Description |
|---|---|
<slugs...> | Page slugs to seal |
validate [slugs...]
Validate page YAML against schema + editorial lints.
| Argument | Description |
|---|---|
[slugs...] | Page slugs to validate (default: every scaffolded page) |
Run with no slugs to also check committed inputs (reference tables, seed pages, discovery seeds) against the engine’s column contracts.
Inspect — see the state of the mesh
status
Per-status counts, drift, the writer worklist, and the render set for --env.
| Option | Description |
|---|---|
--env <env> | Also show the renderable set for this environment |
--summary | Counts only (omit the writing worklist) |
render-manifest
Emit the renderable slug set for an environment.
| Option | Description |
|---|---|
--env <env> | (required) Environment (e.g. local | dev | prod) |
--out <file> | Override the manifest output path |
Consume — generate the content-types package
types
Generate the SSG-facing TS content-types package from schemas/ (--check verifies sync,
no write).
| Option | Description |
|---|---|
--check | Verify the committed package matches the schemas (CI gate); exits non-zero on drift |
--dir <path> | Override the package directory (default: config.codegen.dir) |
This emits a self-contained, buildable TypeScript package your website (or any TS consumer)
compiles against. Wire gtmesh types --check into CI so the consumer’s types can’t drift
from the content contract.
Maintain — keep the engine fresh
upgrade
Re-apply engine-owned scaffold files (refresh; never clobbers your edits or project files).
| Option | Description |
|---|---|
--dry | Report the plan without writing anything |
--with-defaults | Also write changed project-file defaults as *.default for hand-merging |
Engine-owned files are refreshed if you haven’t touched them; if you have, the new version
lands as <file>.new. Project-owned files (config, reference data, your per-type schemas,
templates) are never overwritten. Idempotent. See Installation for the
full upgrade workflow (and how to bump the CLI itself).
migrate (adopt an existing content repo) is registered but not yet implemented — it
prints a notice and exits non-zero. A greenfield project doesn’t need it.