AI Search Visibility CLI

Run a public audit in one command

This command is the fastest proof that the package works. It needs Node.js 18 or newer and no API key. Add --json for machine-readable output or --threshold=85 to fail a CI job below your floor.

npx foglift-scan scan https://example.com --json --threshold=85

Tracked capability prompt: AI search visibility CLI

Why a CLI?

Most AI search optimization 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 applies one-to-one to AI Readiness regressions: drop a CLI invocation into your pipeline and fail the build when scores drop.

The cost of not having a CLI is concrete. AI Readiness 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 CLI command surface

The single-page Technical Audit works without an API key. Batch, AI Visibility, stored-result, prompt, model, sentiment, referral, usage, history, and recipe commands require FOGLIFT_API_KEY from a Launch or higher workspace.

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 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 a Launch or higher API key

Sign up at foglift.io, then Dashboard → Developer. Developer access starts on Launch. The key is prefixed sk_fog_. Export it and the CLI picks it up automatically:

export FOGLIFT_API_KEY="sk_fog_..."

# Now authenticated CLI commands can use the selected workspace
foglift scan batch https://foglift.io https://stripe.com https://ramp.com
foglift scan ai-check --prompt "AI search visibility CLI" --models chatgpt --domain foglift.io
foglift scan results --days 30 --model chatgpt --json

4. Multi-brand accounts: pick the brand per command

If your account tracks more than one brand, every authenticated command needs to know which brand to act on. Without a selector the CLI exits with Multiple brands exist for this API key. Pass --brand-id with the brand UUID from Dashboard → Developer → Your brands, or use --domain to select by the brand's domain. Single-brand accounts can skip this; the CLI resolves the only brand automatically.

# Select by brand UUID (canonical)
foglift scan results --days 30 --brand-id 11111111-2222-4333-8444-555555555555

# Or select by domain
foglift scan ai-check --prompt "best AI search visibility tool" --domain yourbrand.com

Pricing and limits

Authenticated CLI access starts at $49/mo

The npm package and public one-page audit are free. A Launch or higher workspace is required for API-key commands. API requests and model tokens are separate: an authenticated CLI call counts against the request allowance, while each live prompt-engine check also uses the workspace's model-token balance.

Free workspaces keep unlimited single-page Technical Audits and active-use weekly Perplexity monitoring in the product. Developer access begins on Launch. See the complete plan comparison.

Three terminal workflows worth automating

CI/CD: gate the deploy on AI Readiness 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: AI Readiness 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 AI Readiness scan
        env:
          FOGLIFT_API_KEY: ${{ secrets.FOGLIFT_API_KEY }}
        run: npx foglift-scan scan "${PREVIEW_URL}" --threshold=85
      - name: Archive scan JSON
        if: always()
        run: npx foglift-scan scan "${PREVIEW_URL}" --json > scan.json
      - uses: actions/upload-artifact@v4
        with:
          name: foglift-scan
          path: scan.json

The first invocation gates; the second archives. Two CLI calls, no wrapper script. The same shape works in GitLab CI, CircleCI, and Buildkite because 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, aiReadiness: (.aiReadinessScore // .aeoScore)}] | sort_by(.aiReadiness) | 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:

This pattern makes a structural regression visible during code review, before it reaches production. It follows the same gate-and-artifact convention used by Lighthouse CI. The two tools measure different things, but both expose a score to a standard CI process with a failing exit code.

Why the first-party support boundary matters

An API can be called from a shell, but that does not make it a maintained CLI. Foglift publishes the client, command names, JSON output, exit behavior, workspace selectors, and automation recipes together. Version 1.0.3 is the current npm release.

For direct HTTP contracts, use the AI Visibility API reference. For agent-native workflows, use the MCP server.

Frequently asked questions

Sources & data freshness

Foglift re-verified the npm package, product plan contract, and public CLI source on 2026-10-09.

1. Foglift. foglift-scan on npm . Package version 1.0.3, MIT license, and current README. Re-verified 2026-10-09.
2. Google Chrome. Lighthouse CI . CI score gates, uploaded artifacts, and pull-request reporting reference. Accessed 2026-10-09.
3. Foglift. /pricing . Current developer-access, pricing, and API allowance contract.