Ahrefs integration
What it is
The keyword and SERP data source that feeds the mesh. GoToMesh talks to the
Ahrefs API directly (not via an MCP) through two CLI surfaces:
extract, which fills the
bag the deterministic loop reads, and
research, whose pulls feed the discovery skill.
The adapter spec (docs/spec/gtmesh-ahrefs-integration.md) has the full detail
if you are extending it.
Why it matters
Routing every networked provider pull through the gtmesh CLI keeps two things
honest. First, the data lands as immutable, timestamped exports on committed
disk, so plan reads a frozen bag and never re-fetches — a plan is reproducible
from the repo. Second, skills stay provider-agnostic: they ask the CLI for data
rather than reaching out to a provider themselves.
How it works
A cluster extract runs the two-pull pattern — matching-terms (the broad
keyword expansion) and questions — and writes the result under
data/raw/keywords/ahrefs/. The research subcommands (serp, keywords,
top-pages) are the discovery-time pulls that explore a SERP, a keyword
universe, or a competitor’s top pages.
The query shape is config, not code. Under adapters.ahrefs in
gtmesh.config.yaml you set volume_floor, the select columns, the pulls,
the per-cluster seeds (always qualified — a bare crm pulls noise), and
exclude_substrings to strip auth and brand-asset junk. The pull country is
derived from taxonomy.markets — never set it on the adapter.
AHREFS_API_TOKEN comes from the environment, never the config file. No budget?
gtmesh extract --source csv --input export.csv imports a CSV instead.
Key files & flags
| Where | What it controls |
|---|---|
gtmesh.config.yaml adapters.ahrefs | volume_floor, select, pulls, seeds, exclude_substrings |
gtmesh.config.yaml taxonomy.markets | The single source for the pull country |
AHREFS_API_TOKEN (env) | API auth — never committed |
data/raw/keywords/ahrefs/ | The immutable, timestamped exports |
Related
extract— pull keyword data into the bagresearch— the discovery-time SERP/keyword/top-pages pulls- Installation — installing the CLI and setting the token