Command line
Every tool from a terminal or a CI job, with stable exit codes.
The seolyticize command calls any tool from a terminal or a script. It reads the tool list from discovery when it runs, so a tool added to the platform today is a command today, without a new release. It is built on the TypeScript SDK, and waits out rate limits the same way.
Log in
# Piped, so the key never lands in shell history:
printf '%s' "$KEY" | seolyticize login
# Or interactively (the key is not echoed):
seolyticize loginThe key is checked against the API before it is stored, in ~/.config/seolyticize/config.json (or $XDG_CONFIG_HOME/seolyticize/config.json), with permissions 0600 on the file and 0700 on its directory.
SEOLYTICIZE_API_KEY and SEOLYTICIZE_BASE_URL override the stored values, which is how CI should provide them.
seolyticize whoami # role, reach (agency-wide or one client), tool count
seolyticize logoutCall tools
seolyticize tools # what this key may call
seolyticize describe get_top_searches # a tool's options
seolyticize call get_top_searches --market=uk --since=2026-09-01 --limit=20
seolyticize get_top_searches --market=uk --since=2026-09-01 # same, without "call"Input can also come as JSON, inline, from a file, or from stdin; options apply on top:
seolyticize call get_keyword_gap --input '{"clientId":"<clientId>","competitorDomains":["a.com"]}'
seolyticize call get_keyword_gap --file gap.json
cat gap.json | seolyticize call get_keyword_gap --file -Options are typed from the tool's schema: numbers and booleans are converted, arrays take repeated options or commas (--domains=a.com,b.com), objects take JSON, null is null where the schema allows it, and --client-id is accepted for clientId.
Shortcuts
seolyticize clients # list_clients
seolyticize rank <trackerId> --client <id> # get_rank_summary
seolyticize alerts --client <id> [--since 2026-10-01T00:00:00Z] # last 7 days by defaultOnboard and verify a site from its repo
seolyticize init --domain example.com --framework nextjs [--dry-run] [--force] [--dir .] [--public public]
seolyticize verify --site example.com # or --client <id>init calls onboard_site and writes what it returns: the IndexNow and verification files under public/, the robots source, and for Next.js app/seolyticize.tsx (the <Analytics> component and its CSP origins) and app/sitemap.ts. Files already there are kept unless --force.
verify runs verify_site and prints one line per item not done, with its code, detail and next call. It exits 10 when an item failed, so a CI step can stop on it; seolyticize-verify in @seolyticize/next uses the same code.
Environment variables for a deploy
seolyticize env --client <id> [--format dotenv|coolify|vercel|k8s]
COOLIFY_TOKEN=… seolyticize env --client <id> --push coolify --coolify-url https://coolify.example --coolify-app <application uuid> [--force]env prints every variable a client's site reads, each with its scope, what reads it, and whether env can supply its value:
Variable | Scope | Read by | Value from |
|---|---|---|---|
| run |
| yes |
| build |
| yes, once |
| run |
| yes, once |
| run |
| yes |
| run | the post-deploy command, with | only for a signed hook ( |
| secret |
| no |
| secret | the post-deploy command | no |
| secret |
| no |
The hook's url holds only its public id, so a call to it also needs the secret, sent as Authorization: Bearer or used to sign the body. A hook made before signed calls (signing.hookSecret: false) is usually wired up with the webhookUrl that holds its secret in the path, which cannot be read back, so env leaves SEOLYTICIZE_DEPLOY_HOOK_URL out for it and says why: call rotate_deploy_hook once, set the new url and secret, and env gives the URL from then on (see the deploy hook).
Secrets are shown once when they are issued and cannot be read back, so they are printed commented out with the call that issues or replaces them (issue_server_collect_key, rotate_deploy_hook, create_api_key). --format coolify prints the body for Coolify's PATCH /api/v1/applications/{uuid}/envs/bulk; vercel prints vercel env add lines; k8s a ConfigMap and a Secret with the secrets left commented.
--push coolify reads the application's variables through Coolify's API first (GET /api/v1/applications/{uuid}/envs, preview variables ignored), with the token from COOLIFY_TOKEN (never a flag, never printed). It prints one line per variable, its name and new, unchanged, changed or hidden (a value Coolify locked with "shown once", which cannot be compared), never a value. New names are added. A changed or hidden one is left as it is and the command exits 7, unless you pass --force to replace it. Nothing is ever deleted, and secrets are never pushed: a placeholder would overwrite a working value. Coolify's API documents no request field for build-time, so check that NEXT_PUBLIC_SEOLYTICIZE_SITE_KEY is available at build in the application's settings. After rotating the server key, list_collect_keys {clientId} shows each key's lastUsedAt: the rotation is done when the new key's moves and the revoked key's stops.
Output
Human-readable tables by default. Scripts should pass --json, which prints the tool's result exactly as the API returned it under data:
seolyticize clients --json | jq -r '.clients[].id'Errors go to stderr; results go to stdout.
Exit codes
Stable, so scripts can branch on them:
Code | Meaning |
|---|---|
0 | success |
1 | unexpected error |
2 | usage error (bad command, option or JSON) |
3 | authentication failed (missing, unknown, revoked) |
4 | not permitted (role or client scope) |
5 | not found (no such tool for this key) |
6 | invalid input (did not match the tool's schema) |
7 | refused (a well-formed request the product declined) |
8 | rate limited (after the SDK's retries) |
9 | server error or network failure |
10 |
|
MCP over stdio
Some MCP clients only launch a local command. seolyticize mcp relays the hosted MCP server over stdin and stdout with your key, so those clients get the same tools as everyone else:
{
"mcpServers": {
"seolyticize": {
"command": "seolyticize",
"args": ["mcp", "--group", "onboarding"],
"env": { "SEOLYTICIZE_API_KEY": "sk_seo_…" }
}
}
}--group (onboarding, weekly, technical, research, reporting) lists only that job's tools. Clients that speak HTTP should connect to https://seolyticize.com/api/mcp directly.