towns-agent 2.0.4

package/README.md

@@ -0,0 +1,140 @@
+# towns-agent
+
+CLI for creating and managing Towns Protocol bot projects.
+
+## Getting Started
+
+1. **`create`** — Create an app account. This gives you an `APP_ADDRESS` and `APP_PRIVATE_KEY`.
+2. **`init`** — Scaffold a new project. Use the app private key from step 1 to configure your server.
+3. **`setup`** — Once your app server is running, register its webhook URL and notification settings.
+
+## Commands
+
+### `init [project-name]`
+
+Create a new bot project from a template.
+
+```bash
+bun run cli init my-agent
+bun run cli init my-agent --template quickstart
+```
+
+Options:
+
+- `-t, --template <name>` — Template to use (default: `quickstart`)
+
+### `create`
+
+Create a new bot/app account. Prompts interactively for any values not provided as flags.
+
+```bash
+# Interactive
+bun run cli create --ownerPrivateKey 0xac09...
+
+# Non-interactive
+bun run cli create \
+  --ownerPrivateKey 0xac09... \
+  --username my-bot \
+  --displayName "My Bot" \
+  --description "A helpful bot" \
+  --imageUrl https://example.com/avatar.png
+```
+
+Options:
+
+- `-k, --ownerPrivateKey <key>` — Owner private key for authentication
+- `-b, --bearerToken <token>` — Bearer token for authentication (prompted if neither key nor token provided)
+- `-u, --username <name>` — Bot username
+- `-n, --displayName <name>` — Bot display name
+- `-d, --description <text>` — Bot description
+- `-i, --imageUrl <url>` — Bot image URL
+
+Outputs `APP_ADDRESS`, `APP_PRIVATE_KEY`, `APP_PRIVATE_DATA`, and `JWT_SECRET`.
+
+### `setup <appAddress>`
+
+Register a webhook URL and configure notification settings for an app.
+
+```bash
+# Interactive — prompts for webhook URL and notify setting
+bun run cli setup 0xAPP_ADDRESS --ownerPrivateKey 0xac09...
+
+# Non-interactive
+bun run cli setup 0xAPP_ADDRESS \
+  --ownerPrivateKey 0xac09... \
+  --webhookUrl https://example.com/webhook \
+  --notify ALL
+```
+
+Options:
+
+- `-k, --ownerPrivateKey <key>` — Owner private key for authentication
+- `-b, --bearerToken <token>` — Bearer token for authentication (prompted if neither key nor token provided)
+- `-w, --webhookUrl <url>` — Webhook URL to register
+- `--notify <value>` — Notification setting (default: `ALL`)
+  - `ALL` — Forward all messages
+  - `MENTION_REPLY_REACTION` — Forward mentions, replies, and reactions only
+  - `NONE` — Forward no messages
+
+### `metadata <view|update> <appAddress>`
+
+View or update app metadata.
+
+```bash
+# View metadata (no auth required)
+bun run cli metadata view 0xAPP_ADDRESS
+
+# Update interactively
+bun run cli metadata update 0xAPP_ADDRESS --ownerPrivateKey 0xac09...
+
+# Update non-interactively
+bun run cli metadata update 0xAPP_ADDRESS \
+  --ownerPrivateKey 0xac09... \
+  --displayName "New Name" \
+  --description "Updated description"
+```
+
+Options:
+
+- `-k, --ownerPrivateKey <key>` — Owner private key for authentication (required for update)
+- `-b, --bearerToken <token>` — Bearer token for authentication (required for update)
+- `-u, --username <name>` — Username
+- `-n, --displayName <name>` — Display name
+- `-d, --description <text>` — Description
+- `-i, --imageUrl <url>` — Image URL
+- `-a, --avatarUrl <url>` — Avatar URL
+- `-e, --externalUrl <url>` — External URL
+- `-m, --motto <text>` — Motto
+
+### `update`
+
+Update `@towns-labs/*` dependencies and skills to latest versions.
+
+```bash
+bun run cli update
+```
+
+Options:
+
+- `--skip-agents-md` — Skip updating the AGENTS.md file
+
+### `install-skill`
+
+Install Towns Agent Skills into the current project.
+
+```bash
+bun run cli install-skill
+```
+
+## Authentication
+
+Commands that modify app state (`create`, `setup`, `metadata update`) require authentication via one of:
+
+- **`-k, --ownerPrivateKey`** — A hex-encoded private key that owns the app
+- **`-b, --bearerToken`** — A bearer token
+
+If neither flag is provided, the CLI will prompt for a bearer token interactively.
+
+## Global Options
+
+- `-h, --help` — Show help message