gtmesh research
Groups the external (Ahrefs) discovery pulls used by the discovery skill — serp, keywords, and top-pages — as subcommands.
gtmesh research serp "<keyword>" --country gb
gtmesh research keywords --keyword "pump,water pump" --cluster pumps
gtmesh research top-pages example.com --mode subdomainsWhat it does
research is a group of networked Ahrefs pulls the discovery skill leans on during a discovery cycle. They route provider access through the CLI rather than the skill (so the skill stays provider-agnostic), and each appends a timestamped export under data/raw/. There is no top-level research action; you always call one of its three subcommands.
Every subcommand hits the Ahrefs API and spends credits. Each accepts --dry-run to report the planned pull without spending anything. --country is required when you run in a pre-init directory (there’s no config to default from yet).
gtmesh research serp <keyword>
Pull a keyword’s SERP from Ahrefs (serp-overview); append a timestamped export to data/raw/serp/.
| Argument / Option | Description | Default |
|---|---|---|
<keyword> | The keyword to pull the SERP for (a discovery cluster head) | — |
--country <cc> | ISO alpha-2 country | taxonomy.markets[0]; required pre-init |
--top <n> | Limit to the top N organic positions | all |
--dry-run | Report the planned pull without spending API credits | off |
gtmesh research keywords
Pull the keyword universe (Ahrefs matching-terms) for seed terms during discovery cycle 0; append to data/raw/keywords/.
| Option | Description | Default |
|---|---|---|
--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) | matching-terms |
--country <cc> | ISO alpha-2 country | config country, else us |
--dry-run | Report the planned pull without spending API credits | off |
gtmesh 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 | Default |
|---|---|---|
<domain> | The competitor domain to pull top pages for (e.g. example.com) | — |
--country <cc> | ISO alpha-2 country | taxonomy.markets[0]; required pre-init |
--date <yyyy-mm-dd> | Metrics reporting date | today (UTC) |
--mode <scope> | Search scope: exact | prefix | domain | subdomains | subdomains |
--limit <n> | Max pages to pull | all |
--dry-run | Report the planned pull without spending API credits | off |
Reads & writes
- Reads: the Ahrefs config (and
taxonomy.marketsfor the default country). NeedsAHREFS_API_TOKENset. - Writes: timestamped exports under
data/raw/serp/,data/raw/keywords/, anddata/raw/top-pages/respectively. - Committed: yes — the raw exports are diffable and committed.
Examples
gtmesh research serp "water pump" --country gb --top 10
gtmesh research keywords --keyword "pump,water pump" --cluster pumps --country gb
gtmesh research top-pages competitor.com --mode subdomains --limit 200 --dry-runRelated
- Platform: Ahrefs integration, Discovery & harvest
- Guide: Walkthrough, Discovery contract
- CLI:
gtmesh discover,gtmesh extract