`gtmesh extract`

Runs an adapter to pull keyword/search signals into the data bag and appends a timestamped export to data/raw/.


gtmesh extract --cluster slack --dry-run   # report the planned pulls, spend nothing
gtmesh extract --cluster slack             # pull one cluster
gtmesh extract                             # all configured seed clusters

What it does

extract pulls keyword and search signals into the data bag. Raw exports are immutable and timestamped — plan reads the frozen bag and never re-fetches, which is what keeps the pipeline deterministic.

Three sources:

--source ahrefs (default) — runs the Ahrefs adapter; needs AHREFS_API_TOKEN set.
--source csv — imports a CSV with no API budget (pair with --input).
--source seeds — refreshes the volume/difficulty metrics for a curated discovery term list without expanding it. Terms stay in seeds/<class>.csv; metrics land in data/raw/.

Arguments & flags

Option	Description	Default
`--source <source>`	Adapter to run (`ahrefs` \| `csv` \| `seeds`)	`ahrefs`
`--cluster <id>`	Cluster to pull	all configured seed clusters
`--pull <kind>`	Single pull (`matching-terms` \| `questions`)	configured pulls
`--input <file>`	Source CSV (for `--source csv`)	—
`--class <id>`	Discovery class to refresh (for `--source seeds`)	all configured
`--dry-run`	Report the planned pulls without spending API credits	off

--source ahrefs spends API credits. Run with --dry-run first to see exactly which pulls will fire.

Reads & writes

Reads: the adapters.ahrefs config, your seeds and clusters (and --input for the CSV source).
Writes: timestamped exports under data/raw/keywords/ahrefs/ (and the data/raw/ paths for seed refreshes).
Committed: yes — the raw exports are diffable and committed.

Examples


# Keyword pulls for a cluster (two pulls: matching-terms + questions):
gtmesh extract --cluster slack
 
# No API budget — import an existing CSV instead:
gtmesh extract --source csv --input export.csv --cluster slack
 
# Refresh metrics for curated discovery terms (no expansion):
gtmesh extract --source seeds --dry-run
gtmesh extract --source seeds                    # every configured class
gtmesh extract --source seeds --class glossary   # one class

Platform: Ahrefs integration, Discovery & harvest
Guide: Walkthrough
CLI: gtmesh research, gtmesh plan

gtmesh extract