@agent-wechat/cli 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,197 @@
+# @agent-wechat/cli
+
+Command-line tool for managing agent-wechat containers and interacting with WeChat.
+
+## Install
+
+```bash
+npm install -g @agent-wechat/cli
+```
+
+This installs the `wx` command globally.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) installed and running
+
+`wx up` automatically pulls the Docker image from ghcr.io if it isn't found locally.
+
+> **Note:** agent-wechat requires `SYS_PTRACE` and `seccomp=unconfined` to interact with the WeChat desktop process. It cannot run in serverless or restricted container environments (AWS Fargate, Cloud Run, etc.). Use a VM or bare-metal Docker host.
+
+## Quick Start
+
+```bash
+# Start the container
+wx up
+
+# Check status
+wx status
+
+# Log in (displays QR code in terminal)
+wx auth login
+
+# List chats
+wx chats list
+
+# Send a message
+wx messages send <chatId> --text "Hello"
+```
+
+## Commands
+
+### Container
+
+| Command | Description |
+|---------|-------------|
+| `wx up` | Start the agent-wechat container |
+| `wx down` | Stop and remove the container |
+| `wx logs` | Tail container logs |
+| `wx status` | Show container and login status |
+
+### Auth
+
+| Command | Description |
+|---------|-------------|
+| `wx auth login` | Log in to WeChat (shows QR code) |
+| `wx auth logout` | Log out of WeChat |
+| `wx auth status` | Check login status |
+| `wx auth token` | Show current auth token |
+| `wx auth token --regenerate` | Generate a new auth token |
+
+Login options:
+- `--timeout <seconds>` — login timeout (default: 300)
+- `--new` — switch to a new account instead of existing
+
+### Chats
+
+| Command | Description |
+|---------|-------------|
+| `wx chats list` | List chats from WeChat |
+| `wx chats get <chatId>` | Get details for a specific chat |
+| `wx chats find <name>` | Search chats by display name |
+| `wx chats open <chatId>` | Open a chat in the WeChat UI |
+
+Options: `--limit <n>`, `--offset <n>`, `--json`
+
+### Messages
+
+| Command | Description |
+|---------|-------------|
+| `wx messages list <chatId>` | List messages in a chat |
+| `wx messages send <chatId>` | Send a message |
+| `wx messages media <chatId> <localId>` | Download a media attachment |
+
+Send options:
+- `--text "message"` — send text
+- `--image photo.jpg` — send an image
+- `--file document.pdf` — send a file
+
+Media options:
+- `--output <path>` — save to a specific file path
+
+### Sessions
+
+| Command | Description |
+|---------|-------------|
+| `wx session list` | List all sessions |
+| `wx session create <name>` | Create a new session |
+| `wx session start <id>` | Start a session |
+| `wx session stop <id>` | Stop a session |
+| `wx session delete <id>` | Delete a session |
+
+### Debug
+
+| Command | Description |
+|---------|-------------|
+| `wx screenshot [file]` | Save a screenshot (default: screenshot.png) |
+| `wx a11y` | Dump the accessibility tree (`--format json|aria`) |
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-s, --session <name>` | Use a specific session (default: "default") |
+| `-V, --version` | Show version |
+| `-h, --help` | Show help |
+
+## Configuration
+
+The CLI reads configuration from environment variables and a local token file:
+
+| Source | Description |
+|--------|-------------|
+| `AGENT_WECHAT_URL` | Server URL (default: `http://localhost:6174`) |
+| `AGENT_WECHAT_TOKEN` | Auth token (overrides token file) |
+| `~/.config/agent-wechat/token` | Auto-generated auth token |
+
+The auth token is generated automatically on first run and shared with the container via a read-only volume mount.
+
+## Running the Container
+
+There are two ways to run the agent-wechat container.
+
+> **Note:** agent-wechat requires `SYS_PTRACE` and `seccomp=unconfined` because it uses ptrace to interact with the WeChat desktop process. It cannot run in serverless or restricted container environments (AWS Fargate, Cloud Run, Azure Container Instances, etc.). Use a VM or bare-metal Docker host.
+
+### Option 1: `wx up` (local development)
+
+The simplest way. `wx up` pulls/starts the container with the right flags, volume mounts, and auth token:
+
+```bash
+wx up
+```
+
+This starts a container named `agent-wechat` with:
+- **Port 6174** — REST API (exposed to all interfaces)
+- **Port 5900** — VNC (localhost only — use SSH tunnel for remote access)
+- Persistent volumes for data and WeChat home directory
+- Auth token from `~/.config/agent-wechat/token` (auto-generated on first run)
+
+### Option 2: Docker Compose (production / networked)
+
+For production or when running alongside other services (e.g., OpenClaw), use the `docker-compose.yml` in the repo root as a reference:
+
+```yaml
+services:
+  agent-wechat:
+    image: ghcr.io/thisnick/agent-wechat:latest
+    container_name: agent-wechat
+    security_opt:
+      - seccomp=unconfined
+    cap_add:
+      - SYS_PTRACE
+    ports:
+      - "6174:6174"
+      - "127.0.0.1:5900:5900"
+    volumes:
+      - agent-wechat-data:/data
+      - agent-wechat-home:/home/wechat
+      - ~/.config/agent-wechat/token:/data/auth-token:ro
+    restart: unless-stopped
+
+volumes:
+  agent-wechat-data:
+  agent-wechat-home:
+```
+
+Generate a token before starting:
+
+```bash
+mkdir -p ~/.config/agent-wechat
+openssl rand -hex 32 > ~/.config/agent-wechat/token
+chmod 600 ~/.config/agent-wechat/token
+```
+
+If running alongside OpenClaw on the same Docker network, set `serverUrl` to `http://agent-wechat:6174` in your OpenClaw config.
+
+### Building locally
+
+To build the Docker image from source instead of pulling from ghcr.io:
+
+```bash
+# From the repo root — auto-detects host architecture
+pnpm build:image
+
+# Or specify architecture
+pnpm build:image:arm64
+pnpm build:image:amd64
+```

package/dist/cli.js

@@ -7906,6 +7906,7 @@ import path from "path";
 import { fileURLToPath } from "url";
 var VERSION = "0.1.0";
 var CONTAINER_NAME = "agent-wechat";
+var GHCR_IMAGE = "ghcr.io/thisnick/agent-wechat";
 var DEFAULT_PORT = 6174;
 var VNC_PORT = 5900;
 var __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -7939,9 +7940,7 @@ function getConfig() {
   };
 }
 function getImageTag() {
-  const arch = os.arch();
-  if (arch === "arm64") return "agent-wechat:arm64";
-  return "agent-wechat:amd64";
+  return `${GHCR_IMAGE}:latest`;
 }
 var program2 = new Command();
 program2.name("wx").description("WeChat automation CLI").version(VERSION).option("-s, --session <name>", "Use specified session", "default");
@@ -8438,9 +8437,13 @@ async function cmdUp() {
   try {
     execSync(`docker image inspect ${image}`, { stdio: "ignore" });
   } catch {
-    console.error(`Image ${image} not found.`);
-    console.error(`Run 'pnpm build:image' first to build the image.`);
-    process.exit(1);
+    console.log(`Image ${image} not found locally. Pulling...`);
+    try {
+      execSync(`docker pull ${image}`, { stdio: "inherit" });
+    } catch {
+      console.error(`Failed to pull ${image}. Check your internet connection and Docker setup.`);
+      process.exit(1);
+    }
   }
   const token = ensureToken();
   console.log(`Starting container ${CONTAINER_NAME} from ${image}...`);
@@ -8484,7 +8487,7 @@ Waiting for server to be ready...`);
       await new Promise((r) => setTimeout(r, 1e3));
       process.stdout.write(".");
     }
-    console.log("\nServer did not become ready in time. Check logs with: pnpm cli logs");
+    console.log("\nServer did not become ready in time. Check logs with: wx logs");
   } catch (error) {
     console.error("Failed to start container:", error);
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-wechat/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "wx": "./dist/cli.js"