@whop/cli 0.0.1 → 0.0.3

package/README.md

@@ -1,3 +1,95 @@
-# @whop/cli
+# `@whop/cli`
 
-Reserved package for the official Whop CLI.
+The public Whop CLI — build and manage Whop apps from your terminal. The binary is `whop`.
+
+It is built with [incur](https://www.npmjs.com/package/incur), a TypeScript framework for CLIs that are equally usable by humans and AI agents. Every command gets typed `args`/`options`/`output` schemas, readable help, and — for free — `--llms`, `--format json|toon|yaml|md|jsonl`, `--schema`, plus `whop skills add` / `whop mcp add` for agent discovery.
+
+> Status: **early.** This package will become the public `whop` CLI. The existing internal developer CLI (`infra/localdev`) keeps the `whop` name for now and will later be renamed `whopdev`.
+
+## Develop
+
+```bash
+# from developer-platform/
+pnpm install
+
+# run the CLI from source (no build) via tsx
+pnpm --filter @whop/cli dev --help
+pnpm --filter @whop/cli dev auth status
+```
+
+## Build
+
+```bash
+pnpm --filter @whop/cli build   # tsup -> dist/index.js (executable, ESM)
+node packages/cli/dist/index.js --help
+```
+
+## Try it
+
+```bash
+whop --help                  # human-readable help
+whop auth login --help       # help for a specific command
+whop auth status             # who am I?
+whop auth status --format json   # structured output for scripts/agents
+whop --llms                  # agent-readable command manifest
+```
+
+## Authentication
+
+Log in with a Whop **API key** (create one in your dashboard under **Developer → API keys**). Credentials are stored in your **OS keychain** (macOS Keychain, Windows Credential Manager, libsecret on Linux) — never in a plaintext file. Non-secret profile metadata lives in `~/.config/whop/config.json`.
+
+```bash
+whop login                 # interactive: pick a method, paste your API key
+whop auth login            # same thing
+whop auth status           # who am I? (whoami)
+whop auth list             # list saved profiles
+whop auth switch [name]    # switch the active profile (interactive picker if omitted)
+whop auth logout [name]    # remove a profile (defaults to the active one)
+```
+
+You can keep **multiple profiles** (e.g. one per company) and switch between them. `whop login` derives a profile name from the company; pass `--profile <name>` to choose your own.
+
+### Non-interactive (CI / agents)
+
+Skip the prompts by passing the key as a flag or environment variable:
+
+```bash
+whop auth login --api-key whop_xxx --format json
+WHOP_API_KEY=whop_xxx whop auth login --format json
+```
+
+| Env var | Purpose |
+| --- | --- |
+| `WHOP_API_KEY` | API key for non-interactive login |
+| `WHOP_API_BASE_URL` | Override the Whop API base URL (default `https://api.whop.com/api/v1`) |
+| `WHOP_CONFIG_DIR` | Override the config directory (default `~/.config/whop`, honors `XDG_CONFIG_HOME`) |
+
+## Accounts
+
+Manage Whop accounts (business accounts and connected accounts).
+
+```bash
+whop accounts list                        # list accounts visible to your credential
+whop accounts get <id>                    # retrieve a single account
+whop accounts me                          # retrieve the account for the current API key
+whop accounts create --email x@y.com     # create a connected account
+whop accounts update <id> --title "Acme" # update account fields
+```
+
+An **account** is a Whop company. Business accounts are top-level; connected accounts are child accounts under a parent business API key. See `whop accounts <command> --help` for all available options.
+
+## Adding commands
+
+> The full incur authoring guide is vendored into this package as [`SKILL.md`](./SKILL.md) — the framework reference for command definitions, args/options schemas, output formats, middleware, streaming, and agent discovery. Re-sync it from the [`incur`](https://www.npmjs.com/package/incur) repo when upgrading.
+
+Register new subcommands in `src/index.ts`:
+
+```ts
+cli.command("apps", {
+	description: "List your Whop apps",
+	output: z.object({ apps: z.array(z.object({ id: z.string(), name: z.string() })) }),
+	run() {
+		return { apps: [] };
+	},
+});
+```