Codex Terminal SEO Workflow: JSON-First Growth Automation

JSON-first beats prompt-first for SEO ops

Prompt-first agents improvise priorities. JSON-first agents execute queues. Search Console and GA4 already export structured data. Mission Briefs and opportunity lists should look the same: stable keys, cited evidence, ICEE scores. Codex and terminal workflows thrive when every step reads and writes JSON, not prose summaries that drift between sessions.

Pipeline architecture

Sample JSON contract for agents

Treat Mission Brief output as the source of truth. Each order should expose slug or id, url, orderType, icee scores, evidence queries, and recommended action. Your Codex task reads that object, not a paraphrase. Store raw JSON in .growth/brief-latest.json for diffing week over week.

• Never mutate brief JSON to reprioritize. Pull fresh after sync.
• Map orderType to handler scripts: refresh.sh, ctr-meta.sh, merge-map.sh.
• Pass evidence queries into Content Operations create payload.
• Exit non-zero on insufficient credits with user-visible message.

Claude Code SEO workflow and Cursor SEO workflow share the same contracts. This article emphasizes shell composition and Codex batch runs.

Shell composition pattern

A minimal Monday script: pull brief JSON, jq extract order one, call handler, append execution log. Friday script: pull brief again, diff target URLs, append measurement notes. Keep scripts in repo beside application code so agents discover them.

Use --json consistently. Human tables are for standups, not for agent parsers. REST API responses mirror CLI shape when you bypass the wrapper for custom tooling.

Order type handlers

GSC data to content tasks details writer handoffs for refresh and expand types. Keyword cannibalization workflow defines merge evidence requirements.

Credit-aware batch jobs

Batch Codex runs fail expensively without credit gates. Pattern: read balance JSON, estimate job cost from credits doc, abort early with clear stderr. Reserve-before-run semantics return explicit errors. Log attempted spend in execution JSON for finance questions.

Never loop content create across twenty URLs without human review checkpoints. Terminal automation accelerates ranked orders, not spray-and-pray publishing.

Repo hygiene for growth automation

Store brief snapshots, execution logs, and redirect maps in a dedicated directory. Commit after ship, not before review. Agents read last execution to avoid duplicate refresh on the same URL. Knowledge Base remains upstream in Learn Domains vault, not only in chat context.

1. •.growth/brief-latest.json from CLI pull
2. •.growth/executions/YYYY-MM-DD-order-id.json per ship
3. •.growth/redirects/pending.json for cannibalization work
4. •CLAUDE.md or AGENTS instructions pointing to handlers

Observability for terminal pipelines

Log each pipeline stage with timestamp and exit code. Monday pull success but Friday measurement skipped means you fly blind on order one. Simple append-only JSONL in .growth/pipeline.log beats silent cron failures.

Alert on repeated credit failures or auth errors. Those failures look like SEO stalls to stakeholders when the real issue is token expiry.

Testing handlers before Monday production

Dry-run handlers against demo mock data or a staging website before you wire Codex to production tokens. Validate jq paths when brief JSON schema adds fields. A broken handler that calls content create in a loop burns credits and writer trust.

Version pin @learndomains/cli in repo docs. Breaking API changes surface in changelog and /docs/api. Pin protects Monday scripts from silent flag renames.

Monday and Friday scripts reference

Monday script responsibilities: auth check, brief pull, jq extract order one, invoke handler, write execution stub. Friday script responsibilities: brief pull, compare target URL metrics notes, append measurement field to execution JSON, optionally post summary to team channel.

Keep scripts under two hundred lines each. Complexity drives silent failure. Operators maintain scripts like cron jobs: versioned, reviewed, logged.

• monday-growth.sh pulls and executes
• friday-measure.sh appends outcomes
• handlers.d directory one file per order type
• fail fast on empty brief or zero orders

CI integration optional path

Some teams run Friday measurement scripts in CI after deploy windows. Keep growth scripts separate from unit test pipelines to avoid blocking releases on GSC noise. CI logs complement .growth JSON but do not replace operator review of order outcomes.

Operators-guide-to-ai-powered-growth expands team patterns. Codex terminal workflow stays the minimal shell-first entry point.

Error handling conventions

Standardize exit codes across handlers: 0 success, 1 auth failure, 2 insufficient credits, 3 empty brief, 4 handler validation error. Agents and cron jobs parse codes consistently. Stderr messages should be one line, human readable, without dumping stack traces into Slack.

Retry policy: exponential backoff on 429 and 5xx from REST API. Do not retry 4xx except token refresh flows documented in troubleshooting. Log retry count in pipeline JSONL for postmortems.

Document handler exit codes in README beside scripts so the next operator does not reverse-engineer behavior from logs alone. Keep examples current when CLI flags change.

Limits and next steps

Codex terminal workflows do not replace operator judgment on keeper URLs, brand voice, or credit budget. They remove copy-paste and priority arguments. Full API reference at /docs/api. CLI at /docs/cli. Mission Brief Method defines ICEE keys agents should preserve in logs.

Treat terminal automation as infrastructure: small scripts, logged outcomes, human gates on publish. The best agents still fail when Monday starts without a ranked brief. Pull JSON first. Ship order one. Log the result. Repeat Friday.