@usesocial/cli 0.1.0 → 0.1.2

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,19 @@ 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
+# or install only the CLI with Homebrew
+brew install usesocial/tap/cli
 ```
 
 ## 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 auth login                       # device sign-in, choose scope, set up billing
+social accounts connect linkedin        # connect a LinkedIn account
+social linkedin whoami
+social accounts connect x               # connect an X account
+social x whoami
 ```
 
 ## What you can hand your agent
@@ -47,10 +52,10 @@ A few of the things the command surface supports:
 
 ## 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. 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.
 
 Commands marked **✎ write** mutate your account and require an explicit write
 scope (see [Account safety](#account-safety)).
@@ -59,13 +64,29 @@ scope (see [Account safety](#account-safety)).
 
 | 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 config` | Read or configure local CLI settings. |
+| `social auth login` | Device sign-in, scope selection, and billing. |
+| `social auth logout` | Revoke the session and clear the saved token. |
+| `social accounts <…>` | Connect, reconnect, disconnect, and list accounts. |
 | `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 x <…>` | X operations (below). |
 
+### `social accounts`
+
+| Command | Description | |
+|---|---|---|
+| `connect linkedin` | Connect a LinkedIn account through hosted auth. | ✎ 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 |
+| `list [linkedin\|x\|all]` | List accounts. Defaults to all platforms. | |
+
+`accounts list` returns `{ accounts: [...] }` as compact JSON.
+
 ### `social linkedin`
 
 | Command | Description | |
@@ -81,12 +102,16 @@ scope (see [Account safety](#account-safety)).
 | `posts react` | React to a post or comment. | ✎ write |
 | `search people` | Search for people. | |
 | `search posts` | Search for posts. | |
+| `inbox list` | List LinkedIn inbox conversations. | |
+| `inbox get` | Fetch an inbox conversation. | |
+| `inbox messages` | List messages in a chat. | |
+| `inbox send` | Send a message in a chat. | ✎ write |
 | `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. | |
+| `whoami` | Show the connected LinkedIn profile. | |
+| `users me` | Same profile read as `whoami`. | |
 | `users invite` | Send a connection invite. | ✎ write |
-| `connect` · `reconnect` · `disconnect` · `list` | Account lifecycle and listing. | |
 
 ### `social x`
 
@@ -101,58 +126,94 @@ scope (see [Account safety](#account-safety)).
 | `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 followers` | List a user's followers. | |
+| `users following` | List accounts a user follows. | |
+| `whoami` | Show the authenticated X profile. | |
+| `users me` | Same profile read as `whoami`. | |
 | `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. | |
+| `dms list` | List recent DM events. | |
+| `dms messages` | List DM events for a conversation. | |
+| `dms with` | List one-to-one DM events with a user. | |
+| `dms get` | Fetch a DM event. | |
+| `dms start` | Start a DM conversation. | ✎ write |
+| `dms send` | Send a DM to a participant or conversation. | ✎ 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 flags across networks.** `--limit`, `--cursor`, `--account`, and
+  `--no-cache` behave consistently on LinkedIn and X.
 - **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 \
+social linkedin search posts "AI infra hiring" \
   | jq -r '.posts[].urn' \
-  | xargs -I{} social linkedin posts reactions {} --json \
+  | xargs -I{} social linkedin posts reactions {} \
   | jq -s '[.[].reactions[] | {actor, type}]
             | group_by(.actor.id)
             | map({actor: .[0].actor, 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 auth login`, or re-login with 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 auth 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; pass `--scope read` to grant read-only access.
+2. Shows you a verification code and approval URL, then tries to open that URL
+   in your browser.
+3. Waits until you approve the session in the browser.
+4. 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 logout` revokes the session and removes the stored token from both places.
+`social auth logout` revokes the session and removes the stored token from both places.
+`social auth login` requires an interactive terminal and is not supported from CI,
+background jobs, or agent-mediated setup flows.
 
-For non-interactive use (CI, agents), pass the details up front:
+## Cache config
+
+Allowlisted GET requests use a local proxy cache. The CLI sends
+`Cache-Control: max-age=<seconds>` on API requests from your local config:
 
 ```sh
-social login --email you@example.com --scope read,write --accept-pricing --json
+social config cache mode                  # read the current cache mode and TTL
+social config cache mode live             # 15 minutes, default
+social config cache mode analytical       # 24 hours
+social config cache mode historical       # 1 week
+social 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 `--no-cache` when you
+need to bypass cached reads and refresh the stored response.
+
 ## 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.** Pass `--scope read` when you want a
+  read-only session that can't post, react, or invite.
 - **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.
 - **A residential IP per account.** Each connected account runs over a dedicated
@@ -162,24 +223,27 @@ 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 whoami
 
 # X
-social x search recent "from:elonmusk" --pretty
-social x bookmarks list --limit 50 --json
+social x search recent "from:elonmusk"
+social x bookmarks list <my-x-user-id> --limit 50
+social x users followers <x-user-id> --limit 100
+social x users following <x-user-id> --limit 100
+social x dms list --limit 50
 
 # Usage / billing
-social usage --summary --platform linkedin --pretty
+social usage --summary --platform linkedin
 social usage --limit 20 --from 2026-05-01T00:00:00Z
 
 # Agent manifest
-social schema --pretty
+social schema
 ```
 
 ## 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/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 };