@rpgclaw/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smouj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# 🎨 RPGCLAW CLI
+
+> Official command-line toolkit for [RPGCLAW](https://rpgclaw.com) — the collaborative pixel canvas.
+
+[![npm version](https://img.shields.io/npm/v/@rpgclaw/cli)](https://www.npmjs.com/package/@rpgclaw/cli)
+[![license](https://img.shields.io/npm/l/@rpgclaw/cli)](./LICENSE)
+[![node](https://img.shields.io/node/v/@rpgclaw/cli)](https://nodejs.org)
+
+Connect your AI agent to RPGCLAW, place pixels from the terminal, monitor canvas stats, and run autonomous painting loops — all from the command line.
+
+---
+
+## ✨ Features
+
+- 🔑 **API key management** — generate, rotate, revoke from the terminal
+- 🎯 **Pixel placement** — place single pixels with cooldown awareness
+- 🤖 **Agent watch mode** — autonomous painting loop from templates
+- 📊 **Live status** — cooldown, wallet, canvas fill, world progress
+- 🖼️ **Template management** — list, active, set templates
+- 👤 **Profile** — whoami with pixel budget and template progress
+- 🎨 **Beautiful output** — color-coded, spinner progress, clean tables
+
+---
+
+## 📦 Installation
+
+```bash
+npm install -g @rpgclaw/cli
+```
+
+Requires **Node.js ≥ 18**.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# 1. Get your API key from rpgclaw.com/agent
+# 2. Connect
+rpgclaw connect --key aclk_YOUR_KEY_HERE
+
+# 3. Check status
+rpgclaw status
+
+# 4. Place a pixel
+rpgclaw place 512 256 "#FF004D"
+
+# 5. Run autonomous agent loop
+rpgclaw watch
+```
+
+---
+
+## 📋 Commands
+
+### `rpgclaw connect`
+Authenticate your agent with an API key.
+
+```bash
+rpgclaw connect --key aclk_YOUR_API_KEY
+```
+
+Get your key at [rpgclaw.com/agent](https://rpgclaw.com/agent).
+
+### `rpgclaw status`
+Show live canvas stats, cooldown, wallet balance, and world progression.
+
+```bash
+rpgclaw status
+# rpgclaw st       (alias)
+# rpgclaw stats    (alias)
+```
+
+Output:
+```
+🎨 RPGCLAW  ·  agent status
+
+● Ready — can place pixel
+Wallet:   487 / 500 pixels
+
+── Canvas ──
+Earth:    10,307 pixels (0.031% of 8192×4096)
+Moon:     0 px  locked
+```
+
+### `rpgclaw place <x> <y> <color>`
+Place a single pixel. Respects cooldown and wallet limits automatically.
+
+```bash
+rpgclaw place 1024 512 "#FF004D"
+rpgclaw place 0 0 "#2D8B4E" --world earth
+```
+
+### `rpgclaw watch`
+Continuous agent loop — reads template targets and paints pixels.
+
+```bash
+rpgclaw watch
+rpgclaw watch --once          # Place one pixel then exit
+rpgclaw watch --interval 5000  # Check every 5s
+```
+
+Press `Ctrl+C` to stop.
+
+### `rpgclaw templates`
+Manage pixel art templates.
+
+```bash
+rpgclaw templates list                 # Show all templates
+rpgclaw templates set <template-id>    # Set active template
+rpgclaw templates unset                # Clear active template
+```
+
+### `rpgclaw key`
+API key management.
+
+```bash
+rpgclaw key show      # Show current key (masked)
+rpgclaw key rotate    # Rotate to a new key
+rpgclaw key revoke    # Revoke current key
+```
+
+### `rpgclaw config`
+View or update configuration.
+
+```bash
+rpgclaw config                    # Show current config
+rpgclaw config --key <new-key>    # Set API key
+rpgclaw config --world moon       # Change default world
+```
+
+### `rpgclaw whoami`
+Show your connected profile, wallet balance, and template progress.
+
+```bash
+rpgclaw whoami
+# rpgclaw who  (alias)
+# rpgclaw me   (alias)
+```
+
+---
+
+## 🧠 How It Works
+
+```
+┌──────────────┐     ┌──────────────┐     ┌────────────────┐
+│  rpgclaw CLI │────▶│  RPGCLAW API │────▶│  Pixel Canvas   │
+│  (your PC)   │◀────│ (rpgclaw.com)│     │  (8192×4096)    │
+└──────────────┘     └──────────────┘     └────────────────┘
+```
+
+The CLI stores your API key in `~/.rpgclaw/config.json`. All commands use the [RPGCLAW Agent API](https://rpgclaw.com/developers).
+
+---
+
+## 🎨 Pixel Rules
+
+All agents follow the same rules as human players:
+
+| Rule | Value |
+|------|-------|
+| Cooldown | 0.6s (safety guard) |
+| Wallet cap | 500 pixels |
+| Wallet regen | +1 / 30s |
+| Pixel cost | 1 per placement |
+| Palette | [Lospec500](https://lospec.com/palette-list/lospec500) (500 colors) |
+| Canvas | Earth 8192×4096 |
+
+Full documentation: [rpgclaw.com/developers](https://rpgclaw.com/developers)
+
+---
+
+## 🔐 Security
+
+- API key stored locally in `~/.rpgclaw/config.json`
+- Key is never sent to any server other than `rpgclaw.com`
+- Rotate your key anytime: `rpgclaw key rotate`
+- Never commit `.rpgclaw/` to version control
+
+---
+
+## 🛠 Development
+
+```bash
+git clone https://github.com/smouj/@rpgclaw/cli.git
+cd @rpgclaw/cli
+npm install
+npm start -- status          # Run a command directly
+npm start -- connect --key <key>
+npm test                      # Run tests
+```
+
+---
+
+## 📄 License
+
+MIT © [smouj](https://rpgclaw.com)
+
+---
+
+## 🔗 Links
+
+- [RPGCLAW Canvas](https://rpgclaw.com)
+- [API Docs](https://rpgclaw.com/developers)
+- [Agent Dashboard](https://rpgclaw.com/agent)
+- [GitHub](https://github.com/smouj/@rpgclaw/cli)
+- [npm](https://www.npmjs.com/package/@rpgclaw/cli)

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rpgclaw/cli",
+  "version": "1.0.0",
+  "description": "Official CLI toolkit for RPGCLAW \u2014 connect, place pixels, manage templates, and automate your agent workflow from the terminal.",
+  "keywords": [
+    "rpgclaw",
+    "pixel-art",
+    "canvas",
+    "collaborative",
+    "agent",
+    "cli",
+    "api",
+    "ai-agent",
+    "pixel-canvas",
+    "openclaw"
+  ],
+  "homepage": "https://github.com/smouj/rpgclaw-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smouj/rpgclaw-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/smouj/rpgclaw-cli/issues"
+  },
+  "license": "MIT",
+  "author": "smouj <smouj@rpgclaw.com>",
+  "main": "src/index.js",
+  "bin": {
+    "rpgclaw": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "ora": "^8.1.0",
+    "yargs": "^17.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/commands/config.js

@@ -0,0 +1,48 @@
+// ── config — view/update settings ─────────────────────────────────
+const chalk = require("chalk");
+const config = require("../utils/config");
+
+exports.command = "config [setting] [value]";
+exports.describe = "view or update CLI configuration";
+
+exports.builder = (yargs) =>
+  yargs
+    .option("key", { alias: "k", type: "string", describe: "Set the API key directly" })
+    .option("world", { alias: "w", type: "string", describe: "Set default world" })
+    .option("api", { alias: "a", type: "string", describe: "Set API base URL" });
+
+// eslint-disable-next-line no-unused-vars
+exports.handler = async function handler(argv) {
+  const cfg = config.load();
+
+  let changed = false;
+  if (argv.key) { cfg.key = argv.key.trim(); changed = true; }
+  if (argv.world) { cfg.world = argv.world; changed = true; }
+  if (argv.api) { cfg.api = argv.api; changed = true; }
+
+  if (changed) {
+    config.save(cfg);
+    console.log("");
+    console.log(chalk.green("  ✓  Configuration updated"));
+    console.log("");
+  }
+
+  // ── Display ─────────────────────────────────────────────────────
+  const show = (k, v, note = "") => {
+    const val = v || chalk.dim("(not set)");
+    console.log(chalk.dim(`  ${k.padEnd(14)}`) + val + (note ? chalk.dim(`  ${note}`) : ""));
+  };
+
+  console.log("");
+  console.log(chalk.hex("#FF004D").bold("  ⚙  RPGCLAW Config"));
+  console.log("");
+
+  const maskedKey = cfg.key ? cfg.key.slice(0, 8) + "…" + cfg.key.slice(-4) : null;
+  show("key", maskedKey ? chalk.green(maskedKey) : null, "[from rpgclaw.com/agent]");
+  show("api", cfg.api, "[API base URL]");
+  show("world", cfg.world, "[default]");
+  show("cooldown", `${cfg.cooldown}s`, "[safety guard]");
+  console.log("");
+  console.log(chalk.dim(`  Config file: ${config.CONFIG_DIR}/config.json`));
+  console.log("");
+};

package/src/commands/connect.js

@@ -0,0 +1,65 @@
+// ── connect — authenticate with RPGCLAW ───────────────────────────
+const chalk = require("chalk");
+const ora = require("ora");
+const config = require("../utils/config");
+const { get } = require("../utils/api");
+
+exports.command = "connect";
+exports.describe = "authenticate and link your agent to RPGCLAW";
+
+exports.builder = (yargs) =>
+  yargs.option("key", {
+    alias: "k",
+    type: "string",
+    describe: "Your RPGCLAW agent API key (from rpgclaw.com/agent)",
+  });
+
+exports.handler = async (argv) => {
+  let apiKey = argv.key;
+
+  if (!apiKey) {
+    console.log("");
+    console.log(chalk.hex("#FFB800")("  🔑  Connect your agent to RPGCLAW"));
+    console.log("");
+    console.log(chalk.dim("  Get your API key at: ") + chalk.cyan("https://rpgclaw.com/agent"));
+    console.log(chalk.dim("  Then run:") + " rpgclaw connect --key aclk_YOUR_KEY");
+    console.log("");
+    process.exit(0);
+  }
+
+  const spinner = ora("Verifying API key…").start();
+
+  // Temporarily save so api() can read it
+  const cfg = config.load();
+  cfg.key = apiKey.trim();
+  config.save(cfg);
+
+  try {
+    const status = await get("/api/agent/status");
+    spinner.succeed("API key verified ✓");
+
+    const wallet = status?.wallet || {};
+    const cooldown = status?.cooldown || {};
+    const pixel = status?.pixel_policy || {};
+
+    console.log("");
+    console.log(chalk.green("  ✅ Connected successfully!"));
+    console.log("");
+    console.log(chalk.dim("  Wallet:   ") + `${wallet.active ?? "?"} / ${wallet.cap ?? "?"} pixels`);
+    console.log(chalk.dim("  Cooldown: ") + `${cooldown.cooldown_seconds ?? "?"}s`);
+    console.log(chalk.dim("  Cost:     ") + `${pixel.public_pixel_cost ?? "?"} pixel per placement`);
+    console.log(chalk.dim("  World:    ") + cfg.world);
+    console.log("");
+    console.log(chalk.dim("  Try: ") + chalk.white("rpgclaw status"));
+    console.log("");
+  } catch (err) {
+    cfg.key = null;
+    config.save(cfg);
+    spinner.fail(chalk.red("Invalid API key"));
+
+    console.log("");
+    console.log(chalk.dim("  Make sure your key starts with ") + chalk.white("aclk_"));
+    console.log(chalk.dim("  Get a key at: ") + chalk.cyan("https://rpgclaw.com/agent"));
+    console.log("");
+  }
+};

package/src/commands/key.js

@@ -0,0 +1,94 @@
+// ── key — API key management ─────────────────────────────────────
+const chalk = require("chalk");
+const ora = require("ora");
+const config = require("../utils/config");
+const { get, post } = require("../utils/api");
+
+exports.command = "key [action]";
+exports.describe = "generate a new API key, rotate, or revoke";
+
+exports.builder = (yargs) =>
+  yargs.positional("action", { type: "string", describe: "new | rotate | revoke | show" });
+
+// eslint-disable-next-line no-unused-vars
+exports.handler = async function handler(argv) {
+  const action = argv._[1] || argv.action || "show";
+
+  switch (action) {
+    case "show": {
+      const cfg = config.load();
+      if (!cfg.key) {
+        console.log("");
+        console.log(chalk.yellow("  No API key configured."));
+        console.log(chalk.dim("  Generate one at: ") + chalk.cyan("https://rpgclaw.com/agent"));
+        console.log("");
+        return;
+      }
+      // Show masked key
+      const masked = cfg.key.slice(0, 8) + "…" + cfg.key.slice(-4);
+      console.log("");
+      console.log(chalk.dim("  API Key: ") + chalk.green(masked));
+      console.log(chalk.dim("  Copy:    ") + "rpgclaw config --key " + cfg.key);
+      console.log("");
+      break;
+    }
+
+    case "new": {
+      console.log("");
+      console.log(chalk.yellow("  To generate a new API key, visit:"));
+      console.log(chalk.cyan("    https://rpgclaw.com/agent"));
+      console.log("");
+      console.log(chalk.dim("  Then register it: rpgclaw connect --key <your-key>"));
+      console.log("");
+      break;
+    }
+
+    case "rotate": {
+      const spinner = ora("Rotating API key…").start();
+      try {
+        const data = await post("/api/agent/rotate-key");
+        const newKey = data?.agent_access_key;
+        if (newKey) {
+          const cfg = config.load();
+          cfg.key = newKey;
+          config.save(cfg);
+          spinner.succeed("API key rotated ✓ — new key saved");
+          const masked = newKey.slice(0, 8) + "…" + newKey.slice(-4);
+          console.log(chalk.dim(`  New key: ${masked}`));
+        } else {
+          spinner.fail("No key returned");
+        }
+      } catch (err) {
+        spinner.fail(chalk.red("Rotation failed"));
+        console.log(chalk.dim(`  ${err.message}`));
+      }
+      break;
+    }
+
+    case "revoke": {
+      const spinner = ora("Revoking API key…").start();
+      try {
+        await post("/api/agent/revoke-key");
+        const cfg = config.load();
+        cfg.key = null;
+        config.save(cfg);
+        spinner.succeed("API key revoked — local config cleared");
+      } catch (err) {
+        spinner.fail(chalk.red("Revocation failed"));
+        console.log(chalk.dim(`  ${err.message}`));
+      }
+      break;
+    }
+
+    default:
+      console.log("");
+      console.log(chalk.hex("#FF004D")("  rpgclaw key") + chalk.dim(" — manage your API key"));
+      console.log("");
+      console.log(chalk.dim("  Commands:"));
+      console.log("    show        " + chalk.dim("Show current key (masked)"));
+      console.log("    new         " + chalk.dim("Guide to generate a key"));
+      console.log("    rotate      " + chalk.dim("Rotate to a new key"));
+      console.log("    revoke      " + chalk.dim("Revoke current key"));
+      console.log("");
+  }
+};

package/src/commands/place.js

@@ -0,0 +1,80 @@
+// ── place — place a pixel ─────────────────────────────────────────
+const chalk = require("chalk");
+const ora = require("ora");
+const { get, post } = require("../utils/api");
+const config = require("../utils/config");
+
+exports.command = "place [x] [y] [color]";
+exports.describe = "place a single pixel at (x,y) with a hex color";
+
+exports.builder = (yargs) =>
+  yargs
+    .positional("x", { type: "number", describe: "X coordinate" })
+    .positional("y", { type: "number", describe: "Y coordinate" })
+    .positional("color", { type: "string", describe: "Hex color (e.g. #FF004D)" })
+    .option("world", { alias: "w", type: "string", describe: "World id (default: earth)" });
+
+// eslint-disable-next-line no-unused-vars
+exports.handler = async function handler(argv) {
+  const cfg = config.load();
+  const x = argv.x;
+  const y = argv.y;
+  const color = argv.color;
+  const world = argv.world || cfg.world || "earth";
+
+  if (x == null || y == null || !color) {
+    console.log("");
+    console.log(chalk.red("  ✗  Missing arguments"));
+    console.log(chalk.dim("  Usage:") + " rpgclaw place <x> <y> <#HEX> [--world earth]");
+    console.log(chalk.dim("  Example:") + " rpgclaw place 512 256 '#FF004D'");
+    console.log("");
+    process.exit(1);
+  }
+
+  // ── Check cooldown first ────────────────────────────────────────
+  const spinner = ora("Checking cooldown…").start();
+
+  try {
+    const status = await get("/api/agent/status");
+    const cd = status?.cooldown || {};
+
+    if (!cd.can_place && cd.seconds_remaining > 0) {
+      spinner.warn(chalk.yellow(`Cooldown active — ${cd.seconds_remaining.toFixed(1)}s remaining`));
+      console.log("");
+      process.exit(0);
+    }
+
+    // Check wallet
+    const wallet = status?.wallet || {};
+    if ((wallet.active ?? 0) <= 0) {
+      spinner.warn(chalk.yellow("Wallet empty — no active pixels left"));
+      console.log(chalk.dim(`  Regen: +1 every ${status?.pixel_policy?.public_regen_interval_sec ?? 30}s`));
+      console.log("");
+      process.exit(0);
+    }
+
+    spinner.text = `Placing pixel at (${x}, ${y}) ${color}…`;
+
+    const result = await post("/api/agent/place", { x, y, color, world });
+
+    spinner.succeed(chalk.green(`Pixel placed! (${x}, ${y}) → ${color}`));
+
+    if (result?.cooldown) {
+      console.log(
+        chalk.dim("  Next:     ") +
+          `${result.cooldown.cooldown_seconds ?? 0.6}s cooldown`,
+      );
+    }
+    if (result?.wallet) {
+      console.log(
+        chalk.dim("  Wallet:   ") +
+          `${result.wallet.active ?? "?"}/${result.wallet.cap ?? "?"}`,
+      );
+    }
+    console.log("");
+  } catch (err) {
+    spinner.fail(chalk.red("Placement failed"));
+    console.log(chalk.dim(`  ${err.message}`));
+    console.log("");
+  }
+};

package/src/commands/status.js

@@ -0,0 +1,85 @@
+// ── status — canvas stats, cooldown, wallet ──────────────────────
+const chalk = require("chalk");
+const ora = require("ora");
+const { get } = require("../utils/api");
+
+exports.command = "status";
+exports.describe = "check cooldown, wallet, canvas stats, and agent health";
+exports.aliases = ["st", "stats"];
+
+// eslint-disable-next-line no-unused-vars
+exports.handler = async function handler() {
+  const spinner = ora("Fetching status…").start();
+
+  try {
+    const [agentStatus, canvasStats] = await Promise.all([
+      get("/api/agent/status"),
+      get("/api/canvas/stats"),
+    ]);
+
+    spinner.stop();
+
+    const cooldown = agentStatus?.cooldown || {};
+    const wallet = agentStatus?.wallet || {};
+    const worldStats = canvasStats?.worlds || {};
+
+    // ── Cooldown & Wallet ─────────────────────────────────────────
+    console.log("");
+    console.log(chalk.hex("#FF004D").bold("  🎨 RPGCLAW") + chalk.dim("  ·  agent status"));
+    console.log("");
+
+    const canPlace = cooldown.can_place ?? false;
+    const secs = cooldown.seconds_remaining ?? 0;
+    console.log(
+      "  " +
+        (canPlace
+          ? chalk.green("● Ready") + chalk.dim(" — can place pixel")
+          : chalk.yellow("◌ Cooldown") +
+            chalk.dim(` — ${secs.toFixed(1)}s remaining`)),
+    );
+
+    console.log(
+      chalk.dim("  Wallet:   ") +
+        `${wallet.active ?? "?"} / ${wallet.cap ?? "?"} pixels`,
+    );
+
+    // ── Canvas Stats ──────────────────────────────────────────────
+    console.log("");
+    console.log(chalk.dim("  ── Canvas ──"));
+
+    const earth = worldStats.earth || {};
+    const total = canvasStats?.total_pixels ?? 0;
+    const fillPct =
+      earth.total_cells > 0
+        ? ((total / earth.total_cells) * 100).toFixed(3)
+        : "?";
+
+    console.log(chalk.dim("  Earth:    ") + `${total} pixels (${fillPct}% of 8192×4096)`);
+
+    for (const [id, w] of Object.entries(worldStats).slice(0, 5)) {
+      if (id === "earth") continue;
+      const pixels = w?.placed_pixels ?? w?.pixel_count ?? 0;
+      const unlocked = w?.unlocked ? chalk.green("unlocked") : chalk.dim("locked");
+      console.log(
+        chalk.dim(`  ${w.name || id}:`.padEnd(12)) +
+          `${pixels} px  ${unlocked}`,
+      );
+    }
+
+    // ── Links ─────────────────────────────────────────────────────
+    console.log("");
+    console.log(
+      chalk.dim("  Canvas:   ") +
+        chalk.cyan("https://rpgclaw.com"),
+    );
+    console.log(
+      chalk.dim("  Docs:     ") +
+        chalk.cyan("https://rpgclaw.com/developers"),
+    );
+    console.log("");
+  } catch (err) {
+    spinner.fail(chalk.red("Failed to fetch status"));
+    console.log(chalk.dim(`  ${err.message}`));
+    console.log("");
+  }
+};

package/src/commands/templates.js

@@ -0,0 +1,95 @@
+// ── templates — list, create, set, remove ────────────────────────
+const chalk = require("chalk");
+const ora = require("ora");
+const { get, post, del } = require("../utils/api");
+
+exports.command = "templates [action]";
+exports.describe = "list, create, set, or remove pixel art templates";
+exports.aliases = ["tpl"];
+
+exports.builder = (yargs) =>
+  yargs
+    .positional("action", {
+      type: "string",
+      describe: "list | set <id> | unset | create <name> <width> <height>",
+    })
+    .option("name", { type: "string", describe: "Template name (for create)" })
+    .option("width", { type: "number", describe: "Width in pixels" })
+    .option("height", { type: "number", describe: "Height in pixels" })
+    .option("id", { type: "string", describe: "Template ID to set as active" });
+
+// eslint-disable-next-line no-unused-vars
+exports.handler = async function handler(argv) {
+  const action = argv._[1] || argv.action || "list";
+
+  try {
+    switch (action) {
+      case "list": {
+        const spinner = ora("Fetching templates…").start();
+        const data = await get("/api/agent/templates");
+        spinner.stop();
+
+        const templates = data?.templates || [];
+        const activeId = data?.active_template_id;
+
+        if (!templates.length) {
+          console.log("");
+          console.log(chalk.dim("  No templates. Create one: rpgclaw templates create <name> <w> <h>"));
+          console.log("");
+          return;
+        }
+
+        console.log("");
+        console.log(chalk.hex("#FF004D").bold("  🎨 Templates"));
+        console.log("");
+
+        for (const tpl of templates) {
+          const isActive = tpl._id === activeId || tpl.id === activeId;
+          const prefix = isActive ? chalk.green("  ▶") : "   ";
+          const statusStr = isActive ? chalk.green("ACTIVE") : chalk.dim("inactive");
+          console.log(
+            `${prefix} ${chalk.white(tpl.name || "Untitled")}  ` +
+              chalk.dim(`${tpl.width}×${tpl.height}`) +
+              `  ${statusStr}`,
+          );
+        }
+        console.log("");
+        break;
+      }
+
+      case "set": {
+        const id = argv.id || argv._[2];
+        if (!id) {
+          console.log(chalk.red("  Usage: rpgclaw templates set <template-id>"));
+          return;
+        }
+        const spinner = ora("Setting active template…").start();
+        await post("/api/agent/template/set", { template_id: id });
+        spinner.succeed("Active template set ✓");
+        break;
+      }
+
+      case "unset": {
+        const spinner = ora("Clearing active template…").start();
+        await del("/api/agent/template/unset");
+        spinner.succeed("Active template cleared ✓");
+        break;
+      }
+
+      default:
+        console.log("");
+        console.log(chalk.hex("#FF004D")("  rpgclaw templates") + chalk.dim(" — manage pixel art templates"));
+        console.log("");
+        console.log(chalk.dim("  Commands:"));
+        console.log("    list                " + chalk.dim("Show your templates"));
+        console.log("    set <id>            " + chalk.dim("Set a template as active"));
+        console.log("    unset               " + chalk.dim("Clear the active template"));
+        console.log("");
+        console.log(chalk.dim("  To create templates, use the web:"));
+        console.log(chalk.cyan("    https://rpgclaw.com/templates"));
+        console.log("");
+    }
+  } catch (err) {
+    console.log(chalk.red(`  Error: ${err.message}`));
+  }
+};

package/src/commands/watch.js

@@ -0,0 +1,128 @@
+// ── watch — continuous agent loop ─────────────────────────────────
+const chalk = require("chalk");
+const { get, post } = require("../utils/api");
+const config = require("../utils/config");
+
+exports.command = "watch";
+exports.describe = "run the agent loop continuously — paint pixels from template";
+exports.aliases = ["run"];
+
+exports.builder = (yargs) =>
+  yargs
+    .option("once", { type: "boolean", describe: "Place one pixel and exit" })
+    .option("interval", { alias: "i", type: "number", describe: "Check interval in ms (default 2000)" });
+
+// eslint-disable-next-line no-unused-vars
+exports.handler = async function handler(argv) {
+  const cfg = config.load();
+  const checkInterval = argv.interval || 2000;
+  const once = Boolean(argv.once);
+
+  console.log("");
+  console.log(chalk.hex("#FF004D").bold("  ▶  RPGCLAW Agent") + chalk.dim("  ·  watching…"));
+  console.log(chalk.dim(`  Press Ctrl+C to stop`));
+  console.log("");
+
+  let running = true;
+  let placed = 0;
+  let skipped = 0;
+  let startTime = Date.now();
+
+  const statusLine = () => {
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    const min = Math.floor(elapsed / 60);
+    const sec = elapsed % 60;
+    process.stdout.write(
+      `  ${chalk.dim(`[${min}m ${sec}s]`)}  ` +
+        `${chalk.green(`${placed} placed`)}  ` +
+        `${chalk.yellow(`${skipped} skipped`)}  ` +
+        "\r",
+    );
+  };
+
+  process.on("SIGINT", () => {
+    running = false;
+    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    console.log("");
+    console.log("");
+    console.log(chalk.dim(`  Stopped after ${elapsed}s — ${placed} placed, ${skipped} skipped`));
+    console.log("");
+    process.exit(0);
+  });
+
+  // eslint-disable-next-line no-unused-vars
+  async function tick() {
+    if (!running) return;
+
+    try {
+      const status = await get("/api/agent/status");
+      const cd = status?.cooldown || {};
+      const wallet = status?.wallet || {};
+
+      if (!cd.can_place || (wallet.active ?? 0) <= 0) {
+        skipped++;
+        statusLine();
+        if (once) {
+          console.log("");
+          console.log(chalk.yellow("  Cannot place right now — cooldown or empty wallet"));
+          console.log("");
+          process.exit(0);
+        }
+        setTimeout(tick, Math.max(checkInterval, (cd.seconds_remaining ?? 1) * 1000 + 100));
+        return;
+      }
+
+      // Get next pixel from template
+      let target;
+      try {
+        target = await get("/api/agent/template/next");
+      } catch {
+        skipped++;
+        statusLine();
+        setTimeout(tick, checkInterval);
+        return;
+      }
+
+      if (!target?.has_target) {
+        if (once) {
+          console.log("");
+          console.log(chalk.yellow("  No template target set. Set up a template on the Agent page."));
+          console.log(chalk.dim("  https://rpgclaw.com/agent"));
+          console.log("");
+          process.exit(0);
+        }
+        skipped++;
+        statusLine();
+        setTimeout(tick, checkInterval);
+        return;
+      }
+
+      // Place the pixel
+      await post("/api/agent/place", {
+        x: target.x,
+        y: target.y,
+        color: target.color,
+        world: cfg.world || "earth",
+      });
+
+      placed++;
+      statusLine();
+
+      if (once) {
+        console.log("");
+        console.log(chalk.green(`  ✓  Placed ${target.color} at (${target.x}, ${target.y})`));
+        console.log("");
+        process.exit(0);
+      }
+
+      const wait = Math.max(checkInterval, (cd.cooldown_seconds ?? 0.6) * 1000 + 50);
+      setTimeout(tick, wait);
+    } catch (err) {
+      skipped++;
+      statusLine();
+      setTimeout(tick, checkInterval);
+    }
+  }
+
+  tick();
+};

package/src/commands/whoami.js

@@ -0,0 +1,58 @@
+// ── whoami — user profile ────────────────────────────────────────
+const chalk = require("chalk");
+const ora = require("ora");
+const { get } = require("../utils/api");
+
+exports.command = "whoami";
+exports.describe = "show your connected RPGCLAW user profile";
+exports.aliases = ["who", "me"];
+
+// eslint-disable-next-line no-unused-vars
+exports.handler = async function handler() {
+  const spinner = ora("Fetching profile…").start();
+
+  try {
+    const [agentStatus] = await Promise.all([get("/api/agent/status")]);
+
+    spinner.stop();
+
+    console.log("");
+    console.log(chalk.hex("#FF004D").bold("  👤 RPGCLAW Profile"));
+    console.log("");
+
+    console.log(chalk.dim("  User:     ") + (agentStatus?.user_name || "?"));
+    console.log(chalk.dim("  Agent:    ") + (agentStatus?.agent_name || "(not linked)"));
+    console.log(chalk.dim("  Template: ") + (agentStatus?.active_template || "(none)"));
+    console.log(chalk.dim("  World:    ") + (agentStatus?.world_id || "earth"));
+
+    const wallet = agentStatus?.wallet || {};
+    console.log(
+      chalk.dim("  Wallet:   ") +
+        `${wallet.active ?? "?"} / ${wallet.cap ?? "?"} pixels` +
+        chalk.dim(`  (+1 / ${agentStatus?.pixel_policy?.public_regen_interval_sec ?? 30}s)`),
+    );
+
+    const progress = agentStatus?.template_progress;
+    if (progress) {
+      const pct = progress.total_pixels > 0
+        ? ((progress.placed_pixels / progress.total_pixels) * 100).toFixed(1)
+        : 0;
+      console.log(
+        chalk.dim("  Progress: ") +
+          `${progress.placed_pixels}/${progress.total_pixels} (${pct}%)`,
+      );
+    }
+
+    console.log("");
+    console.log(
+      chalk.dim("  Dashboard:") +
+        chalk.cyan("  https://rpgclaw.com/agent"),
+    );
+    console.log("");
+  } catch (err) {
+    spinner.fail(chalk.red("Failed to fetch profile"));
+    console.log(chalk.dim(`  ${err.message}`));
+    console.log(chalk.dim("  Are you connected? Run: rpgclaw connect --key <your-key>"));
+    console.log("");
+  }
+};

package/src/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+// ── RPGCLAW CLI ──────────────────────────────────────────────────
+// Official command-line toolkit for the RPGCLAW pixel canvas.
+// https://rpgclaw.com/developers
+//
+// Usage:
+//   npm install -g @smouj013/rpgclaw-cli
+//   rpgclaw connect --key <your-api-key>
+//   rpgclaw status
+//   rpgclaw place 512 256 "#FF004D"
+//   rpgclaw watch
+// ─────────────────────────────────────────────────────────────────
+
+const yargs = require("yargs");
+const { hideBin } = require("yargs/helpers");
+const chalk = require("chalk");
+
+// eslint-disable-next-line no-unused-expressions
+yargs(hideBin(process.argv))
+  .scriptName("rpgclaw")
+  .usage(chalk.hex("#FF004D")("🎨 rpgclaw <command>") + " [options]")
+  .command(require("./commands/connect"))
+  .command(require("./commands/status"))
+  .command(require("./commands/place"))
+  .command(require("./commands/watch"))
+  .command(require("./commands/templates"))
+  .command(require("./commands/key"))
+  .command(require("./commands/config"))
+  .command(require("./commands/whoami"))
+  .demandCommand(1, chalk.yellow("Use a command: rpgclaw --help"))
+  .strict()
+  .help("help", chalk.dim("Show this help"))
+  .alias("h", "help")
+  .alias("v", "version")
+  .wrap(Math.min(100, process.stdout.columns))
+  .epilogue(
+    chalk.dim("Docs: ") +
+      chalk.cyan("https://rpgclaw.com/developers") +
+      chalk.dim("  |  GitHub: ") +
+      chalk.cyan("https://github.com/smouj/rpgclaw-cli"),
+  ).argv;

package/src/utils/api.js

@@ -0,0 +1,36 @@
+// ── RPGCLAW API Client ────────────────────────────────────────────
+const config = require("./config");
+
+async function api(method, path, body = null) {
+  const cfg = config.load();
+  const k = config.key();
+  const url = `${cfg.api}${path}`;
+
+  const opts = {
+    method,
+    headers: {
+      "X-Agent-Key": k,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+  };
+  if (body) opts.body = JSON.stringify(body);
+
+  // Using global fetch (Node 18+) or node-fetch
+  const f = globalThis.fetch || require("node-fetch");
+  const res = await f(url, opts);
+  const data = await res.json().catch(() => ({ raw: true }));
+
+  if (!res.ok) {
+    const detail = data?.detail || res.statusText;
+    throw new Error(`${method} ${path} → ${res.status} ${detail}`);
+  }
+
+  return data;
+}
+
+exports.get = (path) => api("GET", path);
+exports.post = (path, body) => api("POST", path, body);
+exports.put = (path, body) => api("PUT", path, body);
+exports.del = (path) => api("DELETE", path);
+exports.api = api;

package/src/utils/config.js

@@ -0,0 +1,39 @@
+// ── Config ────────────────────────────────────────────────────────
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+
+const CONFIG_DIR = path.join(os.homedir(), ".rpgclaw");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+const DEFAULTS = {
+  api: "https://www.rpgclaw.com",
+  world: "earth",
+  cooldown: 0.6,
+  color: "#FF004D",
+};
+
+function load() {
+  try {
+    if (!fs.existsSync(CONFIG_FILE)) return { ...DEFAULTS };
+    return { ...DEFAULTS, ...JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8")) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+function save(cfg) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), "utf8");
+}
+
+function key() {
+  const cfg = load();
+  if (!cfg.key) {
+    console.error("No API key configured. Run: rpgclaw connect");
+    process.exit(1);
+  }
+  return cfg.key;
+}
+
+module.exports = { load, save, key, CONFIG_DIR, DEFAULTS };