CLI

Install PageSeeds Operator

Get the CLI, run free desk reports against your site, then activate a license when you're ready to research, write, fix, and merge.

Step 1

Install

Run the install script. Prebuilt binary is macOS Apple Silicon only today. Other platforms: set FROM_SOURCE=1 or see the CLI docs.

curl -fsSL https://raw.githubusercontent.com/fstrauf/pageseeds-app/main/scripts/install-cli.sh | bash
  • Installs to ~/.local/bin/pageseeds-cli
  • Ensure PATH includes ~/.local/bin:
export PATH="$HOME/.local/bin:$PATH"

Verify:

pageseeds-cli --help

Step 2

Setup once in your site

From your content site repo, run setup once. It links the project, writes local defaults, and runs a free desk first-win (site-overview) unless you skip it.

cd /path/to/your-site
pageseeds-cli setup --path . --yes

Optional license at setup time:

pageseeds-cli setup --path . --yes --license <key>

After setup, desk tools resolve the project from cwd — no -i / -p needed for the happy path:

pageseeds-cli site-overview

Connect Search Console with browser consent. First set a Google Cloud Desktop OAuth client id (redirect http://127.0.0.1:8085) in secrets:

# ~/.config/automation/secrets.env GSC_OAUTH_CLIENT_ID=your-desktop-client-id.apps.googleusercontent.com
pageseeds-cli gsc-connect

That saves an OAuth refresh token to ~/.config/automation/secrets.env. Other secrets (Ahrefs, DataForSEO, etc.) stay BYO in the same file or project .env — never in product source. Advanced: a service-account JSON path still works via GSC_SERVICE_ACCOUNT_PATH.

Step 3

Free desk reports

Free forever: see what is going on without a license. Useful reads:

pageseeds-cli site-overview
pageseeds-cli articles -m 100 -l 20
pageseeds-cli list-projects

Free path works without a license. Paid commands print a clear buy link if unlicensed.

Step 4

Activate license (when ready)

Your license key is on the purchase success page and in your email. Activate later if you skipped it at setup:

pageseeds-cli license activate <key>
pageseeds-cli license status

License check runs offline: paid tools require an activated key. The CLI verifies it locally — no account, no phone-home. Without a key, free desk reports keep working.

Step 5

SEO run

With a license, run the SEO pass: it plans a worklist from your Search Console data (new pages, merges, noindex for dead weight), your agent works each row, and one pull request lands in the repo. Full workflow lives in the app repo — we link out rather than rehost it.

CLI getting startedSEO run skill
Troubleshooting
Common blockers when the CLI is quiet or errors early.
  • command not found — add ~/.local/bin to PATH and open a new shell.
  • No project context — run pageseeds-cli setup --path . --yes from your site repo (or pass -i / -p to override).
  • License required — paid tools need an activated key (license activate / license status). Free desk tools work without one.
  • GSC not connected — set GSC_OAUTH_CLIENT_ID (desktop client, redirect http://127.0.0.1:8085) then run pageseeds-cli gsc-connect. Service account path remains an advanced option.
CLI releases on GitHubBack to homepage