@reepl/cli 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# Reepl CLI
+
+`reepl` — a command-line interface for Reepl. Create, schedule, and manage LinkedIn / X /
+Reddit content, carousels, signals, DMs, and writing styles from your terminal or an agent.
+
+Built LLM-first: every command emits a stable JSON envelope (`{ ok, data }` /
+`{ ok, error: { code } }`), auto-enabled when output is piped, with distinct exit codes per
+error class so scripts and agents can branch without parsing prose.
+
+## Architecture
+
+- **`src/core`** — `@reepl/api-core`, an environment-agnostic client for `api.reepl.io/v1`.
+  Owns endpoint shapes, Cognito token refresh, workspace scoping, and typed errors. It is
+  the same contract the Reepl MCP server uses internally, and is designed to be extracted
+  to its own npm package so both surfaces share one source of truth.
+- **`src/cli`** — the `reepl` binary: config/token storage, browser login, output
+  rendering, and one command module per resource.
+
+## Auth
+
+`reepl login` opens your browser to the Reepl web app, which hands back Cognito tokens to a
+localhost loopback listener. Tokens are stored in `~/.reepl/credentials.json` (0600) and
+refreshed automatically (public Cognito client, no secret). Headless:
+`reepl login --token <idToken> --refresh <refreshToken>`.
+
+## Commands
+
+```
+# Auth & workspace
+reepl login | logout | whoami
+reepl workspace list | switch <id> | current
+
+# Posts (LinkedIn + X)  --platform linkedin|x
+reepl post create -c "..." [--draft | --schedule <iso> | --publish] [--title t] [--media a,b]
+reepl post list [--status scheduled|published|drafts] [--search q] [--limit n]
+reepl post update <id> [-c "..."] [--schedule <iso>] [--draft]
+reepl post delete <id> [--draft]
+
+# Calendar (scheduled across platforms)
+reepl calendar [--platform linkedin|x|all]
+
+# Comment / reply by URL or id (auto-routes LinkedIn / X / Reddit)
+reepl comment <urlOrId> -t "..."         # or --url; --platform to force
+
+# Reddit
+reepl reddit search <keyword>            # Pro plan
+reepl reddit reply <urlOrId> -t "..."
+reepl reddit status
+
+# Signals inbox
+reepl signals list
+
+# Carousels
+reepl carousel list | get <id> | delete <id>
+reepl carousel create --title t --slides '[{"headline":"..","body":".."}]'
+reepl carousel update <id> [--title t] [--slides <json>] [--theme x]
+reepl carousel generate --topic "..." [--slides n]
+
+# Writing styles (workspace-scoped; train is Pro+)
+reepl style get
+reepl style set --facet posts -i "..."
+reepl style train --facet posts
+reepl style test --facet posts -i "..."
+
+# Voice profile
+reepl voice get
+reepl voice update --file profile.json | --active | --inactive
+
+# X DMs & reply (Premium)
+reepl dm list | messages <id> | refresh
+reepl dm reply <conversationId> -t "..."
+reepl x reply <tweetUrlOrId> -t "..."
+
+# Agent discovery
+reepl schema            # full command/flag tree as JSON
+```
+
+Every command accepts `--json` (auto-enabled when piped) and exits non-zero with a typed
+`error.code` on failure (`UNAUTHENTICATED`, `PLAN_REQUIRED`, `PREMIUM_REQUIRED`, ...).
+
+### Notes / limits
+- **LinkedIn comments** address Reepl-tracked posts by their Reepl post id, not arbitrary
+  public LinkedIn URLs (use the Chrome extension for those). Reddit and X comment/reply
+  work for any post by URL.
+- **Reddit post creation** is intentionally out of scope for v1 (no backend endpoint);
+  Reddit is reply + search only.
+
+## Develop
+
+```bash
+npm install
+npm test            # unit tests (fast, hermetic — mocked fetch)
+npm run test:e2e    # end-to-end: real binary vs a mock Reepl server
+npm run test:all    # both
+npm run typecheck   # tsc --noEmit
+npm run build       # tsup -> dist/
+node dist/cli/index.js --help
+```
+
+Testing is documented in [TESTING.md](TESTING.md) — including the e2e TDD harness
+(`MockReeplServer` + `runCli`) for driving the real CLI in a red/green loop.
+
+Installing the package prints a branded Reepl screen (postinstall); a bare `reepl`
+shows it too.