> ## Documentation Index > Fetch the complete documentation index at: https://docs.superx.so/llms.txt > Use this file to discover all available pages before exploring further. # CLI & agent skill > Use the SuperX API from your terminal with the superx CLI, or hand it to an AI agent with the superx-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 ```bash theme={null} 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](https://app.superx.so/account?tab=api), then: ```bash theme={null} 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: ```bash theme={null} 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 ` | Search a library of 50M+ high-performing posts for inspiration | | `superx contacts:list` | List the people who engage with you most | | `superx contacts:replies ` | 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 ` | List the members of a contact list you created (`--q` filters) | | `superx lists:add-member ` | Add a person to a contact list (`--handle` or `--x-user-id`) | | `superx lists:remove-member ` | 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 ` | Pause a signal agent (it stops finding leads until resumed) | | `superx signals:resume-agent ` | Resume a paused signal agent | | `superx signals:delete-agent ` | Delete a signal agent (its saved leads and contact list stay untouched) | | `superx media:upload ` | 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 ` | 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 ` | 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 ` | 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 ` | Create a tag (`--color` picks a palette color, default blue) | | `superx tags:update ` | Rename and/or recolor a tag | | `superx tags:delete ` | 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 ` | 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 ` | Edit an article's title, body, or cover; only the flags you pass change | | `superx articles:delete ` | Delete an article (scheduled articles refund their quota) | | `superx articles:schedule ` | Schedule or reschedule an article (`--at`, more than 2 minutes ahead) | | `superx articles:unschedule ` | Pull a scheduled article back to draft (quota refunds) | | `superx articles:publish ` | Publish an article to X now (irreversible; needs X Premium) | | `superx articles:cover ` | 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 "" --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 ` (1-12, plus `--auto-retweet-remove `), `--auto-delete ` (1-12, plus `--auto-delete-threshold `, default 1000), `--auto-plug ` with `--auto-plug-threshold ` (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`: ```bash theme={null} 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](https://github.com/superx-so/superx-agent) repo packages the CLI as a skill for Claude Code and compatible agent tools: ```bash theme={null} 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.