superx-cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 (2026-09-05)
+
+- Engage feeds: `engage:feeds` lists the keyword and list feeds saved in the app (with `type`, `active`, and `fetch_units`), and `engage:posts <feedId>` fetches one feed's candidate posts for review (`--account`, `--limit` 1-50, `--mode top|latest`, `--fresh`, `--include-replied`, `--exclude` comma list of post ids to page with). Read-only by design: replies are written and sent by a person in the SuperX app, so there is no reply command. `--limit` applies to keyword feeds; list feeds return one page per fetch and are paged with `--exclude`. Feed fetches have their own per-plan daily allowance and a list feed that rotates its members counts as 3
+- Inspiration search relevance: `inspiration:search` results are now relevance-ranked, strongest matches first and more loosely related posts after. BEHAVIOR CHANGE: results are no longer a fresh varied mix on every run, and weak and promotional matches are filtered out, so a page can return fewer posts than `--limit`; `has_more` no longer requires a full page, so keep paging with `--page` while it is true (pages run 1 to 7). `--sort relevant` is still the default and is the relevance-ranked order
+- Docs: write commands now describe `--account` for linked accounts (server change shipped Sep 4 2026)
+
 ## 0.2.0 (2026-08-01)
 
 - Advanced post settings: `scheduled:create`/`scheduled:update` gain `--auto-retweet <h>` / `--auto-retweet-remove <h>` (1-12), `--auto-delete <h>` / `--auto-delete-threshold <views>`, `--auto-plug <templateId>` / `--auto-plug-threshold <likes>`, `--super-followers`, plus `--no-*` disable forms; new `plug-templates:list` command. BEHAVIOR CHANGE: posts created via the API now inherit the account's Default Post Settings (auto retweet, auto delete, auto plug, auto DM, Super Followers only) when the matching flags are omitted, exactly like posts composed in the app; previously API posts got no advanced settings at all. Auto DM stays inherit-only (no flag) and surfaces `auto_dm_skipped: true` when a plan limit strips it

package/PLAYBOOK.md

@@ -45,7 +45,7 @@ Consistent, targeted interaction grows accounts faster than posting alone:
 - After a genuine back-and-forth, a soft pointer to related content on the profile is fine. Self-promo inside someone else's thread is not.
 - Budget: about 20 minutes outbound and 20 minutes inbound daily.
 
-Data: `superx contacts:list --sort engagement` identifies who already engages most (reply to them first); `superx contacts:replies <id>` shows the history with one person so replies can be specific. For the inbound block, `superx replies:received --sort recent` lists every reply the audience has sent across all posts, so nothing goes unanswered. Keep the 3-3-3 circle in a contact list (`superx lists:list`, `lists:add-member`) so the daily targets survive between sessions. If the account runs signal agents, `superx signals:leads` surfaces fresh people matching the ideal customer profile, with the post that revealed them; engage while the discovery is recent. No agent yet? `superx signals:create-agent --name ... --icp ...` sets one up from a plain-language customer description (keywords auto-suggested when omitted); leads accumulate over the following days, so create it early in the week and harvest with `signals:leads` later.
+Data: `superx contacts:list --sort engagement` identifies who already engages most (reply to them first); `superx contacts:replies <id>` shows the history with one person so replies can be specific. For the inbound block, `superx replies:received --sort recent` lists every reply the audience has sent across all posts, so nothing goes unanswered. The Engage feeds saved in the app are another source: `superx engage:feeds` lists them and `superx engage:posts <feedId>` returns the posts one surfaces, ready to score before a person writes and sends the reply in the app. Keep the 3-3-3 circle in a contact list (`superx lists:list`, `lists:add-member`) so the daily targets survive between sessions. If the account runs signal agents, `superx signals:leads` surfaces fresh people matching the ideal customer profile, with the post that revealed them; engage while the discovery is recent. No agent yet? `superx signals:create-agent --name ... --icp ...` sets one up from a plain-language customer description (keywords auto-suggested when omitted); leads accumulate over the following days, so create it early in the week and harvest with `signals:leads` later.
 
 ## 5. The research system
 

package/README.md

@@ -80,7 +80,7 @@ superx me         # Key owner, plan tier, key name and scopes
 superx accounts   # X accounts this key can read (main account first)
 ```
 
-Read commands accept `--account <id>` (an id from `superx accounts`) to select a linked or shared account. Omitting it means the main account.
+Read commands accept `--account <id>` (an id from `superx accounts`) to select a linked or shared account. Write commands accept it too for your main or linked accounts; accounts shared with you by other people are read-only (403 `writes_main_account_only`). Omitting it means the main account.
 
 ### Posts
 
@@ -124,7 +124,7 @@ superx inspiration:search "indie hackers" --sort outlier --min-likes 500
 superx inspiration:search "AI tools" --min-followers 1000 --max-followers 50000
 ```
 
-Searches a library of 50M+ real high-performing posts by topic. Options: `--sort relevant|recent|likes|reposts|impressions|outlier`, `--min-likes/--min-reposts/--min-replies/--min-bookmarks/--min-impressions`, `--min-followers/--max-followers` (author size), `--since/--until` (UTC ISO-8601), `--lang` (default en), `--exclude-topics "crypto,politics"`, `--limit` (max 50), `--page` (1-7). Each result carries an `outlier_score`: how far the post outperformed the norm for its author's follower tier. Results are intentionally varied between runs; use them for structures and hooks to remix, never to copy.
+Searches a library of 50M+ real high-performing posts by topic. Options: `--sort relevant|recent|likes|reposts|impressions|outlier`, `--min-likes/--min-reposts/--min-replies/--min-bookmarks/--min-impressions`, `--min-followers/--max-followers` (author size), `--since/--until` (UTC ISO-8601), `--lang` (default en), `--exclude-topics "crypto,politics"`, `--limit` (max 50), `--page` (1-7). Each result carries an `outlier_score`: how far the post outperformed the norm for its author's follower tier. Results are relevance-ranked, strongest matches first, with weak and promotional matches filtered out, so a page may return fewer than `--limit` posts. Use them for structures and hooks to remix, never to copy.
 
 ### Contacts (who engages with you)
 
@@ -142,7 +142,24 @@ superx lists:add-member <list-id> --handle levelsio  # or --x-user-id 44196397
 superx lists:remove-member <list-id> <member-id>
 ```
 
-Lists are the saved people-collections from the SuperX app. System lists (Followers, Following, Repliers, Reposters) appear in `lists:list` but are read-only and their members are not available through the API (400 `system_list_not_supported`). Adding someone already in a list is harmless: the API returns the existing member with `"duplicate": true` and writes nothing. Member writes are main account only.
+Lists are the saved people-collections from the SuperX app. System lists (Followers, Following, Repliers, Reposters) appear in `lists:list` but are read-only and their members are not available through the API (400 `system_list_not_supported`). Adding someone already in a list is harmless: the API returns the existing member with `"duplicate": true` and writes nothing. Member writes work on your main or linked accounts with `--account`; shared accounts are read-only.
+
+### Engage (feed posts to reply to)
+
+```bash
+superx engage:feeds                                  # the feeds saved in the app's Engage tab
+superx engage:posts <feed-id> --limit 50             # one big page of candidate posts
+superx engage:posts <feed-id> --mode latest --fresh true
+superx engage:posts <feed-id> --exclude 1234567890,1234567891   # next batch, minus what you have
+```
+
+Engage feeds are the keyword and list feeds set up in the SuperX app. `engage:feeds` returns each feed's `id`, `name`, `type` (`keywords`, `list`, or `x_list`), `active` flag, and `fetch_units` (what one fetch of it costs: 1 for a keyword feed, at most 3 for list feeds, and an imported X list charges 1 at fetch time). Feeds are created and edited in the app, not through the API.
+
+`engage:posts <feed-id>` returns candidate posts with text, author (handle, bio, follower counts), engagement metrics, and post time, plus `has_more` and the `feed` it came from. Results are for review: replies are written and sent by a person in SuperX, so there is no reply command. Sending replies that read as inauthentic can get an X account suspended under X's inauthentic-behavior rules and a SuperX account terminated; AI output must be reviewed and meaningfully edited by a person before it is posted, and reply activity is logged and may be audited.
+
+`--limit` (1-50, default 20) applies to keyword feeds. List feeds ignore it upstream and return one page per fetch, about 10 posts for a member list and 20 to 25 for an imported X list, with `--limit` only trimming that page; page those with `--exclude` instead. On a keyword feed a 50-post page costs the same as a 20-post page, so ask for 50 a few times a day and filter locally rather than polling. Feeds refresh over hours, so fetching more often than hourly returns the same posts. `--mode top|latest` defaults to `top`; `--fresh true` skips the cache; `--include-replied true` keeps posts already replied to, skipped, or blocked and flags them with `replied`. `--exclude` takes up to 100 post ids and is how you page.
+
+Feed fetches have their own per-plan daily allowance (Trial 20, Pro 60, Advanced 120, Ultra 300 per day), separate from the read budget; per minute: trial 2, pro 5, advanced 10, ultra 15. A list feed that rotates its members counts as up to 3 fetches, every other feed as 1; `engage:feeds` never touches the allowance. Over the cap you get 429 `rate_limited`: the API returns `remaining_day`; the CLI prints the message and the retry delay. Fetches also run a few at a time across all API users, so a 429 with a retry delay can mean busy rather than out of allowance; wait and retry. Posts a fetch returns count as seen and are demoted in later fetches, in the app as well as the API. An unknown feed id returns 404 `feed_not_found`.
 
 ### Signals (automated lead finding)
 
@@ -152,7 +169,7 @@ superx signals:leads --limit 20                      # newest leads across all a
 superx signals:leads --agent 3 --deposited false     # new leads from one agent
 superx signals:leads --since "2026-07-01T00:00:00Z"  # leads discovered since July
 
-# Create an agent (main account only, write scope)
+# Create an agent (write scope; main or linked account via --account)
 superx signals:create-agent \
   --name "Build in public founders" \
   --icp "Indie founders building SaaS in public, sharing MRR and launches" \
@@ -218,7 +235,7 @@ superx scheduled:update <post-id> --clear-tags --clear-title --clear-scratchpad
 
 A new `--at` time alone never schedules a draft; pass `--status scheduled` explicitly. CAUTION: replacement text is a full replace, media included. `--text` without `--media` removes any images the post carried; re-list the current `object_key`s (visible in `scheduled:list`) to keep them. Title, scratchpad, tag, and time edits never touch media.
 
-Write constraints in the current API version: main account only; images via `media:upload` (no video); one of `--text`, `--part`, or `--parts-json`. Idempotent replays add `"replayed": true` to the output. Note that drafts have no scheduled time, so `--from/--to` filters exclude them.
+Write constraints in the current API version: main or linked accounts via `--account` (shared accounts are read-only; tags are workspace-wide and main account only); images via `media:upload` (no video); one of `--text`, `--part`, or `--parts-json`. Idempotent replays add `"replayed": true` to the output. Note that drafts have no scheduled time, so `--from/--to` filters exclude them.
 
 ### Advanced settings
 
@@ -380,6 +397,8 @@ The CLI talks to these SuperX API endpoints (base `https://api.superx.so/v1`):
 | `/signals/agents/:id` | PATCH | `signals:pause-agent <id>` / `signals:resume-agent <id>` |
 | `/signals/agents/:id` | DELETE | `signals:delete-agent <id>` |
 | `/signals/leads` | GET | `signals:leads` |
+| `/engage/feeds` | GET | `engage:feeds` |
+| `/engage/feeds/:id/posts` | GET | `engage:posts <feedId>` |
 | `/media` | POST | `media:upload <file>` |
 | `/scheduled-posts` | GET | `scheduled:list` |
 | `/scheduled-posts` | POST | `scheduled:create` |
@@ -476,6 +495,7 @@ src/
     ├── contacts.ts   # contacts:list / contacts:replies
     ├── lists.ts      # lists:list / lists:members / lists:add-member / lists:remove-member
     ├── signals.ts    # signals:agents / signals:leads / signals:create-agent / signals:pause-agent / signals:resume-agent / signals:delete-agent
+    ├── engage.ts     # engage:feeds / engage:posts
     ├── media.ts      # media:upload
     ├── scheduled.ts  # scheduled:list / scheduled:create / scheduled:update / scheduled:delete
     ├── tags.ts       # tags:list / tags:create / tags:update / tags:delete
@@ -513,18 +533,20 @@ superx lists:list
 superx lists:members <list-id> --q "founder"
 superx signals:agents
 superx signals:leads --agent 3 --deposited false
+superx engage:feeds
+superx engage:posts <feed-id> --limit 50
 
-# Contact list writes (main account)
+# Contact list writes (main or linked account)
 superx lists:add-member <list-id> --handle levelsio
 superx lists:remove-member <list-id> <member-id>
 
-# Signal agent writes (main account)
+# Signal agent writes (main or linked account)
 superx signals:create-agent --name "..." --icp "..." --keyword "..."
 superx signals:pause-agent <id>
 superx signals:resume-agent <id>
 superx signals:delete-agent <id>
 
-# Writes (main account)
+# Writes (main or linked account via --account)
 superx scheduled:create --text "Post"                                # Draft
 superx scheduled:create --text "Post" --at "2026-08-01T15:00:00Z"    # Scheduled
 superx scheduled:create --part "1/" --part "2/" --at "..."           # Thread

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: superx
-description: SuperX is a Twitter/X growth tool. Use it to read an account's published posts with engagement metrics, pull account analytics (impressions, likes, replies, follower change), find the people who engage with the account most, review reply history in both directions (sent and received), manage contact lists, create and manage signal agents (automated lead finders) and review the leads they discover, search a library of 50M+ high-performing posts for inspiration, create, edit, tag, or schedule draft posts and threads (with image attachments), write, schedule, publish, and generate AI covers for long-form X Articles, and read or update the account's Context settings (profile description, interests, SuperX rules, reply settings, favorite creators, style guide, products) that steer SuperX's AI writing, all through the SuperX API.
+description: SuperX is a Twitter/X growth tool. Use it to read an account's published posts with engagement metrics, pull account analytics (impressions, likes, replies, follower change), find the people who engage with the account most, review reply history in both directions (sent and received), manage contact lists, create and manage signal agents (automated lead finders) and review the leads they discover, search a library of 50M+ high-performing posts for inspiration, read the Engage feed posts a saved feed surfaces for review, create, edit, tag, or schedule draft posts and threads (with image attachments), write, schedule, publish, and generate AI covers for long-form X Articles, and read or update the account's Context settings (profile description, interests, SuperX rules, reply settings, favorite creators, style guide, products) that steer SuperX's AI writing, all through the SuperX API.
 homepage: https://docs.superx.so
 metadata: {"openclaw":{"emoji":"🚀","requires":{"bins":["superx"],"env":[]}}}
 ---
@@ -32,7 +32,7 @@ official website: https://superx.so
 
 **Rule 2: Read PLAYBOOK.md before creating any content.** This repo ships a growth strategy guide (`PLAYBOOK.md`, also inside the installed npm package). It tells you WHAT to post, WHEN, and WHY: the action hierarchy, out-of-network discovery, the engagement loop, and the failure modes that kill reach. The CLI gives you data and actions; the playbook gives you judgment. Do not schedule content without it.
 
-**Rule 3: Know the write constraints.** `scheduled:create` without `--at` creates a DRAFT (nothing publishes). With `--at` it schedules for that time. `scheduled:update` changes only the flags you pass, and a new `--at` alone never schedules a draft; add `--status scheduled` to promote. Writes work on the main account only. Images attach via `media:upload` then `--media` (JPG/PNG/WEBP up to 5MB, GIF up to 15MB; max 4 images or 1 GIF per post); video is not supported. Timestamps MUST be UTC ISO-8601 with an explicit `Z` or offset; naive timestamps are rejected with 400. `articles:publish` posts a long-form article to X IMMEDIATELY and irreversibly; treat it like hitting Publish in public and get human confirmation unless the user already gave it.
+**Rule 3: Know the write constraints.** `scheduled:create` without `--at` creates a DRAFT (nothing publishes). With `--at` it schedules for that time. `scheduled:update` changes only the flags you pass, and a new `--at` alone never schedules a draft; add `--status scheduled` to promote. Writes work on your main account or any linked account (pass the same `--account` you used to read it); accounts shared with you by other people are read-only, and tags are workspace-wide. Images attach via `media:upload` then `--media` (JPG/PNG/WEBP up to 5MB, GIF up to 15MB; max 4 images or 1 GIF per post); video is not supported. Timestamps MUST be UTC ISO-8601 with an explicit `Z` or offset; naive timestamps are rejected with 400. `articles:publish` posts a long-form article to X IMMEDIATELY and irreversibly; treat it like hitting Publish in public and get human confirmation unless the user already gave it.
 
 ---
 
@@ -133,7 +133,7 @@ superx inspiration:search "AI tools" --min-likes 500 --min-followers 1000 --max-
 - Searches a library of 50M+ real high-performing posts. Use results for structures, hooks, and angles to remix. Never copy them.
 - Flags: `--sort relevant|recent|likes|reposts|impressions|outlier`, `--min-likes/--min-reposts/--min-replies/--min-bookmarks/--min-impressions`, `--min-followers/--max-followers` (author size), `--since/--until`, `--lang` (default en), `--exclude-topics "crypto,politics"`, `--limit` (max 50), `--page` (1-7).
 - `outlier_score` on each result = how far the post outperformed the norm for its author's follower tier. Sorting by `outlier` surfaces content that won on substance, not audience size.
-- Results are intentionally varied between runs; re-running the same query returns a different mix.
+- Results are relevance-ranked, strongest matches first. Weak and promotional matches are filtered out, so a page may return fewer than `--limit` posts.
 
 ### Contacts (who engages with you)
 
@@ -157,7 +157,25 @@ superx lists:remove-member <list-id> <member-id>     # member-id from lists:memb
 - Lists are the saved people-collections from the SuperX app. Use them to track prospects, customers, or people worth engaging.
 - System lists (Followers, Following, Repliers, Reposters) appear in `lists:list` with `is_system: true` but are read-only and their members are NOT available through the API.
 - Adding someone already in a list is harmless: the existing member returns with `"duplicate": true` and nothing changes.
-- Member writes are main account only and need a key with the write scope.
+- Member writes work on your main or linked accounts (`--account`) and need a key with the write scope; shared accounts are read-only.
+
+### Engage (feed posts to reply to)
+
+```bash
+superx engage:feeds                                  # feeds saved in the app, with type and fetch cost
+superx engage:posts <feed-id> --limit 50             # one big page of candidate posts
+superx engage:posts <feed-id> --mode latest --fresh true         # newest, skipping the cache
+superx engage:posts <feed-id> --exclude 1234567890,1234567891    # next batch, minus what you have
+superx engage:posts <feed-id> --include-replied true             # keep posts already replied to
+```
+
+- Engage feeds are the keyword and list feeds the user set up in the app's Engage tab. `engage:feeds` gives each feed's `id`, `name`, `type` (`keywords`, `list`, `x_list`), `active`, and `fetch_units`. Feeds are created and edited in the app; the API only reads them.
+- `engage:posts` returns candidate posts (text, author handle/bio/follower counts, engagement metrics, post time) plus `has_more` and the `feed`. Score and shortlist them for the user.
+- READ-ONLY BY DESIGN: there is no reply command. Replies are written and sent by a person in SuperX. Sending replies that read as inauthentic can get an X account suspended and a SuperX account terminated; AI output must be reviewed and meaningfully edited by a person before it is posted. Surface candidates and draft suggestions for the user; never claim a reply was sent.
+- `--limit` (1-50, default 20) applies to KEYWORD feeds. List feeds return one page per fetch (about 10 posts for a member list, 20 to 25 for an imported X list) and `--limit` only trims it. Page a list feed with `--exclude` (at most 100 ids per call; window the list to the most recent ids), not a bigger `--limit`.
+- A 50-post page on a keyword feed costs the same as a 20-post page: ask for `--limit 50` a few times a day and filter locally. Feeds refresh over hours, so polling more often than hourly returns the same posts.
+- Each plan has a daily feed-fetch allowance (Trial 20, Pro 60, Advanced 120, Ultra 300), separate from the read budget; per minute: trial 2, pro 5, advanced 10, ultra 15. A list feed that rotates its members counts as 3 fetches. `engage:feeds` never spends it. Over the cap you get 429 `rate_limited`: the API returns `remaining_day`; the CLI prints the message and the retry delay.
+- Posts a fetch returns count as seen and get demoted in later fetches, in the app as well as here. An unknown feed id returns 404 `feed_not_found`.
 
 ### Signals (automated lead finding)
 
@@ -167,7 +185,7 @@ superx signals:leads --limit 20                      # newest leads across all a
 superx signals:leads --agent 3 --deposited false     # one agent's leads not yet in its list
 superx signals:leads --since "2026-07-01T00:00:00Z"  # leads discovered since July
 
-# Create an agent (main account only, write scope)
+# Create an agent (write scope; main or linked account via --account)
 superx signals:create-agent \
   --name "Build in public founders" \
   --icp "Indie founders building SaaS in public, sharing MRR and launches" \
@@ -471,6 +489,7 @@ superx scheduled:list --status scheduled
 26. **`context:set` list flags REPLACE the stored list**: `--interests` and `--favorite-creators` overwrite what is there; include every value the user should keep. `""` on a string flag clears it (style-guide overrides then revert to the generated guide). These settings steer all future AI output; confirm with the user before changing them.
 27. **`queue:set --slots-json` REPLACES the whole schedule** and re-flows queued posts onto the new slots. Read the current slots with `queue:get` first and send the full set. `'[]'` clears every slot and leaves the queue all-custom. `reflow.bailed: true` means the settings saved but no post moved.
 28. **`editor_restricted` (403)**: the account is shared with the key owner with Editor permission. Editors can change queue settings but not context settings. Only the account owner can.
+29. **`engage:posts --limit` is keyword-feeds only**: list feeds return one page of about 10 to 25 posts per fetch, so page them with `--exclude` (the ids you already have, at most 100 per call), not a bigger `--limit`. Each plan also has a daily feed-fetch allowance (separate from reads) and a list feed that rotates its members counts as 3 fetches, so fetch big pages a few times a day rather than polling. Posts a fetch returns count as seen and are demoted in later fetches, in the app as well as here.
 
 ---
 
@@ -501,18 +520,20 @@ superx lists:list
 superx lists:members <list-id> --q "founder"
 superx signals:agents
 superx signals:leads --agent 3 --deposited false
+superx engage:feeds
+superx engage:posts <feed-id> --limit 50
 
-# Contact list writes (main account only)
+# Contact list writes (main or linked account)
 superx lists:add-member <list-id> --handle levelsio
 superx lists:remove-member <list-id> <member-id>
 
-# Signal agent writes (main account only)
+# Signal agent writes (main or linked account)
 superx signals:create-agent --name "..." --icp "..." --keyword "..."   # Lead finder
 superx signals:pause-agent <id>
 superx signals:resume-agent <id>
 superx signals:delete-agent <id>
 
-# Writes (main account only)
+# Writes (main or linked account via --account)
 superx scheduled:create --text "Post"                                  # Draft
 superx scheduled:create --text "Post" --at "2026-08-01T15:00:00Z"      # Scheduled
 superx scheduled:create --part "1/" --part "2/" --at "..."             # Thread

package/dist/index.js

@@ -184,6 +184,13 @@ var SuperXAPI = class {
   async deleteSignalAgent(id) {
     return (await this.request(`/signals/agents/${id}`, { method: "DELETE" })).json;
   }
+  // --- Engage ---
+  async listEngageFeeds(query = {}) {
+    return (await this.request("/engage/feeds", { query })).json;
+  }
+  async getEngageFeedPosts(feedId, query = {}) {
+    return (await this.request(`/engage/feeds/${encodeURIComponent(feedId)}/posts`, { query })).json;
+  }
   // --- Scheduled posts ---
   async listScheduled(query = {}) {
     return (await this.request("/scheduled-posts", { query })).json;
@@ -600,6 +607,26 @@ async function signalsDeleteAgent(argv) {
   printJson(await api.deleteSignalAgent(argv.id));
 }
 
+// src/commands/engage.ts
+async function engageFeeds(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(await api.listEngageFeeds({ account_id: argv.account }));
+}
+async function engagePosts(argv) {
+  const api = new SuperXAPI(getConfig());
+  printJson(
+    await api.getEngageFeedPosts(argv.feedId, {
+      account_id: argv.account,
+      limit: argv.limit,
+      mode: argv.mode,
+      // yargs boolean: pass through only when the flag was given.
+      fresh: argv.fresh === void 0 ? void 0 : String(argv.fresh),
+      include_replied: argv.includeReplied === void 0 ? void 0 : String(argv.includeReplied),
+      exclude_post_ids: argv.exclude
+    })
+  );
+}
+
 // src/commands/scheduled.ts
 async function scheduledList(argv) {
   const api = new SuperXAPI(getConfig());
@@ -1372,6 +1399,32 @@ var advancedSettingsOptions = (y) => y.option("auto-retweet", {
   "Delete a signal agent (its saved leads and contact list stay untouched)",
   (y) => y.positional("id", { describe: "Agent id (from signals:agents)", type: "number" }),
   run(signalsDeleteAgent)
+).command(
+  "engage:feeds",
+  "List the Engage feeds set up in the app",
+  (y) => accountOption(y).example("$0 engage:feeds", "Feed ids, types, and what one fetch costs").example("$0 engage:feeds --account <account-id>", "Feeds saved on a linked account"),
+  run(engageFeeds)
+).command(
+  "engage:posts <feedId>",
+  "Fetch the posts an Engage feed surfaces (for review; replies are sent by a person in the app)",
+  (y) => accountOption(y).positional("feedId", { describe: "Feed id (from engage:feeds)", type: "string" }).option("limit", {
+    describe: "Posts to return, 1-50 (default 20). Applies to keyword feeds; list feeds return one page (about 10 to 25 posts) and --limit only trims it",
+    type: "number"
+  }).option("mode", {
+    describe: "top = highest-signal posts first (default); latest = newest first",
+    type: "string",
+    choices: ["top", "latest"]
+  }).option("fresh", {
+    describe: "true = skip the cache and fetch new posts; false = allow cached posts (default)",
+    type: "boolean"
+  }).option("include-replied", {
+    describe: "true = keep posts already replied to, skipped, or blocked and flag them with `replied`; false = leave them out (default)",
+    type: "boolean"
+  }).option("exclude", {
+    describe: "Comma list of post ids to leave out (max 100); this is how you page: pass the ids you already have to get the next batch",
+    type: "string"
+  }).example("$0 engage:posts <feed-id> --limit 50", "One big page from a keyword feed").example("$0 engage:posts <feed-id> --mode latest --fresh true", "Newest posts, skipping the cache").example("$0 engage:posts <feed-id> --exclude 1234567890,1234567891", "Next batch, minus the posts you have"),
+  run(engagePosts)
 ).command(
   "scheduled:list",
   "List drafts and the scheduled queue",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superx-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SuperX CLI - command line interface to the SuperX API for Twitter/X growth: read posts and analytics, find engaged contacts, and schedule posts and threads",
   "main": "dist/index.js",
   "bin": {