Command reference

Set up

heddle init

Starts a new install. It copies the company template into the site's heddle/ folder and installs Heddle's skill for coding agents, and it refuses to overwrite a heddle/ folder that already exists. Then replace every value marked REPLACE and run heddle validate.

heddle init <site-repo>

Examples:

# Create my-site/heddle/ from the template.
heddle init ../my-site

heddle install

Puts Heddle into a site in one command. It writes heddle/ from the company template, with the basics you pass as flags, the managed Worker, workflow and script templates for the features you choose, package.json scripts and packages, the IndexNow key, the skill for coding agents, and heddle/install.json, the record update and doctor read.

Then it runs the launch checklist. Nothing is prompted for; a value you leave out stays REPLACE and heddle validate names it.

heddle install <site-repo> [--name n --url u --contact e | --config dir] [--with f,..] [--without f,..] [--app next] [--dry-run] [--no-launch] [--apply]

Examples:

# See the plan first.
heddle install ../my-site --name "Acme" --url https://www.acme.test --contact hello@acme.test --dry-run
# A new site with the starter app.
heddle install ../my-site --name "Acme" --url https://www.acme.test --contact hello@acme.test --app next

Needs: git, GitHub CLI (gh), Cloudflare's cf CLI (npm package cf, pinned at 1.0.0-beta.14), CLOUDFLARE_ACCOUNT_ID.

heddle validate

Checks a site's heddle/ folder. It reads every file against its schema and looks for placeholders left in, agents above report with no approver, shared kill switches, the budget, the ledger and the family datasets, and exits 1 on any error. Run it after every edit to heddle/.

heddle validate <site-repo>

Examples:

# Is the install's configuration complete and consistent?
heddle validate .

heddle skill

Heddle's method as an Agent Skill for coding agents. install copies it into a site's .claude/skills/heddle/ and points the site's AGENTS.md and CLAUDE.md at it; public writes the publishable variant with public lessons only. With no argument it regenerates the skill inside the Heddle repository.

heddle skill
heddle skill check
heddle skill install <site-repo> [--check]
heddle skill public <dir> [--zip file]

Examples:

# Give the site's coding agents the current skill.
heddle skill install .
# In CI: fail on a stale copy.
heddle skill install . --check

heddle launch

The go-live checklist for a site, covering the Cloudflare zone, Worker, domain and KV, email in and out, DMARC, Turnstile, Search Console, GitHub secrets and workflows, and the live site. Prints PASS, TODO with the exact next step, FAIL or SKIP for each.

Read-only, unless --apply, which does only the safe Cloudflare steps it found missing.

heddle launch <site-repo> [--apply] [--preview url] [--json]

Examples:

# Where the launch stands.
heddle launch .
# Do the safe Cloudflare steps, then rerun without --apply.
heddle launch . --apply

Needs: GitHub CLI (gh), CLOUDFLARE_LAUNCH_TOKEN, CLOUDFLARE_API_TOKEN, GSC_KEY_FILE, PLUNK_API_KEY.

heddle update

Brings an install's managed files, package.json scripts and record up to the Heddle you have checked out. A managed file that was edited in the site is refused, because the change belongs in Heddle's template, unless you pass --force.

It never touches the facts in heddle/ or the site's own files, and it does not run the launch checklist.

heddle update <site-repo> [--with f,..] [--without f,..] [--force] [--dry-run]

Examples:

# What a pull of Heddle would change in this site.
heddle update . --dry-run

Research

heddle research

Demand, results pages, positions and Search Console for your site. check says which credentials are set. keywords reads volume and cost per click, serp reads a live results page, track reads positions for heddle/targets.json, and gsc reads Search Console (low click-through, striking distance, compare, inspect, prune, weekly). hn and reddit find buyers' own words.

heddle research <site-repo> check
heddle research <site-repo> balance
heddle research <site-repo> keywords "<term>" ["<term>" ...]
heddle research <site-repo> serp "<query>" [depth] [--location "City,State,Country"]
heddle research <site-repo> track [--save] [--force] [--slice]
heddle research <site-repo> gsc check|low-ctr [days] [min]|query "<term>" [days]|striking [days] [min]
heddle research <site-repo> gsc compare "<path regex>" <YYYY-MM-DD> [days]|page "<path>" <YYYY-MM-DD> [days]
heddle research <site-repo> gsc inspect <path> [...] | --sitemap "<path regex>"
heddle research <site-repo> gsc weekly
heddle research <site-repo> gsc prune <path> [...] [--days 90]
heddle research <site-repo> hn|reddit "<query>" [limit]

Examples:

# Which data sources are configured.
heddle research . check
# DataForSEO's prepaid balance, before blaming the key.
heddle research . balance
# Volume and cost per click.
heddle research . keywords "ai seo agent" "seo automation"
# A local results page, read from the city.
heddle research . serp "plumber phoenix" --location "Phoenix,Arizona,United States"
# Searches at positions 4 to 20 worth a push.
heddle research . gsc striking 90 20

Needs: DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD, GSC_KEY_FILE, GSC_SERVICE_ACCOUNT_JSON, REDDIT_CLIENT_ID.

heddle propose

Measured candidate searches for one page pattern. It crosses the pattern with your values (cities, roles, products), reads search volume for each, and prints a shortlist with three judgement columns left blank for a person. With --competitors it lists what your competitors rank on page one for that you do not track.

heddle propose <site-repo> --family <id> [--values file] [--places file] [--limit n] [--serp n] [--json]
heddle propose <site-repo> --competitors [--limit n] [--json]

Examples:

# City pages, with three results pages read.
heddle propose . --family locations --places metros.txt --serp 3
# Demand your competitors have proved.
heddle propose . --competitors

Needs: DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD.

heddle families

Lists Heddle's catalog of page patterns (families), with the search each one answers, its doorway risk, and where it has been proven. Read it before choosing what kind of pages to build.

heddle families [--kind service|product]

Examples:

# The patterns that suit a product.
heddle families --kind product

heddle audit

Crawls the live site, up to a page limit, four pages at a time, and writes a technical audit as Markdown and JSON, covering status codes, titles, canonicals, noindex, sitemap coverage and the problems found. Works on any URL, so you can audit a site before it has a heddle/ folder.

heddle audit <site-repo|url> [--max 500] [--out dir] [--quiet]

Examples:

# Audit a site you have not set up yet.
heddle audit https://example.com --max 200
# Audit your own live site into heddle/.
heddle audit .

heddle legacy

Run it before an overhaul. It writes heddle/legacy-urls.txt from the live sitemap and, with Search Console credentials, every page that has had impressions. The URL check then makes sure each old address still resolves on the new site. Run it before building the new site and again before cutover.

heddle legacy <site-repo> [--from url] [--dry-run]

Examples:

# Inventory the old site before replacing it.
heddle legacy . --from https://www.example.com

Needs: GSC_KEY_FILE.

heddle data

The search data providers a site declares in site.json and what each answers. status shows which provider answers each capability and which credential is missing, get reads one capability by hand, and tools and mcp offer the same data to a model or a coding agent.

Paid capabilities are refused there unless --paid, and every paid call is held to the provider's per-run cap.

heddle data <site-repo> status
heddle data <site-repo> get <capability> [json]
heddle data <site-repo> tools [--paid]
heddle data <site-repo> mcp [--paid]

Examples:

# Which provider answers what, and what is missing.
heddle data . status
# One reading by hand.
heddle data . get keywordVolume '{"terms":["seo agent"]}'

Needs: DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD, GSC_KEY_FILE, PAGESPEED_API_KEY.

Build and check

heddle generate

Writes heddle/generated/ from the family datasets, one JSON file per family with every publishable row and the sibling links each page must carry. It also writes the public playbook and the documentation when site.json asks for them. The site's build runs it first.

heddle generate <site-repo> [--dry-run]

Examples:

# Regenerate after editing a dataset.
heddle generate .

heddle check

Runs the quality gates on the built site, from titles, structured data and links to uniqueness, prose, claims and the model-judged gates. Run it after every build and before every pull request; the deploy script runs it and stops on a failure.

Without the model token the model gates report SKIPPED, which is not a pass, and in CI they fail.

heddle check <site-repo> [--only a,b] [--out dir] [--content dir] [--offline] [--require-model] [--update] [--json]
heddle check platform <site-repo> [--base origin/main] [--only a,b] [--json]
heddle check

Examples:

# Every gate, with the model.
heddle check .
# The code gates only, with no token and no network.
heddle check . --offline
# Two gates while you edit copy.
heddle check . --only humanizer,claims
# The platform lint on what changed.
heddle check platform . --base origin/main

Needs: Chromium or Google Chrome, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN.

heddle aeo

Writes the answer-engine files into the built site after the export and before the deploy. Those are a Markdown twin of every page, llms.txt, llms-full.txt and, when site.json asks, _headers. It writes nothing if any twin would come out thin or disagree with its page.

heddle aeo <site-repo> [--out dir] [--dry-run]

Examples:

# Run after next build; the site's build script does it for you.
heddle aeo .

heddle diagrams

Renders every mermaid block in the site's posts and datasets to an SVG in the brand's colours and font, so the page inlines a captioned figure instead of running a script. Commit what it writes; the build fails on a diagram with no render.

heddle diagrams <site-repo> [--check] [--force] [--prune]

Examples:

# Render what is new.
heddle diagrams .
# In CI: fail on a stale or missing render.
heddle diagrams . --check

Needs: Chromium or Google Chrome.

heddle images

Measures every image the site's content references into heddle/image-dimensions.json, so each image on a page gets its width and height and the page does not jump while it loads. Only new images are read. Commit what it writes.

heddle images <site-repo> [--remote]

Examples:

# Measure images that live only in R2.
heddle images . --remote

heddle brand

Checks heddle/brand.json against its schema and against company.json, then builds the downloadable brand kit the /brand page links to, with logos in each format, the colours and type, and one zip. Commit what it writes.

heddle brand <site-repo> [--out dir] [--dry-run]

Examples:

# Rebuild the kit after a logo or colour change.
heddle brand .

Needs: ImageMagick, librsvg and zip.

heddle covers

Draws a cover for every published post that has none, checks it against the cover rules and the judging model, and writes the SVG and a 1200x630 share image into the site's covers folder. With --fallback it writes the plain, model-free cover instead. Commit what it writes.

heddle covers <site-repo> [--only a,b] [--max n] [--dry-run] [--fallback]

Examples:

# Draw three covers.
heddle covers . --max 3
# Make sure no listing shows a hole.
heddle covers . --fallback

Needs: CF_AIG_TOKEN, CF_AIG_GATEWAY, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN.

heddle playbook

Writes the public playbook for a site whose site.json has a playbook block. The pages' data goes to heddle/generated/playbook.json, and the public Agent Skill and its zip go under the route. heddle generate does the same; this runs it alone.

heddle playbook <site-repo> [--dry-run]

Examples:

# Refresh the playbook pages' data.
heddle playbook .

heddle docs

Writes the documentation pages' data for a site whose site.json has a docs block, covering getting started, installing, this command reference, agents and autonomy, configuration and troubleshooting, all generated from Heddle itself. heddle generate does the same at every build. With --check it reports any command, credential or setting the documentation cannot describe.

heddle docs <site-repo> [--dry-run]
heddle docs --check

Examples:

# Refresh heddle/generated/docs.json.
heddle docs .
# In Heddle: is every command, credential and setting documented?
heddle docs --check

Agents

heddle agent

One run of one agent against a site. The level comes from autonomy.json and can only be lowered here. A run that already succeeded inside the agent's schedule does nothing unless forced. The scheduled workflow calls this; you run it by hand to try an agent or to see what it would do.

heddle agent <id> <site-repo> [--dry-run] [--level l] [--force]

Examples:

# What the SEO agent would do today, without doing it.
heddle agent seo . --dry-run
# Run the watchdog, reporting only.
heddle agent watchdog . --level report

Needs: git, GitHub CLI (gh), CF_AIG_TOKEN, CF_AIG_GATEWAY, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, DATAFORSEO_LOGIN, GSC_KEY_FILE, PLUNK_API_KEY.

heddle recommendations

Prints the recommendations ledger, with every recommendation an agent made, what is still open, oldest first, and who it waits on. Anything open past the limit is marked overdue. Close an entry by editing heddle/recommendations.json and running heddle validate.

heddle recommendations <site-repo> [--all] [--json]

Examples:

# What is waiting, and on whom.
heddle recommendations .

heddle ideas

One pass of blog ideas by email. It reads the ideas the site's Worker holds, then drafts, asks the author, publishes on the author's signed approval, or withdraws each one. The heddle-ideas workflow runs it when mail arrives and every hour.

heddle ideas <site-repo> [--dry-run]

Examples:

# What the next pass would do.
heddle ideas . --dry-run

Needs: git, GitHub CLI (gh), CF_AIG_TOKEN, CF_AIG_GATEWAY, HEDDLE_IDEAS_TOKEN, PLUNK_API_KEY.

heddle advise

Prints the parts of Heddle's playbook, lessons, tactics, checks, page patterns and agents that bear on a topic, as Markdown. A coding agent runs it before changing anything search-relevant. It searches local files by keyword, so it needs no model or network and spends nothing.

heddle advise <topic> [--limit n] [--kind lesson,check,...] [--json] [--full]

Examples:

# What Heddle says about sitemap dates.
heddle advise "sitemap lastmod"
# The lessons and checks about canonicals, as JSON for a script.
heddle advise canonical --kind lesson,check --json

heddle mcp

A read-only MCP server, over stdio, that lets a coding agent search Heddle's playbook, lessons and checks while it works. With --site it also serves that site's search data tools, the free ones only unless --paid. Register it once with your agent.

heddle mcp [--site <site-repo> [--paid]]

Examples:

# Started by the agent: claude mcp add heddle -- node <heddle>/bin/heddle.mjs mcp
heddle mcp
# The same, with this site's free search data tools.
heddle mcp --site .

Publish

heddle indexing

Getting new and changed pages crawled. key creates the IndexNow key and its file. submit sends the sitemap URLs that are new or changed since the last accepted submission to IndexNow (Bing and others) after every deploy; where the site deploys from GitHub Actions, CI does this and owns heddle/indexing.json.

list prints today's Search Console list for the indexing bot and, with --send, emails it. record is the deploy workflow's step that merges what a submit accepted.

heddle indexing key <site-repo>
heddle indexing submit <site-repo> [--all] [--dry-run] [paths...]
heddle indexing list <site-repo> [--send] [--dry-run]
heddle indexing record <dir> <delta.json> [--push branch]

Examples:

# Once: commit site.json and the key file, then deploy.
heddle indexing key .
# After every deploy.
heddle indexing submit .
# Today's indexing list, without sending it.
heddle indexing list . --dry-run

Needs: GSC_KEY_FILE, PLUNK_API_KEY.

heddle media

Keeps the site's images and video in an R2 bucket instead of the repository, with a committed content-hash manifest, so only what changed is uploaded. Also verifies the bucket against the manifest, lists files no page uses and reads the live headers.

heddle media <site-repo> [--dry-run] [--force] [--verify] [--orphans] [--headers]

Examples:

# What a sync would upload.
heddle media . --dry-run
# Upload, then commit the manifest.
heddle media .

Needs: wrangler (Cloudflare's Workers CLI).

heddle video

One step of an explainer video by hand. check runs the word checks on the script (free). render makes the film. watch has the model watch it. publish uploads a merged, rendered film to the YouTube channel, private unless --public; only a person runs it. The video agent does check, render and watch itself.

heddle video check <site-repo> <slug>
heddle video render <site-repo> <slug> [--out dir] [--stills t,t] [--voice deepgram]
heddle video watch <site-repo> <slug> [--out dir]
heddle video publish <site-repo> <slug> [--out dir] [--public]

Examples:

# The free checks on a script.
heddle video check . what-is-aeo
# A draft render.
heddle video render . what-is-aeo --voice deepgram

Needs: ffmpeg, ELEVENLABS_API_KEY, YOUTUBE_CLIENT_ID, YOUTUBE_CLIENT_SECRET, YOUTUBE_REFRESH_TOKEN.

heddle deploy

Deploys the site and proves it is live. run builds, validates, runs the code checks, copies the build into the Worker's assets, stamps it and runs wrangler deploy. verify waits until the live site serves that build's stamp, then runs the canary's probe of it, and exits 1 on any problem.

The deploy workflow runs both on every merge; from a laptop, run --local deploys the working tree.

heddle deploy run <site-repo> [--local] [--sha s]
heddle deploy verify <site-repo> [--sha s] [--origin url] [--sample n]

Examples:

# Deploy the working tree from your machine.
heddle deploy run . --local
# Is the new build what the live site serves?
heddle deploy verify .

Needs: wrangler (Cloudflare's Workers CLI), CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.

Operate

heddle smoke

The post-deploy smoke test the deploy workflow runs. It finds the preview URL, checks the Worker's bindings and the pages a deploy must serve, records the result in heddle/deploys.json, and starts the canary. A deploy that did not pass it is not to be trusted.

heddle smoke <site-repo> [--upload-log file] [--preview-url url] [--dispatch-canary | --canary-after-record] [--canary-dry-run] [--record-into dir --sha s --ref r] [--print-config]

Examples:

# Smoke a preview by hand.
heddle smoke . --preview-url https://my-site.example.workers.dev

Needs: GitHub CLI (gh).

heddle doctor

Fails when an installed template differs from Heddle's, when Heddle's machinery exists a second time in the site, or when config an installed feature needs is missing. Local and read-only; the config-check workflow runs it on every pull request.

heddle doctor <site-repo> [--json]

Examples:

# Has the site drifted from Heddle?
heddle doctor .