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

Weekly operator

With a license, run the bounded weekly pass: read the desk, pick up to five actions under your program mode, ship research / write / fix / merge into the repo, get the report. Full workflow lives in the app repo — we link out rather than rehost it.

CLI getting startedWeekly SEO 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