Why Keyword Lists Go Wrong
Most keyword work stalls in one of three places: no numbers, the wrong numbers, or numbers about somebody else’s business.
A List With No Numbers On It
A spreadsheet of phrases someone brainstormed has no volume, no difficulty and no record of where you already rank, so every decision about what to write next is a guess.
Volume Without Your Position
A keyword tool that does not know your site treats a term you sit at #11 for exactly like one you have never ranked for. The striking-distance win and the two-year project look identical.
Discovery That Wanders Off Topic
Keyword-idea APIs expand on shared word stems. Seed one on "schema markup" and it will happily return "star schema vs snowflake schema", a database question no reader of yours is asking.
How SEOAgent Researches Keywords
One inventory per site, enriched with real provider data and your own performance, extended by two paid commands when you want more candidates.
Enrichment That Knows Your Position
`seoagent keywords` sends your inventory to DataForSEO for volume and difficulty, joins each row with the position Search Console reports for your site, and labels it as an easy win or low priority.
Cold Start From Search Console
`seoagent keywords --seed` bootstraps an empty inventory from the queries your site already gets impressions for. Nothing invented, nothing to type in.
New Candidates, Judged Before You See Them
`seoagent keywords --discover` asks DataForSEO for keyword ideas seeded from your existing strategy, then runs a relevance judge over every candidate against your business context. Off-topic rows are hidden and the verdict is stored, so the same junk is not proposed twice.
Competitor Gap, Organic Only
`seoagent keywords --competitors` reports the keywords your rivals rank in the organic top 10 for and you do not track, ranked by opportunity score with a cap per competitor. The rivals it analyzed are saved to your dashboard’s Competitors section.
One Free Lookup, No Account
`seoagent keywords --peek "keyword research tool"` returns volume, difficulty and intent for a single keyword without logging in, on a daily quota. Add `--json` to pipe it into a script.
Results Land in Your Repo
Every mode writes to `.seoagent/keywords.md`, a read-only projection you read like any other file in the repo. `seoagent keywords --purge` clears suggested rows that discovery or competitor gap got wrong.
How Keyword Research Works
Connect Search Console
Run `seoagent login` and link Google Search Console. Keyword data is cloud-connected: the volume provider and your GSC position both live on the server side, so this step is required for everything except `--peek`.
Seed the Inventory
On a site with no keyword list yet, `seoagent keywords --seed` fills it from your own impressed queries. On a site that already has a strategy, skip straight to enrichment.
Enrich, Then Extend
`seoagent keywords` puts real numbers on what you have. `--discover` and `--competitors` are the paid commands that add candidates: keyword ideas from your strategy, and organic gaps from your rivals.
Turn Keywords Into Briefs
The keywords you keep feed the strategy clusters and the brief writer, which proposes the next article. You approve each brief, and your coding agent drafts it in your repo.
Keyword Research Use Cases
Finding the Striking-Distance Wins
Sort an enriched inventory by your own position to find the terms sitting just off page one, where a rewrite moves the needle faster than a new article.
Competitor Gap Before a Quarter
Pull the keywords rivals rank in the organic top 10 for and you do not track, then plan the quarter against that list instead of a brainstorm.
A Brand-New Site With No Data
Seed from the first impressions Search Console reports, enrich them, and get a first cluster out of a site that has been live for a month.
Checking One Keyword Mid-Task
Ask your coding agent for the volume and difficulty of a single phrase while it drafts, without leaving the editor or creating an account.
Client Research at Onboarding
Seed, enrich and run competitor gap for a new client in one session, then hand back a keyword file they can read in the repo.
Keeping a Large List Current
Enrichment refreshes weekly for connected sites, so volume, difficulty and your position stay current on a list too large to recheck by hand.
Frequently asked questions
Where does the volume and difficulty data come from?
DataForSEO. SEOAgent does not estimate volume itself, and it never fills a missing number with a guess: a keyword the provider has no data for is reported with no volume rather than an invented one.
Do I need a paid plan?
`seoagent keywords --peek <keyword>` is free, needs no account, and looks up one keyword at a time on a daily quota. Enrichment and seeding need `seoagent login`, and the free plan enriches a capped part of your list. Discovery and competitor gap are paid.
What stops discovery from returning irrelevant keywords?
A relevance judge runs over the candidates the provider returns, scoring each against the business context in `.seoagent/context.md`, before the CLI reports anything. Candidates ruled off-topic are hidden and their verdict is stored so they are not proposed again. Without business context the judge cannot rule, and the CLI says the list is unjudged rather than pretending it was checked.
Can I edit .seoagent/keywords.md by hand?
No. It is a read-only projection of the cloud inventory and it is rebuilt on every sync, so hand edits are overwritten. Remove keywords with `seoagent keywords --purge`, which clears suggested rows, or `--purge --all` to clear the whole site.
Can I run this from chat or leave it to autopilot?
Not today. Seeding, discovery and competitor gap are CLI commands you run. Enrichment is the one that also runs on a weekly cloud refresh for connected sites.
Does SEOAgent publish articles for the keywords it finds?
No. SEOAgent never publishes to a CMS. Keywords you keep become briefs, briefs become drafts your coding agent writes into your repo, and you review the diff and ship it through your own pipeline.
More of the SEO engine
Every feature runs from the same Skill in your repo — install once, get all of it.
Put Real Numbers on Your Keyword List
Install the free SEOAgent Skill and run `seoagent keywords --peek` on any phrase. Connect Search Console when you want your own position joined to every row.