@usesocial/cli 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +25 -1
  2. package/README.md +166 -186
  3. package/dist/index.mjs +12409 -12616
  4. package/dist/index.mjs.map +1 -1
  5. package/package.json +1 -1
  6. package/dist/index.d.mts +0 -1498
package/CHANGELOG.md CHANGED
@@ -1,12 +1,36 @@
1
1
  # @usesocial/cli
2
2
 
3
+ ## 0.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#31](https://github.com/usesocial/monorepo/pull/31) [`dcda1ff`](https://github.com/usesocial/monorepo/commit/dcda1ff2af6fbc3595c1978dd528213ef4897c8e) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Split own-data reads from live network reads. Own-account collections now flow
8
+ through explicit `sync` plus free read-only `sql` envelopes; named read commands
9
+ are live and metered, with target-required post/tweet reads and write-only
10
+ message/request routers where applicable.
11
+
12
+ ### Patch Changes
13
+
14
+ - [#31](https://github.com/usesocial/monorepo/pull/31) [`eb53c2c`](https://github.com/usesocial/monorepo/commit/eb53c2cca95f2c708d9c8b8b920fc5b8ab080e2c) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Add cache migrations for the latest synced read schema, including LinkedIn
15
+ headline columns and removed X edit-control fields. Cache opens can now report
16
+ applied migrations so callers can surface migration notices without guessing.
17
+
18
+ - [#31](https://github.com/usesocial/monorepo/pull/31) [`a885c61`](https://github.com/usesocial/monorepo/commit/a885c619b6c67b1317d3e17d8fceb3e49e48795f) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Remove `--credits` from `social x sync` and `social linkedin sync`. Sync now
19
+ walks until the provider completes, reaches a stored checkpoint, or hits
20
+ `--since`; JSON summaries keep actual `creditsSpent` telemetry without exposing
21
+ estimate, cap, `credit-limit`, or `partial` fields.
22
+
23
+ LinkedIn sync also uses offset pagination for full account-level walks where the
24
+ provider exposes totals, and bills first-party sync reads such as connections,
25
+ request lists, chats, messages, own profile, and own posts as `owned_read`.
26
+
3
27
  ## 0.6.0
4
28
 
5
29
  ### Minor Changes
6
30
 
7
31
  - [#30](https://github.com/usesocial/monorepo/pull/30) [`7aefe83`](https://github.com/usesocial/monorepo/commit/7aefe83f716321d7fa10d52be67cb6f96b5474f0) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Per-collection sync with a confirm-by-credits gate, a local profiles mirror, and cache-first enriched reads.
8
32
 
9
- - `social x|linkedin sync <collection>` gates spend with a single `--credits {N}` flag that is both the consent and the hard cap; bare invocations auto-run cheap syncs (≤ $5) or print a credit estimate and stop. Replaces `--billing-limit`/`--yes`/the TTY prompt, and `sync` is now a visible command.
33
+ - `social x|linkedin sync <collection>` walks until provider completion, a stored checkpoint, or `--since`; `--credits` is no longer supported, and sync JSON reports actual `creditsSpent` without estimate, cap, `credit-limit`, or `partial` fields.
10
34
  - New `x_messages` DM collection (flat `/dm_events`) and a DM `includes.users` profile extractor. Syncs mirror participant profiles into the local cache (`x_profiles`/`li_profiles`) with a COALESCE merge so thin sources never clobber richer rows; the server `profiles` corpus merges the same way.
11
35
  - `x followers|following|messages` and `linkedin connections|messages|requests` now read from the local cache, enriched with the profiles mirror. They require a first sync; `followers`/`following`/`connections` then auto-refresh only when older than 15 minutes, while `messages` and `requests sent|received` refresh on every read so they always return the latest.
12
36
 
package/README.md CHANGED
@@ -8,14 +8,14 @@
8
8
  <h1 align="center">@usesocial/cli</h1>
9
9
 
10
10
  **LinkedIn & X CLI.** One install, one login, and your agent can run
11
- distribution work across X and LinkedIn — outreach, posting, audience insights,
12
- and the follow-up loops between them — from any shell.
11
+ distribution work across X and LinkedIn: outreach, posting, audience insights,
12
+ and the follow-up loops between them from any shell.
13
13
 
14
- `social` is built for people who live in a terminal with an agent open and are on
15
- the hook for their own distribution. The work you keep meaning to do — see who
16
- engaged, find the people worth reaching out to, learn from those who post better,
17
- keep the funnel warm — becomes something you can hand to the agent you already
18
- trust with your code.
14
+ `social` is built for people who live in a terminal with an agent open and are
15
+ on the hook for their own distribution. The work you keep meaning to do - see
16
+ who engaged, find the people worth reaching out to, learn from those who post
17
+ better, keep the funnel warm - becomes something you can hand to the agent you
18
+ already trust with your code.
19
19
 
20
20
  Published as `@usesocial/cli` on npm; the binary is `social`.
21
21
 
@@ -28,165 +28,166 @@ curl -fsSL https://usesocial.dev/install.sh | bash
28
28
  ## Quickstart
29
29
 
30
30
  ```sh
31
- social account login # device sign-in, choose scope, set up billing
32
- social account connect linkedin # connect a LinkedIn account
31
+ social account login
32
+ social account connect linkedin
33
33
  social linkedin profile
34
- social account connect x # connect an X account
34
+ social account connect x
35
35
  social x profile
36
36
  ```
37
37
 
38
38
  ## What you can hand your agent
39
39
 
40
- Ask in plain language; the agent runs the calls and you stay the decision-maker.
41
- A few of the things the command surface supports:
42
-
43
40
  | You ask | The agent reaches for |
44
- |---|---|
45
- | "Surface the ten connections worth reaching out to this week." | `linkedin connections`, `x tweets` |
46
- | "Pull everyone who reacted to my last LinkedIn post and flag the warm leads." | `linkedin reactions`, `linkedin profile` |
47
- | "Read this creator's recent posts and break down what makes them land." | `linkedin posts`, `x tweets` |
48
- | "Find what people are saying about AI agents this week and summarize the themes." | `linkedin posts`, `x timeline` |
41
+ | --- | --- |
42
+ | "Surface the ten warm contacts worth reaching out to this week." | `linkedin search people`, `linkedin reactions`, `linkedin sql` |
43
+ | "Pull everyone who reacted to my last LinkedIn post and flag the warm leads." | `linkedin posts <target>`, `linkedin reactions`, `linkedin profile` |
44
+ | "Read this creator's recent posts and break down what makes them land." | `linkedin posts <target>`, `x tweets <target>` |
45
+ | "Find what people are saying about AI agents this week and summarize the themes." | `linkedin search posts`, `x timeline` |
46
+ | "Triage my inbox and draft replies for approval." | `sync messages`, `sql`, `linkedin message`, `x message` |
49
47
  | "Draft a reply to this thread and post it once I approve." | `linkedin comment`, `x post` |
50
48
 
51
49
  ## Commands
52
50
 
53
- The main command surfaces print compact JSON by default. List commands commonly
54
- accept `--limit` plus either `--cursor` or `--offset`; LinkedIn list reads use
55
- `--offset`, while LinkedIn messages and X reads use `--cursor`. Pass `--help` on
56
- any subcommand for the full flag list, or run `social schema "<command path>"`
57
- for the machine-readable contract for a runnable command. Agents planning across
58
- many calls can run `social schema --leaves` for a manifest of runnable commands
59
- keyed by command path. For example, `social schema "linkedin requests received"`
60
- reports offset pagination, while `social schema "linkedin messages"` reports
61
- cursor pagination.
51
+ The CLI prints compact JSON. Use `social schema`, `social schema --list`, or
52
+ `social schema "<command path>"` for the machine-readable command tree.
62
53
 
63
- Commands marked **✎ write** mutate your account and require an explicit write
64
- scope (see [Account safety](#account-safety)).
54
+ Commands marked **write** mutate your account and require write scope. Commands
55
+ marked **local** update local CLI state or the local mirror.
65
56
 
66
57
  ### Targets
67
58
 
68
- Commands with `[target]` or `<target>` accept `@handle` or `@public-identifier`,
69
- a full X/LinkedIn URL, a LinkedIn URN, or a typed ID such as `profile_id:<id>`,
70
- `post_id:<id>`, `list_id:<id>`, `chat_id:<id>`, `conversation_id:<id>`, `company_id:<id>`, or `request_id:<id>`. Bare IDs are not
71
- accepted. When an optional target is omitted, the command acts on your own
72
- connected account.
59
+ Targets accept handles, profile/post/conversation/company URLs, LinkedIn URNs,
60
+ or typed IDs such as `profile_id:<id>`, `post_id:<id>`, `chat_id:<id>`,
61
+ `conversation_id:<id>`, `company_id:<id>`, and `request_id:<id>`. Bare IDs are
62
+ not accepted.
73
63
 
74
64
  ### Body text
75
65
 
76
- Commands that create a post, comment, message, or connection note read the body
77
- from **stdin** — there is no text argument. Pipe it in:
66
+ Posts, comments, messages, message edits, and connection-request notes read
67
+ freeform text from stdin. There is no text positional:
78
68
 
79
69
  ```sh
80
70
  echo "gm" | social x post
81
71
  social linkedin post < draft.md
82
- social linkedin requests send @handle < note.txt # optional connection note
72
+ social linkedin requests send @handle < note.txt
73
+ ```
74
+
75
+ Pipe a JSON object for advanced payload fields.
76
+
77
+ ## Your data is local
78
+
79
+ `sync` pulls your own data down; it is explicit and costs credits. `sql` queries
80
+ that local mirror; it is free, instant, and read-only. Named read commands call
81
+ the live network and cost credits; `x tweets <target>` and
82
+ `linkedin posts <target>` require a target. Writes act.
83
+
84
+ ```sh
85
+ social x sync messages
86
+ social x sql "SELECT sender_handle, text, datetime(created_at/1000,'unixepoch') AS at FROM x_messages ORDER BY created_at DESC LIMIT 20" \
87
+ | jq '.items[]'
83
88
  ```
84
89
 
85
- On an interactive terminal with nothing piped, required body-text commands fail
86
- fast rather than hang. To send advanced payload fields, pipe a JSON object via
87
- stdin; if stdin parses as JSON but is not an object, the command rejects it.
90
+ The X inbox query gets `sender_handle` from the `x_messages` view; no extra
91
+ profile lookup is needed.
88
92
 
89
93
  ### Top level
90
94
 
91
95
  | Command | Description |
92
- |---|---|
93
- | `social account` | Show auth state and connected accounts; login, logout, connect accounts, inspect billing/usage/logs, and configure local CLI settings. |
94
- | `social schema` | Print the compact command tree, inspect one command with `social schema "<command path>"`, or emit agent command contracts with `social schema --leaves`. |
95
- | `social x <…>` | X operations (below). |
96
- | `social linkedin <…>` | LinkedIn operations (below). |
96
+ | --- | --- |
97
+ | `social account` | Auth state, connected accounts, login/logout, connect/reconnect/disconnect, billing, usage, logs, and cache config. |
98
+ | `social schema` | Print the command tree, inspect one command, emit the compact runnable index, or emit full contracts. |
99
+ | `social x <...>` | X operations. |
100
+ | `social linkedin <...>` | LinkedIn operations. |
101
+ | `social feedback bug\|feature` | Send a bug report or feature request to the maintainers (report text from stdin). |
97
102
 
98
103
  ### `social account`
99
104
 
100
105
  | Command | Description | |
101
- |---|---|---|
106
+ | --- | --- | --- |
102
107
  | `(bare)` | Show who is signed in and list connected accounts. | |
103
108
  | `login` | Device sign-in, scope selection, and billing. | |
104
109
  | `logout` | Revoke the session and clear the saved token. | |
105
- | `connect linkedin` | Open or print a LinkedIn connection URL. | ✎ write |
106
- | `connect x` | Open or print an X OAuth URL. | ✎ write |
107
- | `reconnect linkedin <account>` | Re-auth an existing LinkedIn account by opening or printing a connection URL. | ✎ write |
108
- | `reconnect x <account>` | Re-auth an existing X account by opening or printing an OAuth URL. | ✎ write |
109
- | `disconnect linkedin <account>` | Disconnect a LinkedIn account. | ✎ write |
110
- | `disconnect x <account>` | Disconnect an X account. | ✎ write |
110
+ | `connect linkedin` | Open or print a LinkedIn connection URL. | write |
111
+ | `connect x` | Open or print an X OAuth URL. | write |
112
+ | `reconnect linkedin <account>` | Re-auth an existing LinkedIn account. | write |
113
+ | `reconnect x <account>` | Re-auth an existing X account. | write |
114
+ | `disconnect linkedin <account>` | Disconnect a LinkedIn account. | write |
115
+ | `disconnect x <account>` | Disconnect an X account. | write |
111
116
  | `billing` | Show seats, subscription, and current usage billing. | |
112
117
  | `billing portal` | Open the hosted billing portal and print its URL. | |
113
118
  | `usage` | Aggregate proxy usage and billing stats. | |
114
119
  | `logs` | Recent proxy calls. | |
115
- | `config cache mode` | Read or set the cache mode preset. | |
116
- | `config cache ttl` | Set a custom cache TTL in seconds. | |
117
-
118
- `social account` returns compact JSON with the authenticated user and connected accounts.
120
+ | `config cache mode` | Read or set the live-read proxy cache mode. | |
121
+ | `config cache ttl` | Set a live-read proxy cache TTL in seconds. | |
119
122
 
120
123
  ### `social linkedin`
121
124
 
122
125
  | Command | Description | |
123
- |---|---|---|
124
- | `post` | Create a post (body from stdin). | ✎ write |
125
- | `comment <target>` | Comment on a post (body from stdin). | ✎ write |
126
- | `react <target> [type=like]` | React to a post or comment. | ✎ write |
127
- | `requests send <target>` | Send a connection request (optional note from stdin). | ✎ write |
128
- | `requests sent` | List pending sent connection requests; supports `--limit`, `--offset`, and `-H/--header`. | |
129
- | `requests received` | List pending received connection requests; supports `--limit`, `--offset`, and `-H/--header`. | |
130
- | `requests accept request_id:<id>` | Accept a received connection request. | ✎ write |
131
- | `requests cancel request_id:<id>` | Cancel a sent request or refuse a received connection request. | ✎ write |
132
- | `posts [target]` | List a user's or company's posts; supports `--limit` and `--offset`; omit the target for your own account. | |
126
+ | --- | --- | --- |
127
+ | `profile [target]` | Fetch a profile; omit target for your own account. | |
128
+ | `posts <target>` | Live posts for a person or company; target required. | |
133
129
  | `comments <target>` | List a post's comments; supports `--limit` and `--offset`. | |
134
130
  | `reactions <target>` | List a post's reactions; supports `--limit` and `--offset`. | |
135
- | `profile [target]` | Fetch a profile; omit the target for your own account. | |
136
- | `connections [target]` | List connections; supports `--limit` and `--offset`; omit the target for account-level connections. | |
131
+ | `connections [target]` | Live connection graph read; omit target for your own account. Supports `--limit` and `--cursor` from `.meta.cursor`. Costs credits. | |
137
132
  | `company <target>` | Fetch a company profile. | |
138
133
  | `jobs <target>` | List a company's job postings; supports `--limit` and `--offset`. | |
139
- | `messages` | List conversations. | |
140
- | `messages <target>` | Read a conversation by `chat_id:<id>`, `@handle`, `profile_id:<id>`, profile URL, or messaging-thread URL. | |
141
- | `message <target>` | Send a message (body from stdin). | ✎ write |
142
- | `message <target> delete message_id:<id>` | Delete one of your own messages. | ✎ write |
143
- | `message <target> edit message_id:<id>` | Edit one of your own messages (new text from stdin). | ✎ write |
144
- | `messages <target> mark read` | Mark a conversation read. | ✎ write |
145
- | `messages <target> mark unread` | Mark a conversation unread. | ✎ write |
134
+ | `search people\|posts\|jobs\|companies <keywords>` | Search LinkedIn; live offset-paginated reads. | |
135
+ | `sync [collection]` | Pull your own `connections`, `posts`, `messages`, or `requests` into the local mirror; costs credits. | local |
136
+ | `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints the schema. | |
137
+ | `post` | Create a post (body from stdin). | write |
138
+ | `comment <target>` | Comment on a post (body from stdin). | write |
139
+ | `react <target>` | React to a post or comment; use `--type` for non-like reactions. | write |
140
+ | `requests send <target>` | Send a connection request (optional note from stdin). | write |
141
+ | `requests accept request_id:<id>` | Accept a received connection request. | write |
142
+ | `requests cancel request_id:<id>` | Cancel a sent request or refuse a received connection request. | write |
143
+ | `message <target>` | Send a message (body from stdin). | write |
144
+ | `message <target> delete message_id:<id>` | Delete one of your own messages. | write |
145
+ | `message <target> edit message_id:<id>` | Edit one of your own messages (new text from stdin). | write |
146
+ | `messages <target> mark read` | Mark a conversation read. | write |
147
+ | `messages <target> mark unread` | Mark a conversation unread. | write |
146
148
 
147
149
  ### `social x`
148
150
 
149
151
  | Command | Description | |
150
- |---|---|---|
151
- | `post` | Create a post (body from stdin). | ✎ write |
152
- | `delete <target>` | Delete one of your own posts. | ✎ write |
153
- | `repost <target>` · `unrepost <target>` | Repost or undo a repost. | ✎ write |
154
- | `reposters <target>` | List users who reposted a post. | |
155
- | `quotes <target>` | List quote posts of a post. | |
152
+ | --- | --- | --- |
153
+ | `profile [target]` | Fetch a profile; omit target for your own account. | |
154
+ | `tweets <target>` | Live posts for a user; target required. | |
155
+ | `timeline` | Read the home timeline. | |
156
+ | `mentions [target]` | List posts mentioning a user; omit target for your own account. | |
157
+ | `liked [target]` | List posts a user liked; omit target for your own account. | |
158
+ | `followers [target]` | Live follower graph read; omit target for your own account. Costs credits. | |
159
+ | `following [target]` | Live following graph read; omit target for your own account. Costs credits. | |
160
+ | `tweet <target>` | Fetch a single post. | |
156
161
  | `replies <target>` | List replies to a post; accepts `post_id:<id>`, `conversation_id:<id>`, or a post URL. | |
157
- | `like <target>` · `unlike <target>` | Like or unlike a post. | ✎ write |
158
- | `liked [target]` | List posts a user has liked; omit the target for your own account. | |
162
+ | `quotes <target>` | List quote posts of a post. | |
159
163
  | `likers <target>` | List users who liked a post. | |
160
- | `follow <target>` · `unfollow <target>` | Follow or unfollow a user. | ✎ write |
161
- | `followers [target]` | List a user's followers; omit the target for your own account. | |
162
- | `following [target]` | List accounts a user follows; omit the target for your own account. | |
163
- | `tweet <target>` | Fetch a single post. | |
164
- | `tweets [target]` | List a user's recent posts; omit the target for your own account. | |
165
- | `mentions [target]` | List posts mentioning a user; omit the target for your own account. | |
166
- | `profile [target]` | Fetch a profile; omit the target for your own account. | |
167
- | `timeline` | Read the home timeline. | |
168
- | `bookmarks` | List your saved bookmarks. | |
169
- | `bookmark <target>` · `unbookmark <target>` | Add or remove a bookmark. | ✎ write |
170
- | `messages` | List conversations. | |
171
- | `messages <target>` | Read a DM conversation or participant target: chat URL, `chat_id:<id>`, `@handle`, profile URL, or `profile_id:<id>`. | |
172
- | `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 |
164
+ | `reposters <target>` | List users who reposted a post. | |
165
+ | `sync [collection]` | Pull your own `tweets`, `followers`, `following`, `bookmarks`, or `messages` into the local mirror; costs credits. | local |
166
+ | `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints the schema. | |
167
+ | `post` | Create a post (body from stdin). | write |
168
+ | `message <recipients>` | Send a DM (body from stdin). | write |
169
+ | `like <target>` / `unlike <target>` | Like or unlike a post. | write |
170
+ | `follow <target>` / `unfollow <target>` | Follow or unfollow a user. | write |
171
+ | `repost <target>` / `unrepost <target>` | Repost or undo a repost. | write |
172
+ | `bookmark <target>` / `unbookmark <target>` | Add or remove a saved post. | write |
173
+ | `delete <target>` | Delete one of your own posts. | write |
173
174
 
174
175
  ## Built for agents
175
176
 
176
- - **Everything speaks JSON.** Pipe output through `jq`, `fzf`, or your agent's
177
- planner — anything that reads stdin. Structured errors and predictable exit
178
- codes mean an agent can branch on what happened.
179
- - **Schema-backed pagination.** Use `--offset` for LinkedIn list reads,
180
- `--cursor` for LinkedIn messages and X reads, and `--limit` to bound pages.
181
- Cacheable reads also list `-H/--header` for proxy cache headers such as
182
- `Cache-Control: no-cache`.
183
- - **A skill you drop straight in.** Install the public skill repo with
184
- `npx skills add usesocial/skill`; Claude, Codex, or any other supported agent
185
- then knows the commands.
177
+ - Everything speaks JSON: success on stdout, structured errors on stderr.
178
+ - One envelope: lists use `.items[]`, single resources use `.data`, metadata
179
+ lives under `.meta`.
180
+ - Schema-backed planning: `social schema --list` is the compact runnable index.
181
+ - Local SQL is the free surface for your own synced data.
186
182
 
187
183
  ```sh
188
- # Review recent LinkedIn posts, fan out to reaction graphs, rank warm contacts.
189
- social linkedin posts --limit 25 --offset 0 > /tmp/recent-posts.json
184
+ # SQL insight: synced contacts you have never messaged.
185
+ # Run `social linkedin sync connections` and `social linkedin sync messages` first.
186
+ social linkedin sql "SELECT c.user_display_name, c.user_public_identifier, c.user_profile_url FROM li_connections c LEFT JOIN li_messages m ON m.sender_id = c.user_id WHERE m.id IS NULL ORDER BY c.created_at DESC LIMIT 100" \
187
+ | jq '.items[]'
188
+
189
+ # Live fan-out: review recent posts, fan out to reactions, rank warm contacts.
190
+ social linkedin posts profile_id:<profile-id> --limit 25 --offset 0 > /tmp/recent-posts.json
190
191
  jq -r '.items[].id' /tmp/recent-posts.json \
191
192
  | xargs -I{} social linkedin reactions post_id:{} --limit 100 --offset 0 \
192
193
  | jq -s '[ .[] | .items[] ]
@@ -198,125 +199,104 @@ jq -r '.items[].id' /tmp/recent-posts.json \
198
199
  ## Exit codes
199
200
 
200
201
  | Code | Meaning | Agent action |
201
- |---:|---|---|
202
+ | ---: | --- | --- |
202
203
  | `0` | Success | Continue. |
203
- | `2` | Usage or validation error | Fix the command, flags, IDs, JSON body, or local input. |
204
+ | `2` | Usage or validation error | Fix the command, flags, IDs, JSON body, or local input - server-side failures are exit 5. |
204
205
  | `3` | Not found | Check the resource ID or pick a different item. |
205
206
  | `4` | Auth or scope error | Run `social account login`, or log out and choose the needed scope. |
206
- | `5` | API or unexpected error | Retry later or surface the server error. |
207
- | `7` | Rate limited | LinkedIn retries automatically; otherwise back off, using `retryAfterSeconds` when present. |
207
+ | `5` | API, proxy, or unexpected error | Retry later or surface the server error. |
208
+ | `7` | Rate limited | Back off, using `retryAfterSeconds` when present. |
208
209
 
209
210
  ## Auth
210
211
 
211
- `social account login` runs a device-authorization flow:
212
-
213
- 1. Asks what access to grant the agent. Read and Write are both selected by
214
- default; clear Write in the prompt to grant read-only access.
215
- 2. Asks for your email address.
216
- 3. Sends a magic link to that email with the device approval screen already
217
- attached while asking for your phone number.
218
- 4. Waits until you click the magic link and approve the CLI session in the
219
- browser, then stores the returned token in your OS keyring.
220
- 5. Stores the phone number, then confirms billing checkout in the terminal when
221
- a seat is needed. If no keyring is available, credentials fall back to
222
- `~/.social/credentials.json` (mode `0600`).
223
- Non-production `SOCIAL_API_URL` values use an API-specific credential
224
- namespace so staging tests do not overwrite the production session.
225
-
226
- `social account logout` revokes the session and removes the stored token from both places.
227
- Bare `social account` prints compact JSON with the current auth state, credential
228
- namespace, verified session when available, and connected accounts.
229
- `social account login` requires an interactive terminal and is not supported from CI,
230
- background jobs, or agent-mediated setup flows.
212
+ `social account login` runs a device-authorization flow. It asks what access to
213
+ grant, sends a magic link, waits for browser approval, stores the returned token
214
+ in your OS keyring, and confirms billing checkout when a seat is needed.
215
+
216
+ `social account logout` revokes the session and removes the stored token.
217
+ `social account login` requires an interactive terminal and is not supported from
218
+ CI, background jobs, or agent-mediated setup flows.
231
219
 
232
220
  `social account billing` prints the current seat/subscription snapshot plus
233
- aggregate usage billing. `social account billing portal` opens the hosted billing
234
- portal when possible and always prints the portal URL as JSON; use the portal for
235
- payment methods, invoices, plan changes, seat changes, and cancellation.
221
+ aggregate usage billing. `social account billing portal` opens the hosted
222
+ billing portal when possible and always prints the portal URL as JSON.
236
223
 
237
224
  ## Cache config
238
225
 
239
- Allowlisted GET requests use a local proxy cache. Cacheable commands send
240
- `Cache-Control: max-age=<seconds>` from your local config:
226
+ There are two cache layers.
227
+
228
+ The proxy cache applies to live reads only. Cache hits are free; fresh upstream
229
+ reads are metered. Configure the default:
241
230
 
242
231
  ```sh
243
- social account config cache mode # read the current cache mode and TTL
244
- social account config cache mode live # 15 minutes, default
245
- social account config cache mode analytical # 24 hours
246
- social account config cache mode historical # 1 week
247
- social account config cache ttl 3600 # custom TTL in seconds
232
+ social account config cache mode
233
+ social account config cache mode live
234
+ social account config cache mode analytical
235
+ social account config cache mode historical
236
+ social account config cache ttl 3600
248
237
  ```
249
238
 
250
- Setting `ttl` switches the mode to `custom`. Config is stored at
251
- `~/.social/config.json` with mode `0600`.
252
-
253
- Use command-level request headers to override freshness for a single read when a
254
- command lists `--header` in help:
239
+ Override one live read when the command lists `--header`:
255
240
 
256
241
  ```sh
257
- social linkedin profile @handle -H "Cache-Control: no-cache" # bypass cache read, refresh cache
258
- social linkedin profile @handle -H "Cache-Control: no-store" # bypass cache read and write
259
- social linkedin profile @handle -H "Cache-Control: max-age=60" # override TTL for this request
242
+ social linkedin profile @handle -H "Cache-Control: no-cache"
243
+ social linkedin profile @handle -H "Cache-Control: no-store"
244
+ social linkedin profile @handle -H "Cache-Control: max-age=60"
260
245
  ```
261
246
 
262
- `Cache-Control` is the functional request cache surface. Cached responses may
263
- preserve validators such as `ETag` and `Last-Modified` when the upstream returns
264
- them, but the CLI does not expose conditional revalidation semantics; use
265
- `Cache-Control: no-cache` when you need a fresh upstream read.
266
-
267
- Command output exposes actual per-call cost and pagination under `meta`:
247
+ The local mirror is separate: run `sync` when you want newer local data, then
248
+ query it with `sql`. SQL reads show local freshness in `meta.cache.tables`:
268
249
 
269
250
  ```sh
270
- social linkedin reactions post_id:<post-id> --limit 100 --offset 0 \
271
- | jq '{cost: .meta.cost, totalCount: .meta.totalCount}'
272
- social linkedin messages --limit 20 | jq '{cost: .meta.cost, cursor: .meta.cursor}'
273
- social x bookmarks --limit 20 | jq '{cost: .meta.cost, cursor: .meta.cursor}'
251
+ social x sql "SELECT sender_handle, text FROM x_messages ORDER BY created_at DESC LIMIT 5" \
252
+ | jq '{cost: .meta.cost, cache: .meta.cache}'
253
+ social x timeline --limit 20 | jq '{cost: .meta.cost, cursor: .meta.cursor, cache: .meta.cache}'
274
254
  ```
275
255
 
276
- Agents should watch `.meta.cost` during high-fanout loops, use `social account billing`
277
- for the current plan snapshot, and use `social account usage` or `social account logs`
278
- after a run to summarize actual spend.
279
-
280
- ## Account safety
281
-
282
- Built so your accounts outlive your prototype.
283
-
284
- - **Read/write scope by default.** Clear Write during login when you want a
285
- read-only session that can't post, react, or request connections.
286
- - **A write never fires twice.** Rate-limit and server errors surface verbatim and
287
- writes are never retried — so a post or connection request can't double-send.
288
- - **A residential IP per account.** Each connected account runs over a dedicated
289
- residential proxy with smart rate-limiting, so the network sees a normal session.
256
+ Agents should watch `.meta.cost` during high-fanout loops, use
257
+ `social account billing` for the current plan snapshot, and use
258
+ `social account usage` or `social account logs` after a run to summarize spend.
290
259
 
291
260
  ## Examples
292
261
 
293
262
  ```sh
294
- # LinkedIn
263
+ # LinkedIn local mirror.
264
+ social linkedin sync messages
265
+ social linkedin sql "SELECT sender_display_name, text, datetime(timestamp/1000,'unixepoch') AS at FROM li_messages ORDER BY timestamp DESC LIMIT 20"
266
+ social linkedin sql "SELECT user_display_name, user_public_identifier FROM li_requests WHERE type='received' ORDER BY created_at DESC LIMIT 25"
267
+
268
+ # LinkedIn live reads.
295
269
  social linkedin profile
296
- social linkedin requests received --limit 25 --offset 0
297
- social linkedin requests sent --limit 25 --offset 0
270
+ social linkedin posts profile_id:<profile-id> --limit 25 --offset 0
271
+ social linkedin reactions post_id:<post-id> --limit 100 --offset 0
272
+
273
+ # X local mirror.
274
+ social x sync messages
275
+ social x sql "SELECT sender_handle, text FROM x_messages ORDER BY created_at DESC LIMIT 20"
276
+ social x sql "SELECT text, url FROM x_bookmarks ORDER BY created_at DESC LIMIT 50"
277
+ social x sql "SELECT username, name, followers_count FROM x_followers ORDER BY followers_count DESC LIMIT 100"
298
278
 
299
- # X
300
- social x bookmarks --limit 50
301
- social x followers --limit 100
302
- social x following profile_id:<x-user-id> --limit 100
279
+ # X live reads.
280
+ social x tweets profile_id:<x-user-id> --limit 30
303
281
  social x replies post_id:<post-id> --limit 25
304
- social x messages --limit 50
282
+ social x timeline --limit 50
305
283
 
306
- # Writes (body via stdin)
284
+ # Writes (body via stdin).
307
285
  echo "gm" | social x post
308
286
  social linkedin post < draft.md
287
+ echo "Loved your launch notes." | social linkedin requests send profile_id:<profile-id>
309
288
 
310
- # Usage / billing
289
+ # Usage / billing.
311
290
  social account billing
312
291
  social account billing portal
313
292
  social account usage
314
293
  social account logs --limit 20 --from 2026-05-01T00:00:00Z
315
294
 
316
- # Command schema
295
+ # Command schema.
317
296
  social schema
297
+ social schema --list
318
298
  social schema --leaves
319
- social schema "linkedin requests received"
299
+ social schema "linkedin requests send"
320
300
  social schema "x post"
321
301
  ```
322
302