CLI & agent skill

The superx CLI is a thin client for the SuperX API: every command maps to a /v1 endpoint and prints clean JSON. It doubles as the tool the superx-agent skill teaches AI agents to use.

Install

npm install -g superx-cli

Requires Node.js 18 or newer. The package is superx-cli; the installed binary is superx.

Log in

Create an API key in the SuperX app at app.superx.so/account?tab=api, then:

superx login

This prints the key page URL, prompts you to paste the key, validates it against the API, and saves it to ~/.superx/credentials.json (file mode 0600). Use superx login --key "sxk_..." for a non-interactive login, superx status to verify, and superx logout to remove the stored key.

Authentication for CI and agents

Set an environment variable instead of logging in:

export SUPERX_API_KEY=sxk_...

The credentials file takes priority over the environment variable when both exist. To point the CLI at a different API host, set SUPERX_API_URL to a full base URL including the path (default: https://api.superx.so/v1).

Commands

Command	Description
`superx login`	Authenticate with a SuperX API key (guided paste or `--key`)
`superx logout`	Remove stored credentials (`~/.superx/credentials.json`)
`superx status`	Check authentication, plan, and current rate-limit state
`superx me`	Show the key owner, plan, and API key details
`superx accounts`	List the X accounts this key can read (main account first)
`superx posts:list`	List published posts with engagement metrics
`superx posts:analytics`	Account analytics: totals, daily series, follower change (default: last 30 days)
`superx replies:list`	List replies the account has sent (newest first)
`superx replies:received`	List replies the audience has sent the account across all its posts
`superx inspiration:search <query>`	Search a library of 50M+ high-performing posts for inspiration
`superx contacts:list`	List the people who engage with you most
`superx contacts:replies <id>`	List a contact’s replies to you (their id from `contacts:list`)
`superx lists:list`	List your contact lists (system lists are read-only)
`superx lists:members <id>`	List the members of a contact list you created (`--q` filters)
`superx lists:add-member <id>`	Add a person to a contact list (`--handle` or `--x-user-id`)
`superx lists:remove-member <id> <memberId>`	Remove a member from a contact list
`superx signals:agents`	List your signal agents (automated lead finders) with their watched signals
`superx signals:leads`	List the leads your signal agents have found (`--agent`, `--deposited`, `--since`/`--until` filters)
`superx signals:create-agent`	Create a signal agent (`--name`, `--icp` required; repeat `--keyword` for 1-5 watches or omit to auto-suggest; `--list-id` or omit to auto-create a list)
`superx signals:pause-agent <id>`	Pause a signal agent (it stops finding leads until resumed)
`superx signals:resume-agent <id>`	Resume a paused signal agent
`superx signals:delete-agent <id>`	Delete a signal agent (its saved leads and contact list stay untouched)
`superx media:upload <file>`	Upload a local image (JPG, PNG, WEBP, GIF) and print its `object_key` for `--media`
`superx scheduled:list`	List drafts and the scheduled queue (`--tags` filters by tag ids)
`superx scheduled:create`	Create a draft (no `--at`) or scheduled post; repeat `--part` for a thread; `--media`/`--alt-text` attach images; `--title`, `--scratchpad`, `--tag` add organizer fields; advanced settings via `--auto-retweet`, `--auto-delete`, `--auto-plug`, `--super-followers`
`superx scheduled:update <id>`	Edit a draft or scheduled post; only the flags you pass change (`--status scheduled` promotes; text replacement without `--media` removes the post’s images; `--no-auto-retweet` and friends remove advanced settings)
`superx scheduled:delete <id>`	Delete a draft or scheduled post by id
`superx plug-templates:list`	List your auto-plug reply templates (id, text, has_media) for `--auto-plug`
`superx context:get`	Show the account’s Context settings: profile description, interests, rules, reply settings, favorite creators, style guide, products
`superx context:set`	Edit Context settings; only the flags you pass change (`""` clears a string; `--interests`/`--favorite-creators` comma lists fully replace)
`superx context:products`	List the account’s products (used for product mentions in generated content)
`superx context:products:set`	Add or edit one product by `--url` (creates it when new, cap 5) or `--id`
`superx context:products:delete <id>`	Remove a product by id (reversible by re-adding the same url)
`superx queue:get`	Show the account’s posting schedule: predefined time slots and the timezone they run in
`superx queue:set`	Change the posting schedule (`--slots-json` full replace, 0 = Sunday, `'[]'` clears; `--timezone` IANA name); changing the slots re-flows queued posts onto them
`superx tags:list`	List your tags (id, name, color)
`superx tags:create <name>`	Create a tag (`--color` picks a palette color, default blue)
`superx tags:update <id>`	Rename and/or recolor a tag
`superx tags:delete <id>`	Delete a tag (it is removed from every post that carries it)
`superx articles:list`	List long-form X Articles (`--status` filters)
`superx articles:get <id>`	Get one article with its body as markdown
`superx articles:create`	Create an article draft; body via `--content`, `--file`, or piped stdin (markdown)
`superx articles:update <id>`	Edit an article’s title, body, or cover; only the flags you pass change
`superx articles:delete <id>`	Delete an article (scheduled articles refund their quota)
`superx articles:schedule <id>`	Schedule or reschedule an article (`--at`, more than 2 minutes ahead)
`superx articles:unschedule <id>`	Pull a scheduled article back to draft (quota refunds)
`superx articles:publish <id>`	Publish an article to X now (irreversible; needs X Premium)
`superx articles:cover <id>`	Generate an AI cover from the title (60-100s, spends AI credits; `--no-attach` to skip attaching)
`superx docs`	Print the SuperX API quickstart (markdown, no auth needed)

Flags mirror the API’s query parameters: --account, --limit, --page, --since/--until, --sort, --type, --status, --from/--to. Run any command with --help for its full flag list and examples. Note that drafts have no scheduled time, so --from/--to filters on scheduled:list exclude drafts; use --status draft to list them. To post an image: superx media:upload ./chart.png prints an object_key, then superx scheduled:create --text "..." --media "<object_key>" --alt-text "..." attaches it (comma-list up to 4 image keys, or exactly 1 GIF). For threads with media, pass the full parts array as JSON via --parts-json. Images are capped at 5MB (GIF 15MB) and 100 uploads per day. Advanced settings on scheduled:create: flags you omit inherit your Default Post Settings from the SuperX app. Exactly five settings inherit this way (auto retweet, auto delete, auto plug, auto DM, Super Followers only); other composer defaults such as Bluesky cross-posting or share-with-followers are never applied to API posts. --auto-retweet <hours> (1-12, plus --auto-retweet-remove <hours>), --auto-delete <hours> (1-12, plus --auto-delete-threshold <views>, default 1000), --auto-plug <templateId> with --auto-plug-threshold <likes> (template ids from plug-templates:list), and --super-followers set explicit values; the --no-* forms (--no-auto-retweet, --no-auto-delete, --no-auto-plug, --no-super-followers) turn a setting off for that post. On scheduled:update there is no inheritance: flags you pass override, omitted flags keep the post’s current settings, and --no-* removes them. Auto DM always follows your app defaults; if a plan limit strips it at create time, the response carries auto_dm_skipped: true. Article bodies are markdown in both directions: headings, lists, blockquotes, bold/italic/strikethrough, links, images by URL, and bare X post URLs as embeds. Constructs the X Articles format cannot express (code blocks, horizontal rules) degrade to plain text and are reported in a warnings array. Context settings (context:get / context:set) are the background SuperX’s AI uses when writing for the account: the profile description grounds the voice, --interests drive content suggestions, --rules are mandatory instructions on every AI surface, --reply-rules and --reply-author-name steer generated replies, --favorite-creators (max 3) inspire the style, and --style-audience/--style-vocabulary outrank the app’s generated style guide until cleared with "". Boolean flags support --no-* negation. Caps: 500 characters for the profile description, rules, and reply rules; 600 for the style audience; 1000 for the style vocabulary; 30 interests; 3 creators; 5 products.

JSON output

stdout is clean JSON for every command except superx docs (markdown), so output pipes straight into jq:

superx posts:list --sort likes --limit 5 | jq '.data[].text'

Human and status messages go to stderr. Exit code is 0 on success, 1 on error.

Agent skill

The superx-agent repo packages the CLI as a skill for Claude Code and compatible agent tools:

npx skills add superx-so/superx-agent

The skill teaches the agent the full workflow (check auth, read analytics and contacts, create drafts, verify) and ships with PLAYBOOK.md, a distilled SuperX growth strategy the agent follows when deciding what and when to post.

Getting Started

Using the API

CLI & Agents

Updates

CLI & agent skill

Install

Log in

Authentication for CI and agents

Commands

JSON output

Agent skill

​Install

​Log in

​Authentication for CI and agents

​Commands

​JSON output

​Agent skill

Install

Log in

Authentication for CI and agents

Commands

JSON output

Agent skill