idstitch CLI

The pipe between the idstitch platform and local AI agents (Claude Code, Codex, anything). Models keep improving — the CLI keeps handing whichever agent you run today your project's full analytics, and lets that agent log its changes back so the platform grades outcomes.

The agent layer (read this first)

Agents are the PRIMARY interface to this platform — and that is safe by construction. Everything the CLI can do is a data operation on a project-scoped surface: read analytics, log optimizations, curate the product map. Every write is validated server-side and scoped by the token. An agent can never touch application code, schema, or configuration — so you can hand this CLI to any agent and ask it to "fix things in the app": what it actually edits is your project's data, nothing else.

Install & login

npm i -g idstitch       # from npm (or `npm i -g ./cli` from this repo)
idstitch login idsk_…   # token from dashboard → Settings → API tokens
idstitch whoami

The token is project-scoped: it can only read this project's analytics and write its optimizations. Revoke any time in the dashboard.

The agent loop

# 1. Pull everything the platform knows (one JSON bundle)
idstitch pull > analytics.json

# 2. Let your local agent analyze it and edit the site
#    (your repo, your deploy — e.g. Claude Code / Codex session)

# 3. Deploy, VERIFY IT'S LIVE, then log — baseline auto-captured, review scheduled
idstitch opt log --title "Rewrote title/meta on /pricing" \
  --category seo_snippet --target gsc_ctr \
  --hypothesis "CTR 0.9% → 2%+" --urls https://example.com/pricing

After opt log, the platform's daily AI stops re-recommending that change and grades it when the review window elapses (seo_snippet 28d, content 21d, performance 28d, cta 14d, attribution 3d). idstitch opt list shows verdicts.

For agents (paste into your CLAUDE.md / AGENTS.md)

This project uses idstitch analytics. To analyze the site:
  1. `idstitch pull --days 30` → JSON: traffic, audience, GA4, Search Console,
     Clarity UX, platform AI insights, technical site scan, probabilistic AI
     visibility, demand (Google Trends + rising queries + People-Also-Ask),
     already-in-flight optimizations, and the strategic growth[] initiatives.
  2. Do NOT re-recommend anything present in optimizations[] with status
     "active" — it is already done and waiting for its review window.
  1b. BEFORE proposing strategic work, read growth[] (or `idstitch growth list`):
     do NOT redo an initiative that is "in_progress" or "done", and do NOT
     re-propose a "dropped" one — its drop_reason explains why it was rejected.
     Append `idstitch growth log <id> --note "…"` as you make progress so the
     next agent session doesn't repeat your work. Worklog notes are for
     work-in-progress; only DEPLOYED+VERIFIED changes become `opt log` entries.
  3. site_scan.data.report_data.site_audit.ai_citability.fixes[] is an
     ordered list of concrete AI-citability fixes (schema, fact density,
     extractability) — apply them to the site repo via git, highest impact
     first.
  4. After implementing any deliberate change, run:
     `idstitch opt log --title "…" --category <seo_snippet|content|performance|cta|attribution|other> [--urls …]`
  5. HARD RULE — log only what is LIVE: run `opt log` strictly AFTER the change
     is deployed to production AND verified there (curl the live page / check
     the live artifact). Never log planned or merged-but-not-deployed work:
     an "active" record whose change isn't live gets a false verdict when its
     review window closes, and suppression hides the still-unsolved problem
     from the daily analysis.

Agent skills: the analysis layer (two-layer model)

Raw analytics is not the product — the skills that interpret it are. The CLI bundles a base skill pack that turns pulled data into decisions:

| Skill | What it decides | |---|---| | idstitch-site-audit | Product-aware SEO/AI-citability audit → prioritized fix plan | | idstitch-competitor-review | Are tracked competitors REAL competitors? Offer-vs-offer gaps, adoptable moves | | idstitch-prompt-tuning | Are we measuring the right buyer intents? Prompt add/remove/rephrase list |

cd your-site-repo
idstitch skills install     # installs idstitch-* into ./.claude/skills

skills install also writes an AGENTS.md bridge so the pack works for any agent that reads AGENTS.md (Codex, etc.), not only Claude Code. It manages a single idempotent marker block:

<!-- idstitch:start -->
…the agent rules (pull first; don't redo active optimizations; don't re-propose
dropped growth initiatives; append growth worklog notes; opt log ONLY after
deploy + live-verify) and a skills index pointing at each ./.claude/skills/*/SKILL.md…
<!-- idstitch:end -->

The block is replaced in place on every install (created if the file is missing, appended if it exists without markers). Content outside the markers is never touched — your own AGENTS.md notes are safe.

Two layers:

• Base (idstitch-*) — shared by every tenant, shipped with the CLI, improved centrally; skills install updates them but never overwrites your local edits (use --force to accept updates over edits).
• Custom (any other name) — your project's own skills. To customize a base skill permanently, copy it under your own name (e.g. myclinic-site-audit) and edit freely; the pack will never touch it.

Commands

| Command | What | |---|---| | login <token> / whoami | Auth (config in ~/.idstitch/, or IDSTITCH_TOKEN env) | | pull [--days N] | Full bundle: traffic, audience, GA4, GSC, Clarity, AI insights, site scan, optimizations | | insights | Latest platform AI analysis (score, recommendations, critical issues) | | traffic audience ga4 gsc clarity pagespeed scan crawlers | Individual sources | | visibility | Probabilistic AI visibility: mention % with 95% CI per engine | | demand | Cached demand snapshot: Google Trends 12-mo series, rising/top related queries, People-Also-Ask (read-only; refresh is an owner action in the dashboard) | | competitors / competitors candidates | Tracked competitors with product×segment tags / citation winners + segment & demand discovery | | competitors add <domain> / competitors tag <domain> --products … --segments … | Track & curate competitors per product×segment (tags must name product-map entries) | | intent [--days N] [--limit N] | Hot leads ranked by behavioral signals — every score explained | | history [--limit N] | Cycle-over-cycle series (Clarity/GA4/GSC/PSI) + optimization markers | | opt list [--status …] | Tracked optimizations + verdicts | | opt log --title … --category … | Log a change (baseline auto, source=agent) | | growth list [--status …] | Strategic initiatives (the horizon above the loop) + linked optimizations | | growth add --title … [--goal … --target … --horizon … --priority N] | Propose an initiative (source=agent) | | growth log <id> --note … / growth done <id> / growth drop <id> --reason … | Append a worklog note / complete / abandon (reason kept, never resurfaces) | | map get / map add --name … / map add-segment --name … / map set | Read/curate the product map (manual entries survive GPT rescans) |