botparty 0.0.40 → 0.0.42

package/README.md

@@ -1,6 +1,33 @@
 # botparty
 
-CLI for [BotParty](https://botparty.club) — federated bot identity, authentication, and payments.
+The agent-era CLI for services, APIs, and credentials.
+
+BotParty lets any machine interact with hundreds of services without human interaction, and with all other APIs without ever touching credentials.
+
+## What BotParty gives you
+
+**1. BotParty services** — Managed infrastructure with no account creation.
+Create databases, deploy apps, register domains, provision servers — all from the CLI. Your machine gets its own namespace and authenticates with a keypair. No signups, no dashboards, no humans needed.
+
+```bash
+botparty services mongo databases.create --slug my-db
+botparty mongo databases.list                # shorthand works too
+```
+
+**2. Pay-as-you-go APIs** — Hundreds of APIs including all x402-compatible servers. No crypto wallet on your machine, no API keys to manage. BotParty handles payment and auth through its credit system.
+
+```bash
+botparty curl https://api.example.com/generate -X POST -d '{"prompt":"hello"}'
+```
+
+**3. Any other API in the world** — BotParty proxies the call through Keychains, which handles credentials so your machine never sees them. Need OAuth tokens? API keys? A human gets a secure link to enter credentials once, and your machine uses them forever.
+
+```bash
+botparty curl https://api.github.com/user/repos
+# → If credentials are needed, you get a URL for a human to authorize
+```
+
+---
 
 ## Install
 
@@ -11,54 +38,150 @@ npm install -g botparty
 ## Quick Start
 
 ```bash
-# Just run it — no setup needed
+# Just use it — no setup needed
 botparty curl https://api.example.com/data
+
+# Create a MongoDB database
+botparty mongo databases.create --slug my-db
+
+# Deploy a website
+botparty services deploy projects.deploy --projectName my-site --file ./dist/
 ```
 
-That's it. On first run, BotParty automatically:
+On first run, BotParty automatically generates an Ed25519 keypair, registers a namespace (like `brave-fox-a3f2`), signs a JWT, and sends the authenticated request. No configuration required.
 
-1. Generates an Ed25519 keypair
-2. Registers a namespace like `brave-fox-a3f2`
-3. Signs a JWT and sends the authenticated request
+---
+
+## How Auth Works
+
+Each machine gets a **self-assigned namespace**, authenticated by an Ed25519 keypair stored at `~/.botparty/`.
 
-### How it works
+**Key rotation protects against theft.** Keys must be rotated before a TTL expires. If two machines try to rotate the same key, the namespace locks automatically — an attacker who steals your key can't silently use it because rotation will trigger a conflict. A locked namespace requires human intervention to unlock.
+
+**Namespace linking** connects a machine to a human account. Run `botparty link` to generate a URL — give it to your human, they click it, and your namespace is linked to their account. This enables billing, permissions, and human-in-the-loop approval flows.
 
 ```
-botparty curl <url>
-   │
-   ├── Not registered? → auto-register namespace + keypair
-   ├── Key going stale? → auto-rotate
-   ├── Sign JWT → send request with Authorization: Bearer <jwt>
-   │
-   └── Error? → typed output with action URLs
-       ├── 423: "Namespace locked — unlock at: https://..."
-       ├── 402: "Payment required — top up at: https://..."
-       └── 403: "Missing scopes" or "Link a human account at: https://..."
+~/.botparty/
+├── identity.json    Namespace, key ID, algorithm, rotation info
+└── private.pem      Ed25519 private key (mode 0600)
 ```
 
 ---
 
-## Commands
+## `botparty curl`
 
-### Identity
+A curl replacement that handles auth automatically. If the server you're calling uses BotParty for auth, the request goes directly to the server with a signed JWT. Otherwise, BotParty proxies the call through Keychains, which handles credentials (OAuth, API keys, pay-as-you-go billing) on your behalf.
 
 ```bash
-botparty init [namespace]        # Register (auto-generates name if omitted)
-botparty init my-bot --ttl 30   # Custom namespace, 30min key rotation
-botparty whoami                  # Show current identity
-botparty info [namespace]        # Show namespace info from server
-botparty link                    # Generate URL for a human to claim ownership
-botparty reset                   # Clear local state
-botparty destroy --yes           # Destroy namespace (irreversible)
+botparty curl <url> [options]
 ```
 
-### Authenticated Requests
+Your machine never touches third-party credentials. If the target API requires credentials you haven't set up yet, you'll get a URL for a human to authorize access in a secure environment.
+
+### Options
+
+All standard curl flags are supported (`-X`, `-H`, `-d`, `-F`, `-o`, `-v`, `-i`, `-s`, `-L`, etc).
+
+BotParty-specific options:
+
+| Flag | Description |
+|------|-------------|
+| `--wait-on-authlink` | If credentials are needed, wait for human approval then retry |
+| `--wait-timeout <s>` | Max seconds to wait for approval |
+
+### Examples
 
 ```bash
+# Simple GET
 botparty curl https://api.example.com/data
-botparty curl https://api.example.com -X POST -d '{"key":"val"}'
+
+# POST with JSON
+botparty curl https://api.example.com/items -X POST --json '{"name":"widget"}'
+
+# With custom headers
 botparty curl https://api.example.com -H "X-Custom: value"
+
+# Wait for human approval if credentials are needed
+botparty curl https://api.stripe.com/v1/charges --wait-on-authlink
+
+# Generate a raw JWT token (for use in scripts)
+botparty token
+```
+
+---
+
+## `botparty services`
+
+Discover and invoke actions on any BotParty-compatible service. Services publish a manifest at `/.well-known/botparty/services.json` describing their available actions, parameters, and payment requirements.
+
+```bash
+botparty services <domain> [action] [--params]
+```
+
+Use a shorthand like `mongo` (resolves to `mongo.botparty.club`) or any full domain. Omit the action to list everything the service offers.
+
+### Available services
+
+| Shorthand | Domain | What it does |
+|-----------|--------|-------------|
+| `mongo` | `mongo.botparty.club` | MongoDB databases — create, manage credentials, backups |
+| `git` | `git.botparty.club` | Git repositories — create, push/pull, token management |
+| `s3` | `s3.botparty.club` | S3 storage — buckets, presigned URLs, IAM credentials |
+| `deploy` | `deploy.botparty.club` | Deployments — deploy to Vercel with no account needed |
+| `domains` | `domains.botparty.club` | Domains — register domains, configure DNS records |
+| `upstash` | `upstash.botparty.club` | Upstash — Redis, Vector indices, QStash queues |
+| `vps` | `vps.botparty.club` | VPS — bare-metal servers, SSH sessions, command exec |
+| `vms` | `vms.botparty.club` | VMs — Docker containers with persistent storage |
+
+### Root-level shortcuts
+
+You can skip `services` entirely. If BotParty doesn't recognize a command, it checks whether `<command>.botparty.club` is a valid service:
+
+```bash
+botparty mongo databases.list            # same as: botparty services mongo databases.list
+botparty deploy projects.deploy --projectName my-site --file ./dist/
+```
+
+### Examples
+
+```bash
+# Discover all actions on a service
+botparty services mongo
+
+# List your databases
+botparty services mongo databases.list
+
+# Create a database
+botparty services mongo databases.create --slug my-db
+
+# Create and push to a git repo
+botparty services git repos.create --name my-project
+
+# Deploy a website
+botparty services deploy projects.deploy --projectName my-site --file ./dist/
+
+# Register a domain
+botparty services domains domains.check --domain example.com
+
+# Use any BotParty-compatible service
+botparty services custom-service.example.com
+```
+
+---
+
+## Commands Reference
+
+### Identity
+
+```bash
+botparty init [namespace]        # Register (auto-generates name if omitted)
+botparty init my-bot --ttl 30    # Custom namespace, 30min key rotation
+botparty whoami                  # Show current identity
+botparty info [namespace]        # Show namespace info from server
+botparty link                    # Generate URL for a human to claim ownership
 botparty token                   # Print a signed JWT to stdout
+botparty reset                   # Clear local state
+botparty destroy --yes           # Destroy namespace (irreversible)
 ```
 
 ### Key Management
@@ -75,6 +198,22 @@ botparty keys delete <keyId> --yes
 botparty keys invalidate <keyId> --yes   # Panic button — locks namespace
 ```
 
+### Invites and Dependents
+
+```bash
+botparty invites create --scopes "read,write" --expires 24h
+botparty invites list
+botparty dependents list
+botparty dependents revoke <tokenId> --yes
+```
+
+### Connections
+
+```bash
+botparty connections list              # List credential connections
+botparty connections delete <id> --yes # Remove a connection
+```
+
 ---
 
 ## Global Options
@@ -83,21 +222,11 @@ botparty keys invalidate <keyId> --yes   # Panic button — locks namespace
 |------|-------------|---------|-------------|
 | `--server <url>` | `BOTPARTY_SERVER_URL` | `https://id.botparty.club` | BotParty server URL |
 | `--state-dir <path>` | `BOTPARTY_STATE_DIR` | `~/.botparty` | Local state directory |
+| `--proxy-url <url>` | `BOTPARTY_PROXY_URL` | `https://keychains.dev` | Credential proxy URL |
 | `--json` | — | — | Machine-readable JSON output |
 
 ---
 
-## Local Storage
-
-All state is stored in `~/.botparty/`:
-
-| File | Contents |
-|------|----------|
-| `identity.json` | Namespace, key ID, algorithm, rotation info |
-| `private.pem` | Ed25519 private key (mode 0600) |
-
----
-
 ## License
 
 MIT