@jorgemenadev/superaseo

Token-authed CLI for SuperaSEO. It lets an AI agent configure publishing webhooks, trigger test/publish events, read/mark articles, audit and prune the keyword universe and content calendar, and drive article generation for a workspace — everything the dashboard does for publishing and content planning, but from a terminal and without a browser session.

Every command talks to the SuperaSEO Convex HTTP API (/cli/*) and prints a JSON envelope on stdout. Errors go to stderr as { ok: false, error } and the process exits with a stable, non-zero code.

Install

npm i -g @jorgemenadev/superaseo
# or run without installing:
npx @jorgemenadev/superaseo --help

Supported platforms: darwin-arm64, linux-x64, linux-arm64.

Authentication

1. In the dashboard, open Settings → MCP ("API keys para agentes") and create a key. Copy the sk_live_… secret — it is shown only once.
2. Hand the key to the agent and log in:

superaseo login sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

login verifies the key with a cheap authenticated read before saving it to ~/.config/superaseo/config.json (or $XDG_CONFIG_HOME/superaseo/config.json), chmod 600.

You can skip the config file entirely with environment variables:

| Variable | Purpose | | ------------------- | -------------------------------------------------------------------- | | SUPERASEO_API_KEY | Workspace API key. Wins over the config file. | | SUPERASEO_CLI_URL | Convex site URL to target. Defaults to production; wins over config. |

Every command is scoped to the workspace the key belongs to.

Agent quickstart

export SUPERASEO_API_KEY=sk_live_...
superaseo projects list                                   # discover slugs
superaseo integrations set-webhook \
  --project acme --name "Acme blog" \
  --endpoint https://acme.com/api/superaseo-webhook \
  --access-token whsec_...
superaseo integrations test --project acme                # verify credentials
superaseo articles list --project acme --status ready_to_publish
superaseo articles publish --project acme --article-id <id>

Command reference

JSON output is the default for every command.

| Command | Description | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | superaseo login <sk_live_...> | Verify and persist a workspace API key. | | superaseo whoami | Confirm the active key and show the target base URL + project count. | | superaseo projects list | List the workspace's projects. | | superaseo integrations get --project <slug> | Show the project's publishing integration status (never the token). | | superaseo integrations set-webhook --project <slug> --name <name> --endpoint <url> [--access-token <token>] | Create/update the publishing webhook (HTTPS + SSRF validated). | | superaseo integrations delete-webhook --project <slug> | Clear the publishing webhook config. | | superaseo integrations test --project <slug> | Send a test payload to the configured webhook. | | superaseo articles list --project <slug> [--status] [--locale] [--limit] [--cursor] | List articles (cursor-paginated). | | superaseo articles get --project <slug> --locale <locale> --slug <slug> | Fetch one article, including markdown. | | superaseo articles publish --project <slug> --article-id <id> | Publish a ready_to_publish article via the webhook. | | superaseo articles mark-published --project <slug> --article-id <id> --published-url <url> [--commit-sha] [--dry-run] | Reconcile an article as published. Use --dry-run first. | | superaseo keywords list --project <slug> [--tier p1\|p2\|p3] [--status <s>] | List the keyword universe with tier/status counts in meta. | | superaseo keywords skip --project <slug> --keyword-id <id> | Mark a keyword skipped (sugar over set-status). | | superaseo keywords requeue --project <slug> --keyword-id <id> | Mark a keyword queued (sugar over set-status). | | superaseo calendar list --project <slug> [--status <s>] [--lane es\|en] | List content-plan rows with any linked article's slug/status. | | superaseo calendar reschedule --project <slug> --plan-id <id> --date <YYYY-MM-DD> | Move a plan row to a new date (converted to UTC-midnight ms). | | superaseo calendar remove --project <slug> --plan-id <id> [--no-requeue] | Delete a plan row; requeues its keyword unless --no-requeue. | | superaseo generate start --project <slug> [--lane <lane>] [--plan-id <id>] | Start generation (next due, or a specific plan row). Returns workflowId. | | superaseo generate status --project <slug> --workflow-id <id> | Report a generation's status, article, and condensed QA report. |

--access-token is required when first configuring an endpoint or when the endpoint changes; the stored token is never returned by any command.

The keyword CLI can only move a keyword to queued or skipped; the scheduled, in_progress, and published states are engine-managed. calendar remove requeues the keyword (back to queued) unless it is already published; pass --no-requeue to delete the row without touching the keyword.

Run superaseo --help for full usage, or scope help to a command group, e.g. superaseo integrations --help.

Exit codes

| Code | Meaning | | ---- | ------------------------------------------------ | | 0 | Success | | 64 | Usage / bad request (BAD_REQUEST) | | 77 | Authentication failed (UNAUTHORIZED) | | 78 | Not found (NOT_FOUND) | | 69 | Network error reaching the API (NETWORK_ERROR) | | 1 | Internal / unexpected error (INTERNAL) |

HTTP contract

See packages/backend/docs/cli.md for the full /cli/* route contract and auth model.