@usesocial/cli 0.1.0

package/README.md

@@ -0,0 +1,185 @@
+# @usesocial/cli
+
+**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.
+
+`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
+engaged, find the people worth reaching out to, learn from those who post better,
+keep the funnel warm — becomes something you can hand to the agent you already
+trust with your code.
+
+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
+```
+
+## 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
+```
+
+## What you can hand your agent
+
+Ask in plain language; the agent runs the calls and you stay the decision-maker.
+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` |
+
+## 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.
+
+Commands marked **✎ write** mutate your account and require an explicit write
+scope (see [Account safety](#account-safety)).
+
+### 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 x <…>` | X operations (below). |
+
+### `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. | |
+
+### `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. | |
+
+## 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.
+- **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.
+
+```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})
+            | sort_by(-.signals) | .[0:15]'
+```
+
+## Auth
+
+`social 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
+   `~/.social/credentials.json` (mode `0600`) when no keyring is available.
+
+`social logout` revokes the session and removes the stored token from both places.
+
+For non-interactive use (CI, agents), pass the details up front:
+
+```sh
+social login --email you@example.com --scope read,write --accept-pricing --json
+```
+
+## 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.
+- **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
+  residential proxy with smart rate-limiting, so the network sees a normal session.
+
+## Examples
+
+```sh
+# LinkedIn
+social linkedin search people "founder ai" --limit 10 --pretty
+social linkedin users me --json
+
+# X
+social x search recent "from:elonmusk" --pretty
+social x bookmarks list --limit 50 --json
+
+# Usage / billing
+social usage --summary --platform linkedin --pretty
+social usage --limit 20 --from 2026-05-01T00:00:00Z
+
+# Agent manifest
+social schema --pretty
+```
+
+## Links
+
+- Pricing and limits: <https://socialcli.dev/pricing>
+- Terms: <https://socialcli.dev/terms> · Privacy: <https://socialcli.dev/privacy>
+
+Built by founders with the same distribution problem.

package/bin/social.mjs

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

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };