@usesocial/cli 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @usesocial/cli
+
+## 0.1.2
+
+### Patch Changes
+
+- [`158bf58`](https://github.com/usesocial/monorepo/commit/158bf5804d47112fa2ed941fd7e78174a53b3947) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Release the promoted account lifecycle, schema, and publishing pipeline updates.
+
+Future release entries are managed by Changesets.

package/README.md

@@ -1,8 +1,15 @@
-# @usesocial/cli
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://usesocial.dev/app-icon-dark.svg" />
+    <img alt="social" height="84" src="https://usesocial.dev/app-icon.svg" width="84" />
+  </picture>
+</p>
 
-**Give your agent access to social networks.** One install, one login, and your
-agent can read, search, and graph LinkedIn and X — and post through your own
-account when you let it — from any shell, any runtime.
+<h1 align="center">@usesocial/cli</h1>
+
+**Agent-run distribution.** One install, one login, and your agent can run
+distribution work across X and LinkedIn — outreach, posting, audience insights,
+and the follow-up loops between them — from any shell.
 
 `social` is built for people who live in a terminal with an agent open and are on
 the hook for their own distribution. The work you keep meaning to do — see who
@@ -15,21 +22,17 @@ Published as `@usesocial/cli` on npm; the binary is `social`.
 ## Install
 
 ```sh
-brew install usesocial/tap/social
-# or
-bun install -g @usesocial/cli@latest
-# or
-npm install -g @usesocial/cli
+curl -fsSL https://usesocial.dev/install.sh | bash
 ```
 
 ## Quickstart
 
 ```sh
-social login                            # device sign-in, choose scope, set up billing
-social linkedin connect                 # connect a LinkedIn account
-social linkedin users me --pretty
-social x connect                        # connect an X account
-social x users me --pretty
+social account login                    # device sign-in, choose scope, set up billing
+social account connect linkedin         # connect a LinkedIn account
+social linkedin profile
+social account connect x                # connect an X account
+social x profile
 ```
 
 ## What you can hand your agent
@@ -39,122 +42,203 @@ A few of the things the command surface supports:
 
 | You ask | The agent reaches for |
 |---|---|
-| "Surface the ten connections worth reaching out to this week." | `linkedin users connections`, `x users tweets` |
-| "Pull everyone who reacted to my last LinkedIn post and flag the warm leads." | `linkedin posts reactions`, `linkedin users get` |
-| "Read this creator's recent posts and break down what makes them land." | `linkedin users posts`, `x users tweets` |
-| "Find what people are saying about AI agents this week and summarize the themes." | `linkedin search posts`, `x search recent` |
-| "Draft a reply to this thread and post it once I approve." | `linkedin posts comment`, `x tweets post` |
+| "Surface the ten connections worth reaching out to this week." | `linkedin connections`, `x tweets` |
+| "Pull everyone who reacted to my last LinkedIn post and flag the warm leads." | `linkedin reactions`, `linkedin profile` |
+| "Read this creator's recent posts and break down what makes them land." | `linkedin posts`, `x tweets` |
+| "Find what people are saying about AI agents this week and summarize the themes." | `linkedin search posts`, `x timeline` |
+| "Draft a reply to this thread and post it once I approve." | `linkedin comment`, `x post` |
 
 ## Commands
 
-Every command supports `--json` and `--pretty` for machine- vs. human-readable
-output. Most accept filters like `--limit`, `--cursor`, `--from`, and `--to`. Pass
-`--help` on any subcommand for the full flag list, or run `social schema` for a
-structured dump of every command — handy as an agent manifest.
+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>"`
+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.
 
 Commands marked **✎ write** mutate your account and require an explicit write
 scope (see [Account safety](#account-safety)).
 
+### Targets
+
+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
+accepted. When an optional target is omitted, the command acts on your own
+connected account.
+
 ### Top level
 
 | Command | Description |
 |---|---|
-| `social login` | Device sign-in, scope selection, billing, optional agent-skill install. |
-| `social logout` | Revoke the session and clear the saved token. |
-| `social schema` | Print the full command tree as JSON — a manifest for agents. |
-| `social usage` | Recent calls or an aggregate billing/usage summary. |
-| `social linkedin <…>` | LinkedIn operations (below). |
+| `social account` | Show auth state and connected accounts; login, logout, connect accounts, inspect usage/logs, and configure local CLI settings. |
+| `social schema` | Print the compact command tree, inspect one command with `social schema "<command path>"`, or emit agent command contracts with `social schema --leaves`. |
 | `social x <…>` | X operations (below). |
+| `social linkedin <…>` | LinkedIn operations (below). |
+
+### `social account`
+
+| Command | Description | |
+|---|---|---|
+| `(bare)` | Show who is signed in and list connected accounts. | |
+| `login` | Device sign-in, scope selection, and billing. | |
+| `logout` | Revoke the session and clear the saved token. | |
+| `connect linkedin` | Connect a LinkedIn account through the browser. | ✎ write |
+| `connect x` | Connect an X account through OAuth. | ✎ write |
+| `reconnect linkedin <account>` | Re-auth an existing LinkedIn account. | ✎ write |
+| `reconnect x <account>` | Re-auth an existing X account. | ✎ write |
+| `disconnect linkedin <account>` | Disconnect a LinkedIn account. | ✎ write |
+| `disconnect x <account>` | Disconnect an X account. | ✎ write |
+| `usage` | Aggregate proxy usage and billing stats. | |
+| `logs` | Recent proxy calls. | |
+| `config cache mode` | Read or set the cache mode preset. | |
+| `config cache ttl` | Set a custom cache TTL in seconds. | |
+
+`social account` returns compact JSON with the signed-in user and connected accounts.
 
 ### `social linkedin`
 
 | Command | Description | |
 |---|---|---|
-| `companies get` | Fetch a company profile. | |
-| `companies employees` | List employees at a company. | |
-| `companies jobs` | List a company's job postings. | |
-| `posts get` | Fetch a post. | |
-| `posts comments` | List a post's comments. | |
-| `posts reactions` | List a post's reactions. | |
-| `posts post` | Create a post. | ✎ write |
-| `posts comment` | Comment on a post. | ✎ write |
-| `posts react` | React to a post or comment. | ✎ write |
-| `search people` | Search for people. | |
-| `search posts` | Search for posts. | |
-| `users get` | Fetch a profile. | |
-| `users connections` | List a user's connections. | |
-| `users posts` | List a user's or company's posts. | |
-| `users me` | Show the connected LinkedIn profile. | |
-| `users invite` | Send a connection invite. | ✎ write |
-| `connect` · `reconnect` · `disconnect` · `list` | Account lifecycle and listing. | |
+| `post <text>` | Create a post. | ✎ write |
+| `comment <target> <text>` | Comment on a post. | ✎ 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 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. | |
+| `profile [target]` | Fetch a profile; omit the target for your own account. | |
+| `connections [target]` | List connections; omit the target for account-level connections. | |
+| `company <target>` | Fetch a company profile. | |
+| `jobs <target>` | List a company's job postings. | |
+| `search people <keywords>` | Search for people. | |
+| `search posts <keywords>` | Search for posts. | |
+| `search jobs <keywords>` | Search for jobs. | |
+| `search companies <keywords>` | Search for companies. | |
+| `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> 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 |
+| `messages <target> mark read` | Mark a conversation read. | ✎ write |
+| `messages <target> mark unread` | Mark a conversation unread. | ✎ write |
 
 ### `social x`
 
 | Command | Description | |
 |---|---|---|
-| `search recent` | Search posts from the last 7 days. | |
-| `timelines home` | Read the home timeline. | |
-| `tweets list` | Fetch up to 100 posts by ID. | |
-| `tweets get` | Fetch a single post by ID. | |
-| `tweets post` | Create a post. | ✎ write |
-| `tweets like` · `unlike` | Like or unlike a post. | ✎ write |
-| `tweets repost` · `unrepost` | Repost or undo a repost. | ✎ write |
-| `tweets delete` | Delete a post. | ✎ write |
-| `users tweets` | List a user's recent posts. | |
-| `users me` | Show the authenticated X profile. | |
-| `users follow` · `unfollow` | Follow or unfollow a user. | ✎ write |
-| `bookmarks list` | List your saved bookmarks. | |
-| `bookmarks add` · `remove` | Add or remove a bookmark. | ✎ write |
-| `connect` · `reconnect` · `disconnect` · `list` | Account lifecycle and listing. | |
+| `post <text>` | Create a post. | ✎ write |
+| `repost <target>` · `unrepost <target>` | Repost or undo a repost. | ✎ write |
+| `like <target>` · `unlike <target>` | Like or unlike a post. | ✎ write |
+| `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. | |
+| `profile [target]` | Fetch a profile; omit the target for your own account. | |
+| `timeline` | Read the home timeline. | |
+| `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 |
 
 ## Built for agents
 
-- **Everything speaks JSON.** Pass `--json` and pipe 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 flags across networks.** `--limit`, `--cursor`, `--json`,
-  `--pretty`. Learn the surface once; reuse it on LinkedIn and X.
+- **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.
 - **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. `social login` can install it for you.
+  then knows the commands.
 
 ```sh
-# Find hiring posts, fan out to reaction graphs, rank warm contacts — one pipe.
-social linkedin search posts "AI infra hiring" --limit 10 --json \
-  | jq -r '.posts[].urn' \
-  | xargs -I{} social linkedin posts reactions {} --json \
-  | jq -s '[.[].reactions[] | {actor, type}]
-            | group_by(.actor.id)
-            | map({actor: .[0].actor, signals: length})
+# Find hiring posts, fan out to reaction graphs, rank warm contacts.
+social linkedin search posts "AI infra hiring" --limit 25 > /tmp/hiring-posts.json
+jq -r '.items[].id' /tmp/hiring-posts.json \
+  | xargs -I{} social linkedin reactions post_id:{} \
+  | jq -s '[ .[] | .items[] ]
+            | group_by(.actor.id // .reactor.id // .profile_id)
+            | map({person: (.[0].actor // .[0].reactor), signals: length})
             | sort_by(-.signals) | .[0:15]'
 ```
 
+## Exit codes
+
+| Code | Meaning | Agent action |
+|---:|---|---|
+| `0` | Success | Continue. |
+| `2` | Usage or validation error | Fix the command, flags, IDs, JSON body, or local input. |
+| `3` | Not found | Check the resource ID or pick a different item. |
+| `4` | Auth or scope error | Run `social account login`, or log out and choose the needed scope. |
+| `5` | API or unexpected error | Retry later or surface the server error. |
+| `7` | Rate limited | Back off; JSON errors may include `retryAfterSeconds`. |
+
 ## Auth
 
-`social login` runs a device-authorization flow:
+`social account login` runs a device-authorization flow:
 
-1. Shows you a verification code and opens the approval page in your browser
-   (or prints the URL if there's no TTY, or you pass `--no-open`).
-2. Waits until you approve the session in the browser.
-3. Stores the returned token in your OS keyring, falling back to
+1. Asks what access to grant the agent. Read and Write are both selected by
+   default; clear Write in the prompt to grant read-only access.
+2. Asks for your email address.
+3. Shows you a verification code and approval URL, then tries to open that URL
+   in your browser.
+4. Waits until you approve the session in the browser.
+5. Confirms billing checkout in the terminal when a seat is needed.
+6. Stores the returned token in your OS keyring, falling back to
    `~/.social/credentials.json` (mode `0600`) when no keyring is available.
+   Non-production `SOCIAL_API_URL` values use an API-specific credential
+   namespace so staging tests do not overwrite the production session.
+
+`social account logout` revokes the session and removes the stored token from both places.
+Bare `social account` prints compact JSON with the current auth state, credential
+namespace, verified session when available, and connected accounts.
+`social account login` requires an interactive terminal and is not supported from CI,
+background jobs, or agent-mediated setup flows.
 
-`social logout` revokes the session and removes the stored token from both places.
+## Cache config
 
-For non-interactive use (CI, agents), pass the details up front:
+Allowlisted GET requests use a local proxy cache. Cacheable commands send
+`Cache-Control: max-age=<seconds>` from your local config:
 
 ```sh
-social login --email you@example.com --scope read,write --accept-pricing --json
+social account config cache mode                  # read the current cache mode and TTL
+social account config cache mode live             # 15 minutes, default
+social account config cache mode analytical       # 24 hours
+social account config cache mode historical       # 1 week
+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.
+
+Command output exposes actual per-call cost and pagination under `meta`:
+
+```sh
+social linkedin messages --limit 20 | jq '.meta.cost'
+social x bookmarks --limit 20 | jq '{cost: .meta.cost, cursor: .meta.cursor}'
+```
+
+Agents should watch `.meta.cost` during high-fanout loops and use `social account usage`
+or `social account logs` after a run to summarize actual spend.
+
 ## Account safety
 
 Built so your accounts outlive your prototype.
 
-- **Read scope by default.** Writes need an explicit upgrade you can revoke. A
-  read-only session can't post, react, or invite.
+- **Read/write scope by default.** Clear Write during login when you want a
+  read-only session that can't post, react, or request connections.
 - **A write never fires twice.** Rate-limit and server errors surface verbatim and
-  writes are never retried — so a post or invite can't double-send.
+  writes are never retried — so a post or connection request can't double-send.
 - **A residential IP per account.** Each connected account runs over a dedicated
   residential proxy with smart rate-limiting, so the network sees a normal session.
 
@@ -162,24 +246,28 @@ Built so your accounts outlive your prototype.
 
 ```sh
 # LinkedIn
-social linkedin search people "founder ai" --limit 10 --pretty
-social linkedin users me --json
+social linkedin search people "founder ai"
+social linkedin profile
 
 # X
-social x search recent "from:elonmusk" --pretty
-social x bookmarks list --limit 50 --json
+social x bookmarks --limit 50
+social x followers --limit 100
+social x following profile_id:<x-user-id> --limit 100
+social x messages --limit 50
 
 # Usage / billing
-social usage --summary --platform linkedin --pretty
-social usage --limit 20 --from 2026-05-01T00:00:00Z
+social account usage
+social account logs --limit 20 --from 2026-05-01T00:00:00Z
 
-# Agent manifest
-social schema --pretty
+# Command schema
+social schema
+social schema --leaves
+social schema "x post"
 ```
 
 ## Links
 
-- Pricing and limits: <https://socialcli.dev/pricing>
-- Terms: <https://socialcli.dev/terms> · Privacy: <https://socialcli.dev/privacy>
+- Pricing and limits: <https://usesocial.dev/pricing>
+- Terms: <https://usesocial.dev/terms> · Privacy: <https://usesocial.dev/privacy>
 
-Built by founders with the same distribution problem.
+Built by founders who needed their agents to keep distribution moving.

package/bin/social.mjs

@@ -1,10 +1,17 @@
 #!/usr/bin/env node
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { loadEnvFile } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const localEnvPath = join(packageRoot, "..", "..", ".env.staging");
 const entryURL = pathToFileURL(join(packageRoot, "dist", "index.mjs")).href;
 
+if (existsSync(localEnvPath)) {
+  loadEnvFile(localEnvPath);
+}
+
 import(entryURL).catch((error) => {
   console.error(error);
   process.exit(1);

package/dist/index.d.mts

@@ -1 +1,98 @@
-export { };
+//#region ../../node_modules/.bun/citty@0.2.2/node_modules/citty/dist/index.d.mts
+//#region src/types.d.ts
+type ArgType = "boolean" | "string" | "enum" | "positional" | undefined;
+type _ArgDef<T extends ArgType, VT extends boolean | number | string> = {
+  type?: T;
+  description?: string;
+  valueHint?: string;
+  alias?: string | string[];
+  default?: VT;
+  required?: boolean;
+  options?: string[];
+};
+type BooleanArgDef = Omit<_ArgDef<"boolean", boolean>, "options"> & {
+  negativeDescription?: string;
+};
+type StringArgDef = Omit<_ArgDef<"string", string>, "options">;
+type EnumArgDef = _ArgDef<"enum", string>;
+type PositionalArgDef = Omit<_ArgDef<"positional", string>, "alias" | "options">;
+type ArgDef = BooleanArgDef | StringArgDef | PositionalArgDef | EnumArgDef;
+type ArgsDef = Record<string, ArgDef>;
+type ResolveParsedArgType<T extends ArgDef, VT> = T extends {
+  default?: any;
+  required?: boolean;
+} ? T["default"] extends NonNullable<VT> ? VT : T["required"] extends true ? VT : VT | undefined : VT | undefined;
+type ParsedPositionalArg<T extends ArgDef> = T extends {
+  type: "positional";
+} ? ResolveParsedArgType<T, string> : never;
+type ParsedStringArg<T extends ArgDef> = T extends {
+  type: "string";
+} ? ResolveParsedArgType<T, string> : never;
+type ParsedBooleanArg<T extends ArgDef> = T extends {
+  type: "boolean";
+} ? ResolveParsedArgType<T, boolean> : never;
+type ParsedEnumArg<T extends ArgDef> = T extends {
+  type: "enum";
+  options: infer U;
+} ? U extends Array<any> ? ResolveParsedArgType<T, U[number]> : never : never;
+type RawArgs = {
+  _: string[];
+};
+type ParsedArg<T extends ArgDef> = T["type"] extends "positional" ? ParsedPositionalArg<T> : T["type"] extends "boolean" ? ParsedBooleanArg<T> : T["type"] extends "string" ? ParsedStringArg<T> : T["type"] extends "enum" ? ParsedEnumArg<T> : never;
+type ParsedArgs<T extends ArgsDef = ArgsDef> = RawArgs & { [K in keyof T]: ParsedArg<T[K]> } & { [K in keyof T as T[K] extends {
+  alias: string;
+} ? T[K]["alias"] : never]: ParsedArg<T[K]> } & { [K in keyof T as T[K] extends {
+  alias: string[];
+} ? T[K]["alias"][number] : never]: ParsedArg<T[K]> } & Record<string, string | number | boolean | string[]>;
+interface CommandMeta {
+  name?: string;
+  version?: string;
+  description?: string;
+  hidden?: boolean;
+  alias?: string | string[];
+}
+type SubCommandsDef = Record<string, Resolvable<CommandDef<any>>>;
+type CommandDef<T extends ArgsDef = ArgsDef> = {
+  meta?: Resolvable<CommandMeta>;
+  args?: Resolvable<T>;
+  default?: Resolvable<string>;
+  subCommands?: Resolvable<SubCommandsDef>;
+  plugins?: Resolvable<CittyPlugin>[];
+  setup?: (context: CommandContext<T>) => any | Promise<any>;
+  cleanup?: (context: CommandContext<T>) => any | Promise<any>;
+  run?: (context: CommandContext<T>) => any | Promise<any>;
+};
+type CommandContext<T extends ArgsDef = ArgsDef> = {
+  rawArgs: string[];
+  args: ParsedArgs<T>;
+  cmd: CommandDef<T>;
+  subCommand?: CommandDef<T>;
+  data?: any;
+};
+type CittyPlugin = {
+  name: string;
+  setup?(context: CommandContext<any>): void | Promise<void>;
+  cleanup?(context: CommandContext<any>): void | Promise<void>;
+};
+type Resolvable<T> = T | Promise<T> | (() => T) | (() => Promise<T>); //#endregion
+//#region src/command.d.ts
+//#endregion
+//#region src/index.d.ts
+type MutableCommand = CommandDef<any> & {
+  args?: any;
+  meta?: any;
+  subCommands?: any;
+};
+/**
+ * Resolves the chain of matched command NAMES for analytics, e.g.
+ * `social x tweets get <id>` → `["x", "tweets", "get"]`. Mirrors the
+ * `commandForUsage` walk but collects names.
+ *
+ * PRIVACY: only tokens that resolve to a real subcommand are appended. The first
+ * arg that does not resolve (a positional value: tweet ID, handle, query text,
+ * flag value) breaks the walk and is NEVER captured. Never returns rawArgs or
+ * flag values.
+ */
+declare const resolveCommandPath: (command: MutableCommand, rawArgs: string[]) => Promise<string[]>;
+//#endregion
+export { resolveCommandPath };