Foglift
Integration · Command-Line Interface
Foglift CLI
The official Foglift command-line tool. Run SEO, GEO, AEO, and AI Visibility scans from a terminal or CI pipeline with one command. Free without an account, MIT-licensed, and published on npm as foglift-scan.
TL;DR
- What it is:
foglift-scanon npm — an official CLI published by Foglift, version 1.0.1, twelve commands. - Who it’s for: Engineers who script, CI/CD pipelines that gate on quality, and SEO teams who’d rather diff a JSON file than click through a dashboard.
- Why it matters: As of April 2026, Foglift is the only AI search optimization platform shipping a first-party CLI. Every other tool in the category requires you to wrap their REST API yourself.
- Cost: The package is free and MIT-licensed. Public scans need no account; AI Visibility and batch commands consume tokens from your Foglift quota, free plan included.
Why a CLI?
Most AEO and GEO tools live entirely inside a dashboard. That’s fine for the first scan but it doesn’t scale: every iteration on a pricing page or a comparison table means a screenshot, a paste into Slack, a tab switch, a re-scan, another paste. The dashboard hop is the slow path.
A CLI collapses the loop. foglift scan takes one URL and returns a structured score; --threshold=85 turns the score into a build gate; --json pipes into jq, gh, or any shell tool you already use. The same workflow that makes Lighthouse CI a default in performance work — drop a CLI invocation into your pipeline, fail the build when scores drop — applies one-to-one to AEO regressions.
The cost of not having a CLI is concrete. AEO scores drift the same way performance scores drift: someone adds a third-party script, a refactor strips a heading hierarchy, a CMS migration breaks an FAQ schema block. Without a CLI, the regression is invisible until the next dashboard check, which is usually after the deploy. With a CLI in CI, the merge is blocked before the regression ships.
The twelve commands
Every command targets one Foglift API surface. The first three work without an API key; the remaining nine require FOGLIFT_API_KEY.
foglift scan <url>Single-URL audit. Returns SEO, GEO, AEO, performance, security, accessibility scores. No auth required for public scans.
--jsonOutput any scan or query as machine-readable JSON on stdout. Pipes into jq, gh, slack-cli, etc.
--threshold=NExit non-zero when overall score falls below N. CI/CD gating without writing a wrapper script.
foglift scan batch <urls...>Up to 10 URLs in one request. Useful for competitor sweeps and homepage-plus-pricing audits.
foglift scan ai-checkQuery ChatGPT, Claude, Perplexity, Gemini, and Google AI Overview with a prompt; return per-engine citation status, sentiment, and source list.
foglift scan resultsPull historical AI Visibility results, filterable by --days, --model, and --prompt. The trend is what tells you whether a fix worked.
foglift scan prompts list/add/removeManage tracked prompts from the terminal. Pin a query the moment you ship a release.
foglift scan modelsShow which AI engines are enabled and the current monitoring frequency.
foglift scan sentimentSentiment trend on AI mentions — positive, neutral, negative — over a configurable window.
foglift scan usageCurrent account quota: scans, AI Visibility checks, tokens remaining, plan tier.
foglift scan history <url>Per-URL score history. Surface regressions across deploys without opening the dashboard.
FOGLIFT_API_KEYSet via env var (sk_fog_...). Read automatically by every authenticated command. Set FOGLIFT_BASE_URL to override the API host (typically only useful in self-hosted setups).
Setup
1. Install (or skip and use npx)
# Global install npm install -g foglift-scan # Or run any command on demand without installing npx foglift-scan https://example.com
2. Run your first scan (no auth required)
foglift scan https://example.com # Machine-readable output foglift scan https://example.com --json # Fail the shell when overall score < 85 foglift scan https://example.com --threshold=85
3. Generate an API key for the authenticated commands
Sign up at foglift.io, then Dashboard → Settings → API Keys. Free plan is fine; the key is prefixed sk_fog_. Export it and the CLI picks it up automatically:
export FOGLIFT_API_KEY="sk_fog_..." # Now batch, AI Visibility, history, prompts, models, sentiment all work foglift scan batch https://foglift.io https://stripe.com https://ramp.com foglift scan ai-check --prompt "best AEO tool" --models chatgpt,perplexity --domain foglift.io foglift scan results --days 30 --model chatgpt --json
Three terminal workflows worth automating
CI/CD: gate the deploy on AEO score
Drop the CLI into a pipeline step after the preview deploy. The job fails when scores regress; the merge is blocked until the regression is fixed.
# .github/workflows/aeo-gate.yml
name: AEO gate
on: pull_request
jobs:
aeo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Wait for preview deploy
run: ./scripts/await-preview.sh
- name: Foglift AEO scan
env:
FOGLIFT_API_KEY: ${{ secrets.FOGLIFT_API_KEY }}
run: npx foglift-scan "${PREVIEW_URL}" --threshold=85
- name: Archive scan JSON
if: always()
run: npx foglift-scan "${PREVIEW_URL}" --json > scan.json
- uses: actions/upload-artifact@v4
with:
name: foglift-scan
path: scan.jsonThe first invocation gates; the second archives. Two CLI calls, no wrapper script. The same shape works in GitLab CI, CircleCI, and Buildkite — the CLI relies only on standard Unix exit codes.
Headless competitor sweep
Run a batch of competitors in one command and pipe to jq for a leaderboard. Useful for weekly category reports and pre-launch positioning checks.
foglift scan batch \
https://foglift.io \
https://tryprofound.com \
https://peec.ai \
https://otterly.ai \
--json \
| jq '[.results[] | {url, aeo: .aeoScore, geo: .geoScore}] | sort_by(.aeo) | reverse'AI Visibility delta after a content change
After shipping a fix, re-check whether ChatGPT or Perplexity actually started citing the page. The ai-check command queries the engines live; results pulls the trend over a window.
# Live check on a single prompt
foglift scan ai-check \
--prompt "best tool to track AI search visibility" \
--models chatgpt,perplexity,claude,gemini \
--domain foglift.io
# Trend over the last 30 days for a specific model
foglift scan results --days 30 --model chatgpt --json \
| jq '[.[] | {date, citationRate}] | sort_by(.date)'The CI/CD pattern: gate, capture, comment
The CLI’s value is highest when it lives in a pipeline. The minimal-but-complete recipe has three steps that each map to a single CLI invocation:
1. Gate
Run
foglift scan <url> --threshold=Nafter the preview deploy. Non-zero exit fails the job. Choose a threshold that reflects the floor you’re willing to ship at — most teams start at 80 and tighten over time.“npx foglift-scan https://staging.example.com --threshold=85”
2. Capture
Run a second invocation with
--jsonand redirect to a build artifact. This persists the structured result for audit, comment-rendering, or downstream steps without re-running the scan.“npx foglift-scan https://staging.example.com --json > scan.json”
3. Comment
Pipe the JSON through
jqinto a markdown table and post on the PR viagh pr comment. Reviewers see the AEO breakdown in-line with the diff, so a structural regression is part of the review conversation, not a separate dashboard.“cat scan.json | jq -r ‘.aeoBreakdown | to_entries | .[] | “| \(.key) | \(.value) |”’ | gh pr comment $PR_NUMBER --body-file -”
Why this pattern compounds: tight feedback loops are the dominant productivity factor in iterative software work — documented across decades of empirical research, from Knight & Leveson on rapid prototyping (1990) through Lighthouse CI, which has shipped the same gate-capture-comment shape since 2019. Performance regressed quietly until Lighthouse CI made it a required check; AEO regresses the same way until a CLI gate makes it visible. The tooling is the difference; the loop is the same.
Foglift CLI vs. other AI search optimization tools
CLI parity across the AI search optimization category as of April 2026:
| Tool | First-party CLI on npm | CI threshold flag | REST API | Notes |
|---|---|---|---|---|
| Foglift | Yes — foglift-scan v1.0.1 | Yes — --threshold | Yes, free tier | Only first-party CLI in the category |
| Profound | No | No | Yes (enterprise, demo-gated) | REST exists; no CLI; users wrap it themselves |
| Peec.ai | No | No | Yes | No public CLI as of April 2026 |
| AthenaHQ | No | No | Limited | Dashboard-driven workflow |
| Otterly.ai | No | No | Limited (Looker Studio connector) | CSV/dashboard exports primary |
| Semrush AI Toolkit | No | No | Yes (paid, separate per-credit plan) | Large API, no AI-search-specific CLI |
| Ahrefs Brand Radar | No | No | Yes (paid) | No first-party CLI for the Brand Radar surface |
| Lighthouse CI | Yes (different scope) | Yes — --budget-path | N/A (runs in-process) | Performance/SEO; doesn’t score AEO or AI Visibility |
See the broader AI search tool landscape in our Best AI Search Tools with MCP Integration 2026 and Best GEO Tools for Developers breakdowns.
Frequently asked questions
What is the Foglift CLI?
The Foglift CLI is an official, first-party command-line tool published as the npm package foglift-scan. It wraps the Foglift REST API in a typed terminal binary with colored output, --json export for scripting, and a --threshold flag designed to fail CI/CD builds when SEO, GEO, or AEO scores drop below a target. Twelve commands cover single-URL scanning, batch scans across up to ten URLs, AI Visibility checks across the major AI engines, historical results, prompt and model management, sentiment trends, account usage, and per-URL scan history.
How do I install the Foglift CLI?
Install globally with `npm install -g foglift-scan`, then run `foglift scan https://example.com`. Alternatively, invoke any command without installing via `npx foglift-scan ...`. Either path resolves the same binary. The CLI requires Node.js 18 or newer and runs on macOS, Linux, and Windows.
Do I need an API key to use the Foglift CLI?
No. Public scans — `foglift scan https://example.com` — work with no account and no API key. The authenticated commands (batch scan, AI Visibility check, historical results, prompts, models, sentiment, usage, scan history) require a free API key prefixed `sk_fog_`, generated at foglift.io/dashboard/settings and exported as the FOGLIFT_API_KEY environment variable. Free-plan keys include monthly quotas; paid plans (Launch $49, Growth $129, Enterprise $299) raise them.
How does the Foglift CLI compare to Lighthouse CI?
Lighthouse CI scores performance, accessibility, best practices, and SEO from a headless Chrome run inside the build environment. The Foglift CLI scores SEO, GEO, AEO, performance, security, and accessibility from a hosted scanner that fetches the public URL, parses the rendered HTML, and applies the same eight-dimension AEO rubric the Foglift dashboard uses (Structured Data Richness, Heading Clarity, FAQ Quality, Entity Identity, Content Depth, Citation Formatting, Topical Authority, AI Crawler Access). Both tools support a --threshold-equivalent flag for CI gates. Lighthouse focuses on what the page does in a browser; Foglift focuses on what AI engines and search crawlers can extract from it.
Which AI search optimization platforms ship a first-party CLI?
As of April 2026, Foglift is the only AI search optimization platform that publishes a first-party command-line tool on npm. Profound, Peec.ai, AthenaHQ, Otterly.ai, and Rankability ship REST APIs but no maintained CLI. Semrush and Ahrefs expose large APIs but no AI-search-specific CLI; community wrappers exist but are not vendor-supported. The CLI gap mirrors the MCP gap — none of the major competitors expose their AEO data as a callable command-line surface.
Can I use the CLI in GitHub Actions?
Yes. The CLI is designed for CI/CD. A typical GitHub Actions step runs `- run: npx foglift-scan https://${{ env.PREVIEW_URL }} --threshold=85` after a preview deploy. The CLI exits non-zero when the overall score is below the threshold, blocking the merge. For richer output, run a second step with `--json > scan.json` and post the result as a PR comment via gh CLI or actions/github-script. All authenticated commands read FOGLIFT_API_KEY from the runner environment, so storing the key as a GitHub Actions secret is the typical pattern.
What is the difference between the Foglift CLI and the Foglift MCP server?
The CLI (foglift-scan on npm) is built for humans running terminal commands and for shell scripts in CI/CD. It has colored output, progress hints, a --threshold flag, and JSON mode for piping. The MCP server (foglift-mcp on npm) is built for AI agents — Claude Code, Cursor, Windsurf — and speaks the JSON-RPC Model Context Protocol so the agent can call typed tools without a shell. Both wrap the same Foglift REST API; the difference is the calling pattern. Many teams install both: CLI for build gates and headless scripts, MCP for in-editor agent loops.
How does the --threshold flag work?
Pass `--threshold=85` (or any integer 0–100) to the scan command. The CLI runs the scan as normal, prints the human or JSON output, and then exits with code 0 if the overall score is greater than or equal to the threshold and code 1 otherwise. The exit code is the only difference; nothing else about the output changes. This matches the convention used by linters, test runners, and Lighthouse CI, so any CI step that already understands non-zero exit codes will fail the build automatically.
Can I pipe the CLI output into jq?
Yes. Pass `--json` to any scan command and the output is a single JSON document on stdout, with no ANSI escape codes or progress chatter. Common pipelines: `foglift scan example.com --json | jq '.aeoBreakdown'` to extract just the AEO dimension scores; `foglift scan ai-check --prompt 'best AEO tool' --models chatgpt --json | jq '.results[].mention'` to check whether a specific prompt cited the brand; `foglift scan results --days 30 --json | jq '[.[] | .citationRate] | add / length'` to compute a 30-day citation-rate average. The shape is documented in the README on npm.
Is the Foglift CLI open source?
Yes. foglift-scan is published under the MIT license. The package is downloadable from npm and the bin entries (`foglift` and `foglift-scan`) are interchangeable aliases for the same TypeScript-compiled binary. The README on the npm page lists the full command surface and environment variables. Tool calls consume tokens from your Foglift account quota; the CLI itself is free.
Why does the CLI matter for AEO and AI search optimization?
Iterative improvement requires a fast feedback loop. Dashboard hops kill the loop — every screenshot, copy-paste, and tab switch slows the change-and-verify cycle that actually moves AEO scores. A CLI collapses one cycle into a single command, makes scans automatable in CI/CD, and pipes structured data into the rest of a developer's tooling (jq, gh, slack-cli, custom shell scripts). The same loop logic that makes Lighthouse CI valuable for performance regressions makes the Foglift CLI valuable for AEO regressions: you catch the drop in the build, not the next time someone notices a competitor cited instead of you.
What's the minimum viable CI recipe?
The smallest useful pipeline step is one line: `- run: npx foglift-scan https://${{ env.PREVIEW_URL }} --threshold=85`. Place it after the preview deploy step and mark the job as a required check on protected branches. No API key needed for the basic scan. To extend: add a second step with `--json > scan.json` for archival, and a third step that posts the result as a PR comment via `gh pr comment $PR_NUMBER --body "$(cat scan.json | jq ...)"`. The recipe is identical across GitHub Actions, GitLab CI, and CircleCI because the CLI relies only on standard Unix exit codes and stdout.
Sources & data freshness
All competitor parity claims verified against vendor public pages or public npm registries on 2026-05-02. CLI version pinned to the latest published release.
- Foglift. foglift-scan on npm — package, version 1.0.1, license, README. Accessed 2026-05-02.
- Google Chrome. Lighthouse CI — gate-capture-comment pattern reference. Accessed 2026-05-02.
- Knight, J. C., & Leveson, N. G. (1990). An experimental evaluation of the assumption of independence in multiversion programming — feedback-loop research foundation.
- Aggarwal et al. Agentic refactoring loops at KDD 2024 — empirical productivity gains from collapsing manual cycles into agent loops.
- npm registry searches for
foglift-scan,profound-cli,peec-cli,otterly-cli,athena-cli,semrush-ai-cli,ahrefs-brand-radar-cli— none of the non-Foglift packages exist on the public registry as of 2026-05-02. - Foglift. /pricing — plan tier and free-key availability self-verification.
Related
- Foglift MCP Server — same Foglift API, exposed to Claude Code, Cursor, and Windsurf as agent-native tools.
- All Foglift integrations — REST API, MCP, Slack, Discord, webhooks, Zapier, n8n, GitHub Actions.
- Developer documentation — REST API reference and full CLI command surface.
- Best GEO Tools for Developers 2026 — how every AI search tool stacks up on developer ergonomics.
- What is Foglift? — canonical platform overview.
Try the CLI now — no install required
npx foglift-scan https://your-site.com. No account, no auth, no signup. The AI Visibility commands need a free key from the dashboard.