@boole-digital/cli 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2026 Boole Digital. All rights reserved.
+
+This software (the "Boole CLI") is proprietary to Boole Digital.
+
+Permission is granted, free of charge, to any person who is an authorized user
+of the Boole service to download, install, and run unmodified copies of the
+Boole CLI solely to access and operate their own Boole trading computer in
+accordance with the Boole Terms of Service.
+
+You may not, except as expressly permitted above: copy, modify, merge, publish,
+redistribute, sublicense, sell, reverse engineer, or create derivative works of
+the Boole CLI, in whole or in part.
+
+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 BOOLE DIGITAL 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.
+
+Trading involves substantial risk of loss. The Boole CLI operates live trading
+systems; you are solely responsible for all activity conducted through it.

package/README.md

@@ -0,0 +1,59 @@
+# @boole-digital/cli
+
+Operate your **Boole trading computer** from the terminal — and let your coding
+agent (**Claude Code**, **Codex**, or **Gemini**) drive it safely.
+
+```bash
+npx @boole-digital/cli login      # sign in (opens your browser)
+npx @boole-digital/cli connect    # connect to your trading computer
+npx @boole-digital/cli init       # scaffold an agent workspace here
+```
+
+Then open the folder in Claude Code, Codex, or Gemini and start working. The
+agent reads the operating rules `init` wrote and creates strategies the right
+way — every one tracked on your Boole dashboard.
+
+## Requirements
+
+- Node.js >= 18 (that's it — SSH is built in, no `expect`/PuTTY needed)
+- A Boole account with onboarding complete (terms + billing) at
+  [trade.boole.markets](https://trade.boole.markets). Your first trading
+  computer is created in the app; after that the CLI can connect and operate it.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `login [--paste]` | Sign in via the browser (`--paste` for manual code entry). |
+| `connect [name]` | Connect to a trading computer; caches access for this machine. |
+| `init [dir] [--force]` | Write `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` so your agent has the rules. |
+| `computers` | List your trading computers. |
+| `status` | Identity + computers + a live snapshot. |
+| `balances [--venue <v>]` | Equity and open positions. |
+| `ssh "<cmd>"` | Run a read-only command on the box. |
+| `logs [name]` | Tail a strategy's logs. |
+| `strategy spawn --template <t.js> --name <n> [--param K=V]...` | Create a tracked strategy through the gateway. |
+| `strategy ls` | List running strategies. |
+| `strategy doctor [name]` | Gateway health + tracking status. |
+| `logout` | Sign out, clear the cached session. |
+
+### Creating a strategy
+
+Strategies are always created through the gateway so they appear on your
+dashboard with full accounting:
+
+```bash
+boole strategy spawn --template loop_template.js --name btc-watch \
+  --param EXCHANGE=hyperliquid --param MARKET=BTC --param POLL_SEC=10
+```
+
+## Notes
+
+- Credentials and SSH access are stored under `~/.boole/` with `0600`
+  permissions and are never logged.
+- Set `BOOLE_API_BASE` to point at a non-production environment.
+
+---
+
+© 2026 Boole Digital. Proprietary — see [LICENSE](./LICENSE). Trading involves
+substantial risk of loss.

package/dist/index.js

@@ -0,0 +1,955 @@
+#!/usr/bin/env node
+import{createRequire as __cr}from'module';const require=__cr(import.meta.url);
+
+// src/login.ts
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+
+// src/config.ts
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  mkdirSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  rmSync
+} from "node:fs";
+var API_BASE = (process.env.BOOLE_API_BASE || "https://trade.boole.markets").replace(/\/+$/, "");
+var CONFIG_DIR = process.env.BOOLE_HOME || join(homedir(), ".boole");
+var CRED_PATH = join(CONFIG_DIR, "credentials.json");
+var SESSION_PATH = join(CONFIG_DIR, "session.env");
+function ensureDir() {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+}
+function saveCredentials(creds) {
+  ensureDir();
+  writeFileSync(CRED_PATH, JSON.stringify(creds, null, 2));
+  chmodSync(CRED_PATH, 384);
+}
+function loadCredentials() {
+  if (!existsSync(CRED_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(CRED_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function clearCredentials() {
+  if (existsSync(CRED_PATH)) rmSync(CRED_PATH);
+}
+function shSingleQuote(v) {
+  return `'${v.replace(/'/g, `'\\''`)}'`;
+}
+function saveSession(s) {
+  ensureDir();
+  const body = [
+    "# Written by `boole connect`. Do not edit by hand; re-run `boole connect` to refresh.",
+    `BOOLE_AGENT=${shSingleQuote(s.agent)}`,
+    `BOOLE_DROPLET_ID=${shSingleQuote(String(s.dropletId))}`,
+    `BOOLE_IP=${shSingleQuote(s.ip)}`,
+    `BOOLE_PASS=${shSingleQuote(s.password)}`,
+    `BOOLE_SSH_USER=${shSingleQuote(s.sshUser || "customer")}`,
+    ""
+  ].join("\n");
+  writeFileSync(SESSION_PATH, body);
+  chmodSync(SESSION_PATH, 384);
+}
+function loadSession() {
+  if (!existsSync(SESSION_PATH)) return null;
+  try {
+    const text = readFileSync(SESSION_PATH, "utf8");
+    const get = (k) => {
+      const m = text.match(new RegExp(`^${k}=(.*)$`, "m"));
+      if (!m) return "";
+      let v = m[1].trim();
+      if (v.startsWith("'") && v.endsWith("'")) v = v.slice(1, -1).replace(/'\\''/g, "'");
+      return v;
+    };
+    const ip = get("BOOLE_IP");
+    if (!ip) return null;
+    return {
+      agent: get("BOOLE_AGENT"),
+      dropletId: get("BOOLE_DROPLET_ID"),
+      ip,
+      password: get("BOOLE_PASS"),
+      sshUser: get("BOOLE_SSH_USER") || "customer"
+    };
+  } catch {
+    return null;
+  }
+}
+function jwtExpiry(token) {
+  try {
+    const payload = token.split(".")[1];
+    const json = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return typeof json.exp === "number" ? json.exp : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// src/ui.ts
+var useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+var wrap = (code) => (s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
+var c = {
+  bold: wrap("1"),
+  dim: wrap("2"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  blue: wrap("34"),
+  cyan: wrap("36")
+};
+var log = (msg = "") => console.log(msg);
+var info = (msg) => console.log(`${c.cyan("\u203A")} ${msg}`);
+var ok = (msg) => console.log(`${c.green("\u2713")} ${msg}`);
+var warn = (msg) => console.log(`${c.yellow("!")} ${msg}`);
+var err = (msg) => console.error(`${c.red("\u2717")} ${msg}`);
+function die(msg) {
+  err(msg);
+  process.exit(1);
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function prompt(question) {
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve2) => {
+    rl.question(`${c.cyan("?")} ${question} `, (ans) => {
+      rl.close();
+      resolve2(ans.trim());
+    });
+  });
+}
+
+// src/login.ts
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
+function decodePayload(code) {
+  const json = Buffer.from(code.trim(), "base64").toString("utf8");
+  const p = JSON.parse(json);
+  if (!p.access_token || !p.user) throw new Error("Malformed login code.");
+  return {
+    access_token: p.access_token,
+    refresh_token: p.refresh_token || "",
+    expires_at: p.expires_at || jwtExpiry(p.access_token),
+    user: p.user
+  };
+}
+function successHtml(email, dashboardUrl) {
+  const who = email ? `<p>Signed in as <b style="color:#eaeaea">${email.replace(/[<>&]/g, "")}</b></p>` : "";
+  const url = dashboardUrl.replace(/"/g, "");
+  return `<!doctype html><meta charset=utf-8><title>Boole</title>
+<style>body{font:16px -apple-system,system-ui,sans-serif;background:#0b0b0b;color:#eaeaea;display:grid;place-items:center;height:100vh;margin:0}div{text-align:center}h1{font-size:22px}p{color:#9a9a9a;margin:6px 0}.btn{display:inline-block;margin-top:18px;padding:10px 20px;border-radius:8px;background:#6d5efc;color:#fff;text-decoration:none;font-weight:600}.btn:hover{background:#5a4ef0}</style>
+<div><h1>\u2713 Signed in to Boole</h1>${who}<p style="color:#34d399;font-weight:600">Your CLI is authenticated.</p><p>You can close this tab now and return to your terminal.</p>
+<a class="btn" href="${url}">See dashboard \u2192</a></div>`;
+}
+function emailFromCode(code) {
+  try {
+    return JSON.parse(Buffer.from(code.trim(), "base64").toString("utf8")).user?.email || "";
+  } catch {
+    return "";
+  }
+}
+async function loginPaste() {
+  const url = `${API_BASE}/cli-auth?paste=1`;
+  info("Opening the Boole login page\u2026");
+  log(`  ${c.dim("If it does not open, visit:")} ${c.cyan(url)}`);
+  openBrowser(url);
+  const code = await prompt("Paste the login code:");
+  if (!code) throw new Error("No code entered.");
+  saveCredentials(decodePayload(code));
+}
+async function loginLoopback() {
+  let resolveCode;
+  let rejectCode;
+  const codePromise = new Promise((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+  const server = createServer((req, res) => {
+    const u = new URL(req.url || "/", "http://127.0.0.1");
+    if (u.pathname !== "/callback") {
+      res.writeHead(200);
+      res.end("boole");
+      return;
+    }
+    const code = u.searchParams.get("token");
+    if (!code) {
+      res.writeHead(400);
+      res.end("missing token");
+      rejectCode(new Error("No token in callback."));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+    res.end(successHtml(emailFromCode(code), API_BASE));
+    queueMicrotask(() => resolveCode(code));
+  });
+  const port = await new Promise((resolve2) => {
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      resolve2(typeof addr === "object" && addr ? addr.port : 0);
+    });
+  });
+  const url = `${API_BASE}/cli-auth?port=${port}`;
+  info("Opening the Boole login page in your browser\u2026");
+  log(`  ${c.dim("If it does not open, visit:")} ${c.cyan(url)}`);
+  openBrowser(url);
+  log(c.dim("  Waiting for you to finish signing in\u2026"));
+  const timeout = setTimeout(() => rejectCode(new Error("Timed out waiting for login (5 min).")), 5 * 6e4);
+  try {
+    const code = await codePromise;
+    clearTimeout(timeout);
+    saveCredentials(decodePayload(code));
+    await sleep(1200);
+  } catch (e) {
+    clearTimeout(timeout);
+    server.close();
+    throw e;
+  }
+  server.close();
+}
+async function login(opts = {}) {
+  try {
+    if (opts.paste) await loginPaste();
+    else await loginLoopback();
+  } catch (e) {
+    if (!opts.paste) warn("Automatic handoff failed \u2014 retry with `boole login --paste`.");
+    throw e;
+  }
+}
+
+// src/agents.ts
+import { randomBytes } from "node:crypto";
+
+// src/api.ts
+var AuthError = class extends Error {
+};
+function unwrap(body) {
+  if (body == null) return body;
+  if (Array.isArray(body)) return body;
+  if (Array.isArray(body.data)) return body.data;
+  if (body.data?.droplets) return body.data.droplets;
+  if (body.droplets) return body.droplets;
+  if (body.data !== void 0) return body.data;
+  return body;
+}
+var BooleApi = class {
+  creds;
+  constructor(creds = loadCredentials()) {
+    this.creds = creds;
+  }
+  get user() {
+    return this.creds?.user ?? null;
+  }
+  get isLoggedIn() {
+    return !!this.creds?.access_token;
+  }
+  setCredentials(creds) {
+    this.creds = creds;
+    saveCredentials(creds);
+  }
+  // Refresh the access token if it's missing/expired (60s skew).
+  async ensureFresh() {
+    if (!this.creds) throw new AuthError("Not logged in. Run `boole login`.");
+    const exp = this.creds.expires_at || jwtExpiry(this.creds.access_token);
+    if (exp && exp - 60 > Date.now() / 1e3) return;
+    if (!this.creds.refresh_token) return;
+    const res = await fetch(`${API_BASE}/api/v1/auth/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refresh_token: this.creds.refresh_token })
+    });
+    if (!res.ok) return;
+    const data = await res.json().catch(() => null);
+    if (data?.success && data.access_token) {
+      const next = {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token || this.creds.refresh_token,
+        expires_at: data.expires_at || jwtExpiry(data.access_token),
+        user: data.user || this.creds.user
+      };
+      this.setCredentials(next);
+    }
+  }
+  async request(path, init2 = {}) {
+    await this.ensureFresh();
+    if (!this.creds) throw new AuthError("Not logged in. Run `boole login`.");
+    const doFetch = () => fetch(`${API_BASE}${path}`, {
+      ...init2,
+      headers: {
+        "Content-Type": "application/json",
+        ...init2.headers || {},
+        Authorization: `Bearer ${this.creds.access_token}`
+      }
+    });
+    let res = await doFetch();
+    if (res.status === 401) {
+      this.creds.expires_at = 0;
+      await this.ensureFresh();
+      res = await doFetch();
+    }
+    if (res.status === 401) {
+      throw new AuthError("Session expired or token was rotated elsewhere. Run `boole login` again.");
+    }
+    const text = await res.text();
+    const body = text ? (() => {
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    })() : null;
+    if (!res.ok) {
+      const msg = body && (body.error || body.message) || `${res.status} ${res.statusText}`;
+      throw new Error(`${path}: ${msg}`);
+    }
+    return body;
+  }
+  // ---- droplets ----------------------------------------------------------
+  async listDroplets() {
+    const body = await this.request("/api/v1/droplets");
+    const list2 = unwrap(body);
+    return Array.isArray(list2) ? list2 : [];
+  }
+  async getDroplet(id) {
+    const body = await this.request(`/api/v1/droplets/${id}`);
+    return unwrap(body);
+  }
+  async createDroplet(input) {
+    const body = await this.request("/api/v1/droplets", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+    return unwrap(body);
+  }
+  // Returns the plaintext SSH password for a droplet. Field name varies by
+  // server version, so probe the likely shapes.
+  async getSshPassword(id) {
+    const body = await this.request(`/api/v1/droplets/${id}/ssh-password`, { method: "POST" });
+    const pw = body?.password ?? body?.ssh_password ?? body?.data?.password ?? body?.data?.ssh_password;
+    if (!pw) throw new Error("SSH password not present in API response (check field name in api.ts:getSshPassword).");
+    return String(pw);
+  }
+  // ---- talk to the gateway on the box (via the ownership-checked proxy) ---
+  // GET a gateway path (e.g. "/health", "/api/venues/hyperliquid/account")
+  // through /api/v1/droplets/:id/proxy/* — the JWT is forwarded and ownership
+  // re-checked server-side.
+  async proxyGet(id, gatewayPath) {
+    const p = gatewayPath.startsWith("/") ? gatewayPath : `/${gatewayPath}`;
+    return this.request(`/api/v1/droplets/${id}/proxy${p}`);
+  }
+  async getHealth(id) {
+    return this.proxyGet(id, "/health");
+  }
+  async getAccount(id, exchange) {
+    return this.proxyGet(id, `/api/venues/${exchange}/account`);
+  }
+};
+
+// src/agents.ts
+import { existsSync as existsSync2, rmSync as rmSync2 } from "node:fs";
+function requireApi() {
+  const api = new BooleApi();
+  if (!api.isLoggedIn) die("Not logged in. Run `boole login` first.");
+  return api;
+}
+var READY = (d) => d.status === "active" && !!d.setup_completed_at;
+function onboardingNotice() {
+  log("");
+  warn("No trading computer yet \u2014 and you can\u2019t deploy your first one from the CLI.");
+  log("  Finish onboarding in the Boole app first (this is required):");
+  log(`    1. Create your account   2. Agree to the terms   3. Set up billing`);
+  log(`    ${c.cyan(API_BASE)}`);
+  log(`  Deploy your first trading computer there, then come back and run ${c.cyan("boole connect")}.`);
+  log("");
+}
+function printAgents(droplets) {
+  if (!droplets.length) {
+    onboardingNotice();
+    return;
+  }
+  const session = loadSession();
+  for (const d of droplets) {
+    const here = session && String(session.dropletId) === String(d.id);
+    const state = READY(d) ? c.green(d.status) : c.yellow(d.status);
+    const ip = d.ip_address || c.dim("(pending)");
+    log(`${here ? c.cyan("\u25CF") : " "} ${c.bold(d.name)}  ${state}  ${ip}  ${c.dim(`id:${d.id}`)}`);
+  }
+}
+async function agents() {
+  const api = requireApi();
+  printAgents(await api.listDroplets());
+}
+function fmtUsd(n) {
+  const v = typeof n === "number" ? n : Number(n);
+  if (!isFinite(v)) return "$0";
+  return `$${v.toLocaleString("en-US", { maximumFractionDigits: 2 })}`;
+}
+function pickAgentId(droplets) {
+  const session = loadSession();
+  if (session?.dropletId) {
+    const d = droplets.find((x) => String(x.id) === String(session.dropletId));
+    return { id: session.dropletId, name: d?.name || session.agent || String(session.dropletId) };
+  }
+  const ready = droplets.filter(READY);
+  if (ready.length === 1) return { id: ready[0].id, name: ready[0].name };
+  return null;
+}
+async function summary() {
+  const creds = loadCredentials();
+  if (!creds) {
+    warn("Not logged in. Run `boole login`.");
+    return;
+  }
+  log("");
+  ok(`Logged in as ${c.bold(creds.user.email || creds.user.id)}${creds.user.role ? c.dim(` \xB7 ${creds.user.role}`) : ""}`);
+  const api = new BooleApi();
+  let droplets = [];
+  try {
+    droplets = await api.listDroplets();
+  } catch (e) {
+    warn(`Could not list trading computers: ${e.message}`);
+    return;
+  }
+  if (!droplets.length) {
+    onboardingNotice();
+    return;
+  }
+  log("");
+  log(c.bold(`Trading computers (${droplets.length})`));
+  printAgents(droplets);
+  const pick = pickAgentId(droplets);
+  if (!pick) return;
+  log("");
+  log(c.bold(`Snapshot \u2014 ${pick.name}`));
+  try {
+    const health = await api.getHealth(pick.id);
+    ok(`online${health.defaultModel ? c.dim(` \xB7 model ${health.defaultModel}`) : ""}`);
+  } catch {
+    warn("trading computer unreachable (tunnel may be waking up \u2014 retry in a moment)");
+    return;
+  }
+  await printBalances(api, pick.id, "hyperliquid");
+}
+async function printBalances(api, id, exchange) {
+  try {
+    const acct = await api.getAccount(id, exchange);
+    const positions = Array.isArray(acct.positions) ? acct.positions : [];
+    info(`${exchange}: equity ${c.bold(fmtUsd(acct.equity))} \xB7 available ${fmtUsd(acct.available)} \xB7 ${positions.length} open position(s)`);
+    for (const p of positions.slice(0, 12)) {
+      log(`    ${c.bold(String(p.market ?? "?"))}  ${p.size ?? ""}`);
+    }
+  } catch (e) {
+    warn(`${exchange} balances unavailable: ${e.message}`);
+  }
+}
+async function status() {
+  await summary();
+}
+async function balances(opts = {}) {
+  const api = requireApi();
+  const droplets = await api.listDroplets();
+  const pick = pickAgentId(droplets);
+  if (!pick) die("No trading computer connected. Run `boole connect` first.");
+  log(c.bold(`${pick.name}`));
+  await printBalances(api, pick.id, opts.venue || "hyperliquid");
+}
+async function logout() {
+  clearCredentials();
+  if (existsSync2(SESSION_PATH)) rmSync2(SESSION_PATH);
+  ok("Logged out.");
+}
+async function provision(opts = {}) {
+  const api = requireApi();
+  const name = opts.name || `computer-${randomBytes(3).toString("hex")}`;
+  info(`Deploying ${c.bold(name)}\u2026`);
+  let d;
+  try {
+    d = await api.createDroplet({ name, region: opts.region, size: opts.size });
+  } catch (e) {
+    err("Could not deploy a trading computer from the CLI.");
+    onboardingNotice();
+    log(c.dim(`  (reason: ${e.message})`));
+    process.exit(1);
+  }
+  log(c.dim(`  Trading computer created (#${d.id}). Waiting for it to come online\u2026`));
+  const deadline = Date.now() + 8 * 6e4;
+  while (Date.now() < deadline) {
+    if (READY(d)) break;
+    if (d.status === "error" || d.status === "failed") die(`Deploy failed: status=${d.status}.`);
+    await sleep(4e3);
+    d = await api.getDroplet(d.id);
+  }
+  if (!READY(d)) die("Timed out waiting for the trading computer to come online. Check `boole computers` shortly.");
+  ok(`Trading computer ${c.bold(name)} is ready.`);
+  await connect({ name });
+}
+async function connect(opts = {}) {
+  const api = requireApi();
+  const droplets = await api.listDroplets();
+  if (!droplets.length) {
+    onboardingNotice();
+    return;
+  }
+  let target;
+  if (opts.name) {
+    target = droplets.find((d) => d.name === opts.name || String(d.id) === opts.name);
+    if (!target) die(`No trading computer named "${opts.name}". Run \`boole computers\` to list them.`);
+  } else {
+    const ready = droplets.filter(READY);
+    if (ready.length === 1) target = ready[0];
+    else {
+      warn("Specify which trading computer: `boole connect <name>`");
+      printAgents(droplets);
+      return;
+    }
+  }
+  if (!READY(target)) die(`Trading computer "${target.name}" is not ready yet (status=${target.status}).`);
+  if (!target.ip_address) die(`Trading computer "${target.name}" has no IP yet. Try again shortly.`);
+  info(`Fetching access for ${c.bold(target.name)}\u2026`);
+  const password = await api.getSshPassword(target.id);
+  saveSession({ agent: target.name, dropletId: target.id, ip: target.ip_address, password, sshUser: "customer" });
+  ok(`Connected to ${c.bold(target.name)} (${target.ip_address}).`);
+  log("");
+  log(`  Scaffold an agent workspace here, then open it:`);
+  log(`    ${c.cyan("boole init")}`);
+  log(`  Open the folder in ${c.bold("Claude Code")}, ${c.bold("Codex")}, or ${c.bold("Gemini")} \u2014 each reads the`);
+  log(`  rules it just wrote (${c.dim("CLAUDE.md / AGENTS.md / GEMINI.md")}) and operates your computer via ${c.cyan("boole")}.`);
+  log(`  Or run a one-off:  ${c.cyan('boole ssh "pm2 list"')}`);
+}
+
+// src/ssh.ts
+import ssh2 from "ssh2";
+var { Client } = ssh2;
+function requireSession() {
+  const s = loadSession();
+  if (!s) die("No active trading computer. Run `boole connect` first.");
+  return s;
+}
+function friendly(e) {
+  const m = e?.message || String(e);
+  if (/All configured authentication methods failed|authentication/i.test(m)) {
+    return "SSH authentication failed \u2014 your access may have rotated. Run `boole connect` again.";
+  }
+  if (/ECONNREFUSED|ETIMEDOUT|EHOSTUNREACH|ENOTFOUND|timed out|Timed out/i.test(m)) {
+    return "Could not reach your trading computer (it may still be waking up). Try again in a moment.";
+  }
+  return `SSH error: ${m}`;
+}
+function open(s) {
+  return new Promise((resolve2, reject) => {
+    const conn = new Client();
+    conn.on("ready", () => resolve2(conn));
+    conn.on("error", (e) => reject(new Error(friendly(e))));
+    conn.connect({
+      host: s.ip,
+      port: 22,
+      username: s.sshUser || "customer",
+      password: s.password,
+      readyTimeout: 25e3,
+      // We connect to the customer's OWN freshly-provisioned box, addressed by
+      // the IP the authenticated Boole API returned for their account. Accept
+      // the host key on first use (parity with the prior transport).
+      hostVerifier: () => true
+    });
+  });
+}
+async function runRemote(command) {
+  const s = requireSession();
+  const conn = await open(s);
+  try {
+    return await new Promise((resolve2, reject) => {
+      conn.exec(command, (err2, stream) => {
+        if (err2) return reject(new Error(friendly(err2)));
+        let stdout = "";
+        let stderr = "";
+        stream.on("close", (code) => resolve2({ code: code ?? 0, stdout, stderr }));
+        stream.on("data", (d) => {
+          stdout += d.toString();
+        });
+        stream.stderr.on("data", (d) => {
+          stderr += d.toString();
+        });
+      });
+    });
+  } finally {
+    conn.end();
+  }
+}
+async function runRemoteInherit(command) {
+  const s = requireSession();
+  const conn = await open(s);
+  try {
+    return await new Promise((resolve2, reject) => {
+      conn.exec(command, (err2, stream) => {
+        if (err2) return reject(new Error(friendly(err2)));
+        stream.on("close", (code) => resolve2(code ?? 0));
+        stream.on("data", (d) => process.stdout.write(d));
+        stream.stderr.on("data", (d) => process.stderr.write(d));
+      });
+    });
+  } finally {
+    conn.end();
+  }
+}
+
+// src/strategy.ts
+var NAME_RE = /^[a-z0-9][a-z0-9_-]{0,48}$/;
+var GATE = "http://localhost:3000";
+function paramLiteral(raw) {
+  const t = raw.trim();
+  if (/^-?\d+(\.\d+)?$/.test(t)) return t;
+  if (t === "true" || t === "false") return t;
+  if (t.startsWith("[") || t.startsWith("{")) return t;
+  return `'${raw.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+function parseParams(pairs) {
+  const out = {};
+  for (const p of pairs) {
+    const i = p.indexOf("=");
+    if (i < 0) die(`Bad --param "${p}" (expected KEY=VALUE).`);
+    const key = p.slice(0, i).trim();
+    if (!/^[A-Z][A-Z0-9_]*$/.test(key)) die(`Bad param key "${key}" (UPPER_SNAKE_CASE).`);
+    out[key] = paramLiteral(p.slice(i + 1));
+  }
+  return out;
+}
+async function strategySpawn(opts) {
+  const template = opts.template;
+  const name = opts.name;
+  if (!template || !name) {
+    die("Usage: boole strategy spawn --template <template.js> --name <name> [--param KEY=VALUE]...");
+  }
+  if (!template.endsWith("_template.js")) die("--template must be a gateway template ending in _template.js (e.g. order_template.js, grid_template.js, loop_template.js).");
+  if (!NAME_RE.test(name)) die(`Invalid --name "${name}". Use lowercase letters, digits, "-" or "_" (max 49 chars).`);
+  const payload = {
+    templateFile: template,
+    name,
+    params: parseParams(opts.params || []),
+    autoStart: opts.autostart !== false
+  };
+  info(`Spawning ${c.bold(name)} from ${c.bold(template)} through the gateway\u2026`);
+  const b64 = Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+  const cmd = `printf %s '${b64}' | base64 -d | curl -s --max-time 60 -XPOST ${GATE}/api/strategy/spawn -H 'content-type: application/json' -d @-`;
+  const r = await runRemote(cmd);
+  let res = null;
+  try {
+    res = JSON.parse(r.stdout.trim());
+  } catch {
+  }
+  if (!res) {
+    err("The gateway did not return a valid response.");
+    if (r.stdout.trim()) log(c.dim(`  ${r.stdout.trim().slice(0, 400)}`));
+    if (r.stderr.trim()) log(c.dim(`  ${r.stderr.trim().slice(0, 200)}`));
+    process.exit(1);
+  }
+  if (res.error || res.ok === false) {
+    err(`Spawn rejected: ${res.error || "unknown error"}`);
+    if (res.suggested_name) log(c.dim(`  Try --name ${res.suggested_name}`));
+    process.exit(1);
+  }
+  ok(`Spawned ${c.bold(name)}${res.runId ? c.dim(` \xB7 run ${res.runId}`) : ""} \u2014 it will appear on your dashboard.`);
+  const dropped = Array.isArray(res.skipped) ? res.skipped.filter((k) => k !== "RUN_ID") : [];
+  if (dropped.length) warn(`Ignored param(s) with no matching template field: ${dropped.join(", ")} \u2014 check the template's required params.`);
+  if (typeof res.placed === "number" || typeof res.total === "number") {
+    info(`Orders placed: ${res.placed ?? 0}/${res.total ?? 0}${res.failed ? c.yellow(` \xB7 ${res.failed} failed`) : ""}`);
+  }
+  if (res.firstError) warn(`First error: ${res.firstError}`);
+}
+async function strategyList() {
+  const r = await runRemote("pm2 jlist 2>/dev/null");
+  let procs = [];
+  try {
+    procs = JSON.parse(r.stdout.trim());
+  } catch {
+  }
+  if (!Array.isArray(procs)) {
+    warn("Could not read process list from the box.");
+    return;
+  }
+  if (!procs.length) {
+    info("No strategies running.");
+    return;
+  }
+  log(c.bold("Strategies"));
+  for (const p of procs) {
+    const st = p.pm2_env?.status || "?";
+    const dot = st === "online" ? c.green("\u25CF") : c.dim("\u25CB");
+    const up = p.pm2_env?.pm_uptime && st === "online" ? c.dim(` \xB7 up ${Math.max(0, Math.round((Date.now() - p.pm2_env.pm_uptime) / 6e4))}m`) : "";
+    const restarts = p.pm2_env?.restart_time ? c.dim(` \xB7 \u21BA${p.pm2_env.restart_time}`) : "";
+    log(`  ${dot} ${c.bold(p.name)}  ${st === "online" ? c.green(st) : c.yellow(st)}${up}${restarts}`);
+  }
+}
+async function strategyDoctor(name) {
+  const health = await runRemote(`curl -sf --max-time 15 ${GATE}/health`);
+  if (health.code !== 0) {
+    err("Gateway is not responding on the box.");
+    return;
+  }
+  ok("Gateway healthy.");
+  if (!name) return;
+  if (!NAME_RE.test(name)) die(`Invalid name "${name}".`);
+  const r = await runRemote("pm2 jlist 2>/dev/null");
+  let procs = [];
+  try {
+    procs = JSON.parse(r.stdout.trim());
+  } catch {
+  }
+  const p = procs.find((x) => x.name === name);
+  if (!p) {
+    warn(`No process named "${name}" \u2014 spawn it with \`boole strategy spawn\`.`);
+    return;
+  }
+  if (p.pm2_env?.status === "online") ok(`${c.bold(name)} is online and tracked \u2014 it will show on the dashboard.`);
+  else {
+    warn(`${c.bold(name)} is ${p.pm2_env?.status || "not online"} \u2014 check \`boole logs ${name}\`.`);
+  }
+}
+
+// src/rules.ts
+import { writeFileSync as writeFileSync2, existsSync as existsSync3, mkdirSync as mkdirSync2 } from "node:fs";
+import { join as join2, resolve } from "node:path";
+var OPERATING_RULES = `# Boole Trading Computer \u2014 Operating Rules (READ FIRST, IN FULL)
+
+You operate a customer's **live** crypto trading computer through the \`boole\` CLI.
+**Real money is at risk.** These are STRICT, NON-NEGOTIABLE rules.
+
+> Why they matter: Boole tracks and controls every strategy by HOW it was created.
+> If you create one any other way \u2014 writing files over SSH, starting processes
+> yourself \u2014 it **silently fails**: it won't register, won't appear on the
+> dashboard, can't be controlled, and may mismanage live positions. There is no
+> error message. When in doubt, STOP and ask the user.
+
+## Boot sequence \u2014 every session, before anything else
+1. \`boole status\` \u2014 confirm you are logged in and a trading computer is connected.
+   If not, STOP and tell the user to run \`boole login\` then \`boole connect\`.
+2. Read this entire file.
+3. \`boole strategy ls\` \u2014 see what is already running.
+
+## The one rule: THINK locally, COMMIT through \`boole\`
+- THINK \u2014 research, analyze data, design, draft code \u2014 freely on this machine. No limits.
+- COMMIT \u2014 anything that changes the trading computer \u2014 ONLY through \`boole\` commands.
+
+## Creating / running a strategy \u2014 the ONLY sanctioned path
+Spawn from a known-good template through the gateway gate:
+
+    boole strategy spawn --template <template.js> --name <name> \\
+      --param KEY=VALUE --param KEY=VALUE ...
+
+- This registers the run and starts it tracked, so it appears on the dashboard.
+- \`--name\`: lowercase letters, digits, "-" or "_" (e.g. btc-grid).
+- \`--param\`: pass raw values (EXCHANGE=hyperliquid, TOTAL_USD=50). The CLI quotes them.
+- Verify: \`boole strategy doctor <name>\` \u2192 should report online and tracked.
+
+### Templates (required params)
+- order_template.js  \u2014 single order: EXCHANGE, MARKET, SIDE(buy|sell), ORDER_TYPE(market|limit), TOTAL_USD, LIMIT_PRICE(0 for market)
+- grid_template.js   \u2014 grid: EXCHANGE, SYMBOL, LEVELS_PER_SIDE, ORDER_SIZE_USD, LEVERAGE, MAX_EXPOSURE_USD
+- twap_template.js   \u2014 TWAP: EXCHANGE, MARKET, SIDE, TOTAL_USD, DURATION_MIN, SLICES
+- scale_template.js  \u2014 ladder: EXCHANGE, MARKET, SIDE, TOTAL_USD, PRICE_LOW, PRICE_HIGH, LEVELS
+- stop_template.js   \u2014 conditional (no position yet): EXCHANGE, MARKET, SIDE, STOP_KIND(stop_market|stop_limit|tp_market|tp_limit), TOTAL_USD, TRIGGER_PRICE, LIMIT_PRICE(0 for *_market)
+- loop_template.js   \u2014 generic poll loop / price watcher: EXCHANGE, MARKET, POLL_SEC
+
+Example:
+
+    boole strategy spawn --template loop_template.js --name btc-watch \\
+      --param EXCHANGE=hyperliquid --param MARKET=BTC --param POLL_SEC=10
+
+If you omit a required param, the gate returns an error naming it \u2014 fix and retry.
+If the gate says a template is not found, it is not installed on this box \u2014 pick
+another from the list or ask the user.
+Only use a template above. Do NOT hand-roll custom strategy files. If you need
+something no template covers, STOP and ask the user.
+
+## Allowed \u2014 read-only inspection
+- \`boole status\` / \`boole balances [--venue <v>]\` \u2014 identity, equity, positions
+- \`boole strategy ls\` \u2014 running strategies
+- \`boole strategy doctor <name>\` \u2014 health + tracking check
+- \`boole logs <name>\` \u2014 tail a strategy's logs
+- \`boole ssh "<read-only command>"\` \u2014 inspect only (cat, ls, pm2 list, curl localhost:3000/health)
+
+## Forbidden
+- Do NOT write strategy or interface files over SSH.
+- Do NOT \`pm2 start/restart/stop/delete\` by hand.
+- Do NOT edit gateway files directly.
+- \`boole ssh\` is for READ-ONLY inspection. To change the box, use a \`boole\` verb.
+- If there is no verb for a change you need, STOP and ask. A missing verb is not permission to freelance.
+
+## Safety (real money)
+- Trading is live. Prefer capital preservation. Confirm exchange state before acting.
+- Never print or exfiltrate .env, API keys, or credentials.
+- Never restart the gateway.
+- Ask the user before destructive actions (closing positions, stopping strategies).
+
+## Notes
+- Some gateway internals are intentionally not readable from your account \u2014 by design. Use the \`boole\` verbs; you don't need them.
+- A commit is not done until \`boole strategy doctor\` confirms it. If it did not register, fix it before moving on.
+`;
+var FILES = ["CLAUDE.md", "AGENTS.md", "GEMINI.md"];
+function init(opts = {}) {
+  const dir = resolve(opts.dir || process.cwd());
+  if (!existsSync3(dir)) mkdirSync2(dir, { recursive: true });
+  let wrote = 0;
+  let skipped = 0;
+  for (const f of FILES) {
+    const p = join2(dir, f);
+    if (existsSync3(p) && !opts.force) {
+      warn(`${f} already exists \u2014 skipped (use --force to overwrite).`);
+      skipped++;
+      continue;
+    }
+    writeFileSync2(p, OPERATING_RULES);
+    wrote++;
+  }
+  log("");
+  if (wrote) ok(`Wrote operating rules (${FILES.join(", ")}) to ${c.bold(dir)}`);
+  else if (skipped) info("All rule files already present \u2014 nothing changed.");
+  log("");
+  log(`  Open ${c.bold(dir)} in ${c.bold("Claude Code")}, ${c.bold("Codex")}, or ${c.bold("Gemini")}.`);
+  log(`  Your agent reads these rules and operates your trading computer through ${c.cyan("boole")}.`);
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+function parse(argv) {
+  const _ = [];
+  const flags = {};
+  const add = (k, v) => {
+    if (k in flags) {
+      const cur = flags[k];
+      flags[k] = Array.isArray(cur) ? [...cur, String(v)] : [String(cur), String(v)];
+    } else flags[k] = v;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      if (key.includes("=")) {
+        const [k, v] = key.split(/=(.*)/s);
+        add(k, v);
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+        add(key, argv[++i]);
+      } else add(key, true);
+    } else _.push(a);
+  }
+  return { _, flags };
+}
+var str = (f) => typeof f === "string" ? f : Array.isArray(f) ? f[f.length - 1] : void 0;
+var list = (f) => f === void 0 ? [] : Array.isArray(f) ? f : typeof f === "string" ? [f] : [];
+var HELP = `${c.bold("boole")} \u2014 operate your Boole trading computer from the terminal.
+
+${c.bold("Usage")}
+  boole <command> [options]
+
+${c.bold("Getting started")}
+  login [--paste]          Sign in (opens the browser; --paste for manual code)
+  provision [--name <n>]   Create a new trading computer (requires app onboarding)
+  connect [name]           Connect to an existing trading computer (caches SSH access)
+  init [dir] [--force]     Scaffold an agent workspace (CLAUDE.md / AGENTS.md / GEMINI.md)
+  computers                List your trading computers
+  status                   Who you are + your trading computers + a live snapshot
+  balances [--venue <v>]   Equity + open positions for the connected trading computer
+  logout                   Sign out and clear the cached session
+
+${c.bold("Operate")}
+  ssh "<command>"          Run a read-only command on the connected box
+  logs [name]              Tail a strategy's logs
+
+${c.bold("Strategies")} ${c.dim("(go through the gateway \u2014 always tracked on the dashboard)")}
+  strategy spawn --template <t.js> --name <n> [--param KEY=VALUE]... [--no-autostart]
+  strategy ls              List running strategies
+  strategy doctor [name]   Gateway health + a strategy's tracking status
+
+${c.bold("Other")}
+  help, --help             Show this help
+  version, --version       Show version
+
+Env: ${c.dim("BOOLE_API_BASE")} (default https://trade.boole.markets), ${c.dim("BOOLE_HOME")}
+`;
+async function main() {
+  const { _, flags } = parse(process.argv.slice(2));
+  const cmd = _[0];
+  if (cmd === "version" || flags.version) {
+    log(`boole ${VERSION}`);
+    return;
+  }
+  if (!cmd || cmd === "help" || flags.help) {
+    log(HELP);
+    return;
+  }
+  switch (cmd) {
+    case "login":
+      await login({ paste: !!flags.paste });
+      await summary();
+      break;
+    case "logout":
+      await logout();
+      break;
+    case "status":
+    case "whoami":
+      await status();
+      break;
+    case "balances":
+    case "balance":
+      await balances({ venue: str(flags.venue) });
+      break;
+    case "computers":
+    case "agents":
+    case "ls":
+      await agents();
+      break;
+    case "provision":
+      await provision({ name: str(flags.name), region: str(flags.region), size: str(flags.size) });
+      break;
+    case "connect":
+      await connect({ name: _[1] });
+      break;
+    case "init":
+      init({ dir: _[1], force: !!flags.force });
+      break;
+    case "ssh": {
+      const command = _.slice(1).join(" ");
+      if (!command) die('Usage: boole ssh "<command>"');
+      process.exit(await runRemoteInherit(command));
+    }
+    case "logs": {
+      const proc = _[1];
+      const remote = proc ? `pm2 logs '${proc.replace(/'/g, "")}' --lines 50 --nostream` : "pm2 logs --lines 40 --nostream";
+      process.exit(await runRemoteInherit(remote));
+    }
+    case "strategy": {
+      const sub = _[1];
+      if (sub === "spawn") {
+        await strategySpawn({
+          template: str(flags.template),
+          name: str(flags.name),
+          params: list(flags.param),
+          autostart: !flags["no-autostart"]
+        });
+      } else if (sub === "ls" || sub === "list") {
+        await strategyList();
+      } else if (sub === "doctor") {
+        await strategyDoctor(_[2]);
+      } else {
+        die("Usage: boole strategy <spawn|ls|doctor> \u2026 (see `boole help`)");
+      }
+      break;
+    }
+    default:
+      err(`Unknown command: ${cmd}`);
+      log(HELP);
+      process.exit(1);
+  }
+}
+main().catch((e) => {
+  err(e?.message || String(e));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@boole-digital/cli",
+  "version": "0.1.0",
+  "description": "Boole — install, sign in, and operate your trading computer from the terminal (Claude Code, Codex, Gemini).",
+  "type": "module",
+  "bin": { "boole": "dist/index.js" },
+  "main": "dist/index.js",
+  "files": ["dist/index.js", "README.md", "LICENSE"],
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": { "node": ">=18" },
+  "repository": { "type": "git", "url": "github:Boole-Digital/portara-desktop" },
+  "homepage": "https://trade.boole.markets",
+  "publishConfig": { "access": "public" },
+  "keywords": ["boole", "trading", "cli", "claude-code", "codex", "gemini"],
+  "dependencies": {
+    "ssh2": "^1.16.0"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js --external:ssh2 --banner:js=\"import{createRequire as __cr}from'module';const require=__cr(import.meta.url);\"",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/ssh2": "^1.15.0",
+    "esbuild": "^0.23.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  }
+}