# Command reference > Everything you do with Heddle by hand is one command, heddle followed by its name, run from your site's repository. Run heddle on its own to list them. The 32 commands below are grouped by when you need them, from setting up and research to building and checking the site, running agents, publishing and operations. Each has its flags, an example and the accounts it needs. Canonical: https://heddle.pro/docs/commands --- ## 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | Examples: ### 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --name n | The company's name. | | --url u | The live site's address. | | --contact e | The public contact address. | | --one-line text | The one-sentence description. | | --short text | The short description. | | --config dir | A prepared heddle/ folder, copied over the template instead of the basics. | | --with f,.. | Features to add: worker, next, agents, deploy, config-check, ideas, approvals, smoke. | | --without f,.. | Features to leave out. | | --app next | Also write a starter Next.js site that reads every fact from heddle/. | | --worker name | The Worker's name. | | --account id | The Cloudflare account id (CLOUDFLARE_ACCOUNT_ID otherwise). | | --contact-to e | Where the contact form's mail goes. | | --mail-from e | The address the site sends from. | | --preview url | Passed to the launch checklist: check the preview host too. | | --force | Replace managed files even where they were edited in the site. | | --dry-run | Print the plan and write nothing. | | --no-launch | Skip the launch checklist at the end. | | --apply | Let the launch checklist do the Cloudflare and GitHub steps it can. | Examples: 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/. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | Examples: ### 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. | Argument or flag | What it does | | check|install|public | What to do; nothing regenerates skills/heddle/ in Heddle itself. | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --check | install: exit 1 when the site's copy or pointer is stale. | | --zip file | public: also write the skill as a zip. | Examples: ### 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --apply | Create what is missing on Cloudflare (KV, Email Routing, the DMARC record, Turnstile hostnames). Needs the launch token; never edits or deletes. | | --preview url | Also check the preview host before the domain is attached. | | --json | The checklist as JSON. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --with f,.. | Add these features. | | --without f,.. | Remove these features. | | --force | Replace managed files even where they were edited in the site. | | --dry-run | Print the plan and write nothing. | Examples: ## 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | check|balance|keywords|serp|track|gsc|hn|reddit | What to read. | | --json | Raw rows as JSON. | | --location "City,State,Country" | serp: read the page as seen from this place. City searches must be read from the city. | | --save | track: record this reading as the new baseline (refused within 21 days of the last). | | --force | track: read every target even if read recently. | | --slice | track: only the targets due today, each once every 21 days. | | --sitemap "" | gsc inspect: inspect the sitemap URLs matching this. | | --days n | gsc prune: the window (default 90). | | --all-countries | gsc: read beyond the market country in company.json. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --family id | The page pattern (heddle families lists them). | | --values file | The changing part of the pattern, one per line. | | --places file | The same, for a place pattern. | | --limit n | How many to list (default 30; 40 for --competitors). | | --serp n | Also read the live results page for the top n. | | --competitors | What company.json's competitors rank for instead. | | --json | Results as JSON. | Examples: 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. | Argument or flag | What it does | | --kind service|product | Only the patterns that suit a service company or a product. | Examples: ### 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. | Argument or flag | What it does | | | A site repository (the URL comes from company.json) or any https:// address. | | --max n | The most pages to fetch (default 500). | | --out dir | Where to write audit-.md and.json (default heddle/, or the current folder for a URL). | | --quiet | No progress lines. | Examples: ### 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --from url | The live site to read, when it is not company.json url. | | --dry-run | Print what it found and write nothing. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | status|get|tools|mcp | What to do. | | | get: a capability status lists, such as keywordVolume. | | --paid | tools and mcp: offer the capabilities that spend credit. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --dry-run | List what would change. | Examples: ### 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | platform | Lint the Worker config, workflows and tests against the platform constraints instead. | | --only a,b | Run only these checks (heddle check with no site lists them). | | --out dir | The build folder, when it is not site.json outDir. | | --content dir | The Markdown content folder, when it is not site.json contentDirs. | | --offline | Skip the checks that need the model or the network, on purpose. They show as SKIPPED. | | --require-model | Fail when a model check could not run, as CI does. | | --update | Let a check that keeps a record rewrite it (the search surface, the helpful baseline, which only tightens). | | --json | Results as JSON. | | --strict | Fail closed, as CI does without --offline: a model check that cannot run fails, a page the helpful gate cannot read fails, a reading the branch committed is read again, and the helpful floors and baseline are compared with --base (playbook/quality-gates.md). | | --record-only | Only compare the helpful record (site.json helpful and the baseline) with --base, with no build and no model: the model-free check a fork's pull request gets. | | --base ref | The git ref to compare against: for check platform, and for the helpful record in strict mode (default origin/$GITHUB_BASE_REF, else site.json helpful.base, else origin/main). | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --out dir | The build folder, when it is not site.json outDir. | | --dry-run | Print llms.txt and write nothing. | Examples: ### 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --check | Render nothing. Exit 1 if a diagram is uncaptioned, unrendered or rendered in an older theme. | | --force | Render everything again, after a brand colour or font changes. | | --prune | Delete rendered SVGs no diagram uses any more. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --remote | Fetch an image from the live site when there is no local copy (media kept in object storage). | Examples: ### 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --out dir | Write the kit somewhere other than site.json brand.kitDir (default public/brand/kit). | | --dry-run | List the files it would write. | | --date YYYY-MM-DD | The date stamped in the kit's manifest, for a reproducible build. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --only slug,slug | Only these posts. | | --max n | At most this many covers (default 20). | | --dry-run | List the posts it would draw. | | --fallback | Write the deterministic fallback cover for every post without a drawn one. No model. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --dry-run | List what would change. | Examples: ### 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --dry-run | Say whether the data would change, and write nothing. | | --check | No site: exit 1 when a command has no reference entry or its flags drift, a credential the code reads is undescribed, or a configuration field has no description. | Examples: ## 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. | Argument or flag | What it does | | | The agent: memory, research, strategy, content, families, writer, seo, refresh, authority, site, followup, paid, covers, video, watchdog or canary. | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --dry-run | Read, decide and print the report and the pull requests it would open. Writes nothing. | | --level off|report|propose|merge | Run below the configured level. A higher value is ignored. | | --force | Run even though a clean run already happened inside the schedule. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --all | Every entry, closed ones included. | | --json | The counts and open entries as JSON. | Examples: ### 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --dry-run | Decide and print. No state, no branch, no email. | Examples: 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. | Argument or flag | What it does | | | A few plain words or a question. | | --limit n | How many results (default 8). | | --kind lesson,check,... | Only these kinds: playbook, lesson, tactic, check, family, agent. | | --json | Results as JSON. | | --full | Each result in full rather than its first lines. | | --public | Only what the public playbook publishes (public lessons). | Examples: ### 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. | Argument or flag | What it does | | --site | Also mount the site's search data tools (heddle data). | | --paid | With --site, allow the tools that spend data credit. | Examples: ## 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. | Argument or flag | What it does | | key|submit|list|record | What to do. | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | paths... | submit: only these paths or URLs. | | --all | submit: every sitemap URL, not only the changed ones. | | --send | list: email the list to the indexing bot. | | --dry-run | Print what would be submitted or sent. | | --local | submit: submit from your machine even though the site deploys from CI (CI will not see the state until it is committed). | | --delta file | submit, in CI: write what IndexNow accepted to this file for record. | | --push branch | record: commit and push the merged state, retried from a fresh branch. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --dry-run | List what would be uploaded. | | --force | Upload everything again. | | --verify | Fetch every object and compare it with the manifest. | | --orphans | List files no built page references. Never deletes. | | --headers | Check each live URL answers 200, immutable, from the bucket. | Examples: 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. | Argument or flag | What it does | | check|render|watch|publish | The step. | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | | The film's spec, video/specs/.json. | | --out dir | Where the film is written or read (default $VIDEO_OUT or the temp folder). | | --stills 3,12.5 | render: only frames at these seconds. | | --voice deepgram | render: a free draft voice instead of the configured one. | | --public | publish: upload as public (YouTube keeps it private until the API project is audited). | Examples: 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. | Argument or flag | What it does | | run|verify | Deploy, or prove the deploy is live. | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --local | run: deploy from your machine. CI still owns IndexNow and heddle/indexing.json. | | --prepare-only | run: build, check, copy the build into the Worker's assets and stamp it, then stop before wrangler deploy. The preview and smoke workflows upload that folder as a preview version. | | --sha s | The commit being deployed, for the stamp. | | --origin url | verify: the live address, when it is not site.json baseUrl or company.json url. | | --sample n | verify: how many sitemap pages to probe (default 20). | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --upload-log file | The wrangler upload log, to read the preview URL from. | | --preview-url url | The preview URL, when it is known. | | --dispatch-canary | Start the canary workflow afterwards. | | --canary-after-record | Leave the canary to the workflow, once the record is pushed. | | --canary-dry-run | Say what would start the canary, without starting it. | | --record-into dir | A checkout of the default branch to write the deploy record into. | | --sha sha | The deployed commit, for the record. | | --ref ref | The deployed branch, for the record. | | --prep step=outcome;... | The outcomes of the steps before it; anything but success fails the smoke. | | --print-config | Print the Worker config the smoke reads, and stop. | Examples: 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. | Argument or flag | What it does | | | The site's repository: the folder that holds heddle/. Use. when you are in it. | | --json | The findings as JSON. | Examples: Generated from the Heddle repository at d2b6328. ## Questions ### What do the exit codes mean? 0 is success, 1 is a failure the command explains, and 2 means the arguments were wrong: heddle prints every command's usage line and exits with 2. ### Do commands change my site? Commands that write say so and take --dry-run, which prints what would change and writes nothing. heddle check, validate, launch without --apply, recommendations and research only read.