@usesocial/cli 0.2.6 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @usesocial/cli
 
+## 0.3.0
+
+### Minor Changes
+
+- [#10](https://github.com/usesocial/monorepo/pull/10) [`66a94e1`](https://github.com/usesocial/monorepo/commit/66a94e1196aebd9758e9e063cdbaab299db1e5cd) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - **BREAKING:** Body text is now pipe-only. The freeform body-text positional has been removed from every text-bearing write command — X `post`/`message`, LinkedIn `post`/`comment`/`message`/`message edit`, and the LinkedIn connection-request note (`requests send`). Post/comment/message body text is now read from stdin (or `--body '<json>'`); the structured target/typed-ID positionals (e.g. `message <target>`, `comment <post>`) stay on argv.
+
+  Pipe the content: `echo "..." | social x post`, `social linkedin post < file.txt`, `pbpaste | social linkedin message <target>`. A single trailing newline is trimmed; internal newlines and tabs are preserved. `--body` remains the structured escape hatch and its fields merge with the stdin text. If a command needs body text and stdin is an interactive TTY with no `--body`, it fails fast with a pipe hint instead of blocking on an interactive read. The connection-request note stays optional (omit stdin to send no note).
+
+  Schema and `--help` no longer advertise a text positional; commands that source body text from stdin are marked with `inputSource: "stdin"` in the generated schema so agents know to pipe.
+
+  Migration: replace `social x post "text"` with `echo "text" | social x post` (same for `linkedin post`, `comment`, `message`, `message edit`, and `requests send`).
+
+- [#10](https://github.com/usesocial/monorepo/pull/10) [`f4c316c`](https://github.com/usesocial/monorepo/commit/f4c316cbc9fe485162d69d459b665929a7228812) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Allow newlines and tabs in post/message body text, and accept body text piped via stdin (e.g. `pbpaste | social x post`). Identifier fields (handles, IDs, query params) still reject control characters.
+
 ## 0.2.6
 
 ### Patch Changes

package/README.md

@@ -51,11 +51,14 @@ A few of the things the command surface supports:
 ## Commands
 
 The main command surfaces print compact JSON by default. List commands commonly
-accept `--limit` and `--cursor`; time windows are command-specific. Pass `--help`
-on any subcommand for the full flag list, or run `social schema "<command path>"`
+accept `--limit` plus either `--cursor` or `--offset`; LinkedIn list reads use
+`--offset`, while LinkedIn messages and X reads use `--cursor`. Pass `--help` on
+any subcommand for the full flag list, or run `social schema "<command path>"`
 for the machine-readable contract for a runnable command. Agents planning across
 many calls can run `social schema --leaves` for a manifest of runnable commands
-keyed by command path.
+keyed by command path. For example, `social schema "linkedin requests received"`
+reports offset pagination, while `social schema "linkedin messages"` reports
+cursor pagination.
 
 Commands marked **✎ write** mutate your account and require an explicit write
 scope (see [Account safety](#account-safety)).
@@ -64,10 +67,25 @@ scope (see [Account safety](#account-safety)).
 
 Commands with `[target]` or `<target>` accept `@handle` or `@public-identifier`,
 a full X/LinkedIn URL, a LinkedIn URN, or a typed ID such as `profile_id:<id>`,
-`post_id:<id>`, `list_id:<id>`, `chat_id:<id>`, `company_id:<id>`, or `request_id:<id>`. Bare IDs are not
+`post_id:<id>`, `list_id:<id>`, `chat_id:<id>`, `conversation_id:<id>`, `company_id:<id>`, or `request_id:<id>`. Bare IDs are not
 accepted. When an optional target is omitted, the command acts on your own
 connected account.
 
+### Body text
+
+Commands that create a post, comment, message, or connection note read the body
+from **stdin** — there is no text argument. Pipe it in, or pass a raw `--body`
+JSON object:
+
+```sh
+echo "gm" | social x post
+social linkedin post < draft.md
+social linkedin requests send @handle < note.txt    # optional connection note
+```
+
+On an interactive terminal with nothing piped (and no `--body`), these commands
+fail fast rather than hang.
+
 ### Top level
 
 | Command | Description |
@@ -101,26 +119,26 @@ connected account.
 
 | Command | Description | |
 |---|---|---|
-| `post <text>` | Create a post. | ✎ write |
-| `comment <target> <text>` | Comment on a post. | ✎ write |
+| `post` | Create a post (body from stdin). | ✎ write |
+| `comment <target>` | Comment on a post (body from stdin). | ✎ write |
 | `react <target> [type=like]` | React to a post or comment. | ✎ write |
-| `requests send <target> [message]` | Send a connection request. | ✎ write |
-| `requests sent` | List pending sent connection requests; supports `--limit`, `--cursor`, `--offset`, and `-H/--header`. | |
-| `requests received` | List pending received connection requests; supports `--limit`, `--cursor`, `--offset`, and `-H/--header`. | |
+| `requests send <target>` | Send a connection request (optional note from stdin). | ✎ write |
+| `requests sent` | List pending sent connection requests; supports `--limit`, `--offset`, and `-H/--header`. | |
+| `requests received` | List pending received connection requests; supports `--limit`, `--offset`, and `-H/--header`. | |
 | `requests accept request_id:<id>` | Accept a received connection request. | ✎ write |
 | `requests cancel request_id:<id>` | Cancel a sent request or refuse a received connection request. | ✎ write |
-| `posts [target]` | List a user's or company's posts; omit the target for your own account. | |
-| `comments <target>` | List a post's comments. | |
-| `reactions <target>` | List a post's reactions. | |
+| `posts [target]` | List a user's or company's posts; supports `--limit` and `--offset`; omit the target for your own account. | |
+| `comments <target>` | List a post's comments; supports `--limit` and `--offset`. | |
+| `reactions <target>` | List a post's reactions; supports `--limit` and `--offset`. | |
 | `profile [target]` | Fetch a profile; omit the target for your own account. | |
-| `connections [target]` | List connections; omit the target for account-level connections. | |
+| `connections [target]` | List connections; supports `--limit` and `--offset`; omit the target for account-level connections. | |
 | `company <target>` | Fetch a company profile. | |
-| `jobs <target>` | List a company's job postings. | |
+| `jobs <target>` | List a company's job postings; supports `--limit` and `--offset`. | |
 | `messages` | List conversations. | |
 | `messages <target>` | Read a conversation by `chat_id:<id>`, `@handle`, `profile_id:<id>`, profile URL, or messaging-thread URL. | |
-| `message <target> <text>` | Send a message. | ✎ write |
+| `message <target>` | Send a message (body from stdin). | ✎ write |
 | `message <target> delete message_id:<id>` | Delete one of your own messages. | ✎ write |
-| `message <target> edit message_id:<id> <text>` | Edit one of your own messages. | ✎ write |
+| `message <target> edit message_id:<id>` | Edit one of your own messages (new text from stdin). | ✎ write |
 | `messages <target> mark read` | Mark a conversation read. | ✎ write |
 | `messages <target> mark unread` | Mark a conversation unread. | ✎ write |
 
@@ -128,38 +146,47 @@ connected account.
 
 | Command | Description | |
 |---|---|---|
-| `post <text>` | Create a post. | ✎ write |
+| `post` | Create a post (body from stdin). | ✎ write |
+| `delete <target>` | Delete one of your own posts. | ✎ write |
 | `repost <target>` · `unrepost <target>` | Repost or undo a repost. | ✎ write |
+| `reposters <target>` | List users who reposted a post. | |
+| `quotes <target>` | List quote posts of a post. | |
+| `replies <target>` | List replies to a post; accepts `post_id:<id>`, `conversation_id:<id>`, or a post URL. | |
 | `like <target>` · `unlike <target>` | Like or unlike a post. | ✎ write |
+| `liked [target]` | List posts a user has liked; omit the target for your own account. | |
+| `likers <target>` | List users who liked a post. | |
 | `follow <target>` · `unfollow <target>` | Follow or unfollow a user. | ✎ write |
 | `followers [target]` | List a user's followers; omit the target for your own account. | |
 | `following [target]` | List accounts a user follows; omit the target for your own account. | |
 | `tweet <target>` | Fetch a single post. | |
 | `tweets [target]` | List a user's recent posts; omit the target for your own account. | |
+| `mentions [target]` | List posts mentioning a user; omit the target for your own account. | |
 | `profile [target]` | Fetch a profile; omit the target for your own account. | |
 | `timeline` | Read the home timeline. | |
+| `bookmarks` | List your saved bookmarks. | |
 | `bookmark <target>` · `unbookmark <target>` | Add or remove a bookmark. | ✎ write |
 | `messages` | List conversations. | |
 | `messages <target>` | Read a DM conversation or participant target: chat URL, `chat_id:<id>`, `@handle`, profile URL, or `profile_id:<id>`. | |
-| `message <recipients> [text]` | Send a message to a chat URL, `chat_id:<id>`, `@handle`, profile URL, or `profile_id:<id>`; comma-separate profile targets for a group. | ✎ write |
+| `message <recipients>` | Send a DM (body from stdin) to a chat URL, `chat_id:<id>`, `@handle`, profile URL, or `profile_id:<id>`; comma-separate profile targets for a group. | ✎ write |
 
 ## Built for agents
 
 - **Everything speaks JSON.** Pipe output through `jq`, `fzf`, or your agent's
   planner — anything that reads stdin. Structured errors and predictable exit
   codes mean an agent can branch on what happened.
-- **The same patterns across networks.** `--limit`, `--cursor`, and `--account`
-  behave consistently on LinkedIn and X. Cacheable reads also list `-H/--header`
-  when proxy request headers such as `Cache-Control: no-cache` can be overridden.
+- **Schema-backed pagination.** Use `--offset` for LinkedIn list reads,
+  `--cursor` for LinkedIn messages and X reads, and `--limit` to bound pages.
+  Cacheable reads also list `-H/--header` for proxy cache headers such as
+  `Cache-Control: no-cache`.
 - **A skill you drop straight in.** Install the public skill repo with
   `npx skills add usesocial/skill`; Claude, Codex, or any other supported agent
   then knows the commands.
 
 ```sh
 # Review recent LinkedIn posts, fan out to reaction graphs, rank warm contacts.
-social linkedin posts --limit 25 > /tmp/recent-posts.json
+social linkedin posts --limit 25 --offset 0 > /tmp/recent-posts.json
 jq -r '.items[].id' /tmp/recent-posts.json \
-  | xargs -I{} social linkedin reactions post_id:{} \
+  | xargs -I{} social linkedin reactions post_id:{} --limit 100 --offset 0 \
   | jq -s '[ .[] | .items[] ]
             | group_by(.actor.id // .reactor.id // .profile_id)
             | map({person: (.[0].actor // .[0].reactor), signals: length})
@@ -214,14 +241,28 @@ social account config cache ttl 3600              # custom TTL in seconds
 ```
 
 Setting `ttl` switches the mode to `custom`. Config is stored at
-`~/.social/config.json` with mode `0600`. Use command-level
-`-H "Cache-Control: no-cache"` when a command lists `--header` in help and you
-need to bypass a cached read.
+`~/.social/config.json` with mode `0600`.
+
+Use command-level request headers to override freshness for a single read when a
+command lists `--header` in help:
+
+```sh
+social linkedin profile @handle -H "Cache-Control: no-cache"   # bypass cache read, refresh cache
+social linkedin profile @handle -H "Cache-Control: no-store"   # bypass cache read and write
+social linkedin profile @handle -H "Cache-Control: max-age=60" # override TTL for this request
+```
+
+`Cache-Control` is the functional request cache surface. Cached responses may
+preserve validators such as `ETag` and `Last-Modified` when the upstream returns
+them, but the CLI does not expose conditional revalidation semantics; use
+`Cache-Control: no-cache` when you need a fresh upstream read.
 
 Command output exposes actual per-call cost and pagination under `meta`:
 
 ```sh
-social linkedin messages --limit 20 | jq '.meta.cost'
+social linkedin reactions post_id:<post-id> --limit 100 --offset 0 \
+  | jq '{cost: .meta.cost, totalCount: .meta.totalCount}'
+social linkedin messages --limit 20 | jq '{cost: .meta.cost, cursor: .meta.cursor}'
 social x bookmarks --limit 20 | jq '{cost: .meta.cost, cursor: .meta.cursor}'
 ```
 
@@ -244,6 +285,8 @@ Built so your accounts outlive your prototype.
 ```sh
 # LinkedIn
 social linkedin profile
+social linkedin requests received --limit 25 --offset 0
+social linkedin requests sent --limit 25 --offset 0
 
 # X
 social x bookmarks --limit 50
@@ -251,6 +294,10 @@ social x followers --limit 100
 social x following profile_id:<x-user-id> --limit 100
 social x messages --limit 50
 
+# Writes (body via stdin)
+echo "gm" | social x post
+social linkedin post < draft.md
+
 # Usage / billing
 social account usage
 social account logs --limit 20 --from 2026-05-01T00:00:00Z
@@ -258,6 +305,7 @@ social account logs --limit 20 --from 2026-05-01T00:00:00Z
 # Command schema
 social schema
 social schema --leaves
+social schema "linkedin requests received"
 social schema "x post"
 ```
 

package/dist/index.d.mts

@@ -1395,6 +1395,8 @@ declare const createSocialCommand: (deps?: {
   api: KyInstance;
   parseResourceId: (name: string, value: unknown) => string;
   parseQueryString: (name: string, value: unknown) => string;
+  parseBodyText: (name: string, value: unknown) => string;
+  readStdin: () => Promise<string>;
   parseIntegerString: (name: string, value: unknown, options?: {
     min?: number;
     max?: number;