@alva-ai/toolkit 0.1.3 → 0.2.0

package/dist/cli.js

@@ -11,6 +11,14 @@ var AlvaError = class extends Error {
     this.status = status;
   }
 };
+var CliUsageError = class extends Error {
+  command;
+  constructor(message, command) {
+    super(message);
+    this.name = "CliUsageError";
+    this.command = command;
+  }
+};
 
 // src/resources/fs.ts
 var FsResource = class {
@@ -200,6 +208,23 @@ var DeployResource = class {
       `/api/v1/deploy/cronjob/${params.id}/resume`
     );
   }
+  async listRuns(params) {
+    this.client._requireAuth();
+    return this.client._request(
+      "GET",
+      `/api/v1/deploy/cronjob/${params.cronjob_id}/runs`,
+      {
+        query: { first: params.first, cursor: params.cursor }
+      }
+    );
+  }
+  async getRunLogs(params) {
+    this.client._requireAuth();
+    return this.client._request(
+      "GET",
+      `/api/v1/deploy/cronjob/${params.cronjob_id}/runs/${params.run_id}/logs`
+    );
+  }
 };
 
 // src/resources/release.ts
@@ -391,10 +416,88 @@ var UserResource = class {
   }
 };
 
+// src/resources/trading.ts
+var TradingResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async accounts() {
+    this.client._requireAuth();
+    return this.client._request("GET", "/api/v1/trading/accounts");
+  }
+  async portfolio(accountId) {
+    this.client._requireAuth();
+    return this.client._request("GET", "/api/v1/trading/portfolio", {
+      query: { accountId }
+    });
+  }
+  async orders(params) {
+    this.client._requireAuth();
+    return this.client._request("GET", "/api/v1/trading/orders", {
+      query: {
+        accountId: params.accountId,
+        source: params.source,
+        since: params.since,
+        limit: params.limit
+      }
+    });
+  }
+  async subscriptions(accountId) {
+    this.client._requireAuth();
+    return this.client._request("GET", "/api/v1/trading/subscriptions", {
+      query: { accountId }
+    });
+  }
+  async equityHistory(params) {
+    this.client._requireAuth();
+    return this.client._request("GET", "/api/v1/trading/equity-history", {
+      query: {
+        accountId: params.accountId,
+        timeframe: params.timeframe,
+        sinceMs: params.sinceMs,
+        untilMs: params.untilMs
+      }
+    });
+  }
+  async riskRules() {
+    this.client._requireAuth();
+    return this.client._request(
+      "GET",
+      "/api/v1/trading/risk-rules"
+    );
+  }
+  async subscribe(params) {
+    this.client._requireAuth();
+    return this.client._request("POST", "/api/v1/trading/subscribe", {
+      body: params
+    });
+  }
+  async unsubscribe(subscriptionId) {
+    this.client._requireAuth();
+    return this.client._request("POST", "/api/v1/trading/unsubscribe", {
+      body: { subscriptionId }
+    });
+  }
+  async execute(params) {
+    this.client._requireAuth();
+    return this.client._request("POST", "/api/v1/trading/execute", {
+      body: params
+    });
+  }
+  async updateRiskRules(rules) {
+    this.client._requireAuth();
+    return this.client._request("PUT", "/api/v1/trading/risk-rules", {
+      body: rules
+    });
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api-llm.prd.alva.ai";
 var AlvaClient = class {
   baseUrl;
+  token;
   apiKey;
   _fs;
   _run;
@@ -406,8 +509,10 @@ var AlvaClient = class {
   _remix;
   _screenshot;
   _user;
+  _trading;
   constructor(config) {
     this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.token = config.token;
     this.apiKey = config.apiKey;
   }
   get fs() {
@@ -440,11 +545,14 @@ var AlvaClient = class {
   get user() {
     return this._user ??= new UserResource(this);
   }
+  get trading() {
+    return this._trading ??= new TradingResource(this);
+  }
   _requireAuth() {
-    if (!this.apiKey) {
+    if (!this.token && !this.apiKey) {
       throw new AlvaError(
         "UNAUTHENTICATED",
-        "API key is required for this operation. Pass apiKey in the constructor.",
+        "Authentication is required. Pass token or apiKey in the constructor.",
         401
       );
     }
@@ -464,7 +572,9 @@ var AlvaClient = class {
       }
     }
     const headers = {};
-    if (this.apiKey) {
+    if (this.token) {
+      headers.Authorization = `${this.token}`;
+    } else if (this.apiKey) {
       headers["X-Alva-Api-Key"] = this.apiKey;
     }
     let fetchBody;
@@ -596,16 +706,16 @@ function parseFlag(argv, flag) {
   return void 0;
 }
 function loadConfig(deps) {
-  const { argv, env, readFile: readFile2, homedir: homedir2 } = deps;
+  const { argv, env, readFile: readFile3, homedir: homedir3 } = deps;
   const profileName = parseFlag(argv, "--profile") || env.ALVA_PROFILE || "default";
   const baseUrlFlag = parseFlag(argv, "--base-url");
   const baseUrlEnv = env.ALVA_ENDPOINT;
   const apiKeyFlag = parseFlag(argv, "--api-key");
   const apiKeyEnv = env.ALVA_API_KEY;
   let fileProfile = {};
-  const path = configPath({ env, homedir: homedir2 });
+  const path = configPath({ env, homedir: homedir3 });
   try {
-    const raw = readFile2(path);
+    const raw = readFile3(path);
     let config;
     try {
       config = readConfigFile(raw);
@@ -625,11 +735,135 @@ function loadConfig(deps) {
   };
 }
 
-// src/cli/index.ts
-import * as fs from "fs";
+// src/cli/auth.ts
+import * as crypto from "crypto";
+import * as http from "http";
+import { exec } from "child_process";
 import * as os from "os";
 import * as fsPromises from "fs/promises";
-var CLI_VERSION = true ? "0.1.3" : "dev";
+function generateState() {
+  return crypto.randomBytes(32).toString("hex");
+}
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx !== -1) {
+        flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+        flags[arg.slice(2)] = argv[i + 1];
+        i++;
+      }
+    }
+  }
+  return flags;
+}
+function defaultOpenBrowser(url) {
+  return new Promise((resolve) => {
+    const platform = process.platform;
+    let cmd;
+    if (platform === "darwin") {
+      cmd = `open "${url}"`;
+    } else if (platform === "win32") {
+      cmd = `start "${url}"`;
+    } else {
+      cmd = `xdg-open "${url}"`;
+    }
+    exec(cmd, () => {
+      resolve();
+    });
+  });
+}
+function defaultDeps() {
+  return {
+    generateState,
+    openBrowser: defaultOpenBrowser,
+    writeConfigDeps: {
+      env: process.env,
+      homedir: () => os.homedir(),
+      mkdir: (path, options) => fsPromises.mkdir(path, options).then(() => void 0),
+      writeFile: (path, data, options) => fsPromises.writeFile(path, data, options).then(() => void 0),
+      readFile: (path) => fsPromises.readFile(path, "utf-8")
+    },
+    createServer: (handler) => http.createServer(handler),
+    timeout: 12e4,
+    log: (msg) => process.stderr.write(msg)
+  };
+}
+async function handleAuthLogin(args, deps) {
+  const d = { ...defaultDeps(), ...deps };
+  const flags = parseFlags(args.slice(1));
+  const profileName = flags.profile || "default";
+  const authUrl = flags["auth-url"] || "https://alva.ai";
+  const timeout = d.timeout ?? 12e4;
+  const state = d.generateState();
+  return new Promise((resolve, reject) => {
+    const server = d.createServer((req, res) => {
+      const reqUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (reqUrl.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+      const callbackState = reqUrl.searchParams.get("state");
+      const apiKey = reqUrl.searchParams.get("api_key");
+      if (callbackState !== state) {
+        res.writeHead(400);
+        res.end(
+          "<html><body><h1>Error</h1><p>State mismatch. Please try again.</p></body></html>"
+        );
+        return;
+      }
+      if (!apiKey) {
+        res.writeHead(400);
+        res.end(
+          "<html><body><h1>Error</h1><p>Missing API key. Please try again.</p></body></html>"
+        );
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(
+        `<html><body style="display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:rgba(246,246,246,1);font-family:system-ui,sans-serif"><div style="text-align:center;display:flex;flex-direction:column;align-items:center;gap:40px"><h1 style="font-size:45px;font-weight:400;line-height:120%;margin:0">Turn Ideas into Live<br>Investing Playbooks in Minutes</h1><p style="font-size:24px;font-weight:400;margin:0">You're all set for Alva.</p></div></body></html>`
+      );
+      server.close();
+      clearTimeout(timer);
+      writeConfig({ apiKey }, d.writeConfigDeps, profileName).then(() => {
+        resolve({ status: "logged_in", apiKey, profile: profileName });
+      }, reject);
+    });
+    server.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const callbackUrl = `http://127.0.0.1:${addr.port}/callback`;
+      const loginUrl = `${authUrl}/authorize?callback_url=${encodeURIComponent(callbackUrl)}&state=${state}`;
+      d.log(
+        `Opening browser...
+If it doesn't open, visit:
+${loginUrl}
+
+Waiting for login callback...
+`
+      );
+      d.openBrowser(loginUrl).catch(() => {
+      });
+    });
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new Error("Login timed out waiting for callback"));
+    }, timeout);
+  });
+}
+
+// src/cli/index.ts
+import * as fs from "fs";
+import * as os2 from "os";
+import * as fsPromises2 from "fs/promises";
+var CLI_VERSION = true ? "0.2.0" : "dev";
 function isVersionOlderThan(a, b) {
   const parse = (v) => {
     if (!v) return null;
@@ -661,6 +895,8 @@ Commands:
   sdk         SDK documentation (doc, partitions, partition-summary)
   comments    Playbook comments (create, pin, unpin)
   remix       Save playbook remix lineage
+  trading     Trading operations (accounts, portfolio, orders, subscriptions, equity-history, risk-rules, subscribe, unsubscribe, execute, update-risk-rules)
+  auth        Authentication (login via browser)
   screenshot  Capture a web screenshot as PNG
 
 Global options:
@@ -704,6 +940,14 @@ Examples:
   alva configure --api-key alva_abc123 --base-url http://localhost:8080
   alva configure --profile staging --api-key alva_stg_key --base-url https://api-llm.stg.alva.ai
   alva --profile staging whoami`,
+  auth: `Usage: alva auth <subcommand>
+
+Subcommands:
+  login       Open browser to authenticate and save credentials
+
+Examples:
+  alva auth login
+  alva auth login --profile staging`,
   whoami: `Usage: alva whoami [--profile <name>]
 
 Verify that your credentials are valid by calling the Alva API. Shows your
@@ -791,11 +1035,13 @@ data SDKs, ALFS, HTTP networking, and the Feed SDK.
 
 Options:
   --code <code>          Inline JavaScript code to execute
+  --local-file <path>    Path to a local file whose contents are sent as code
   --entry-path <path>    Path to a script file on ALFS (home-relative)
   --working-dir <dir>    Working directory for require() (inline code only)
   --args <json>          JSON object passed to require("env").args
 
-At least one of --code or --entry-path is required.
+At least one of --code, --local-file, or --entry-path is required.
+These three options are mutually exclusive.
 
 Response fields:
   result    JSON-encoded return value of the script
@@ -822,7 +1068,8 @@ Examples:
   alva run --code "1 + 2 + 3;"
   alva run --code "JSON.stringify(require('env').args);" --args '{"symbol":"BTC"}'
   alva run --entry-path ~/feeds/my-feed/v1/src/index.js
-  alva run --entry-path ~/tasks/analyze/src/index.js --args '{"symbol":"NVDA","limit":50}'`,
+  alva run --entry-path ~/tasks/analyze/src/index.js --args '{"symbol":"NVDA","limit":50}'
+  alva run --local-file ./my-script.js --args '{"symbol":"BTC"}'`,
   deploy: `Usage: alva deploy <subcommand> [options]
 
 Manage scheduled cronjobs that run your scripts on a cron schedule.
@@ -871,7 +1118,10 @@ Examples:
   alva deploy update --id 42 --cron "0 */2 * * *" --no-push-notify
   alva deploy pause --id 42
   alva deploy resume --id 42
-  alva deploy delete --id 42`,
+  alva deploy delete --id 42
+  alva deploy runs --id 42
+  alva deploy runs --id 42 --first 10
+  alva deploy run-logs --id 42 --run-id 123`,
   release: `Usage: alva release <subcommand> [options]
 
 Publish feeds and playbooks to the Alva platform. The typical workflow:
@@ -1032,15 +1282,79 @@ Optional:
 
 Examples:
   alva screenshot --url /playbook/alice/btc-dashboard --out dashboard.png
-  alva screenshot --url /playbook/alice/btc-dashboard --out chart.png --selector ".chart-container"`
+  alva screenshot --url /playbook/alice/btc-dashboard --out chart.png --selector ".chart-container"`,
+  trading: `Usage: alva trading <subcommand> [options]
+
+Manage trading accounts, portfolios, orders, subscriptions, and risk rules.
+
+Subcommands:
+  accounts             List all trading accounts
+  portfolio            Get portfolio for an account
+  orders               List orders for an account
+  subscriptions        List subscriptions for an account
+  equity-history       Get equity history for an account
+  risk-rules           Show risk rules
+  subscribe            Subscribe an account to a source feed
+  unsubscribe          Unsubscribe by subscription ID
+  execute              Execute a signal on an account
+  update-risk-rules    Update risk rules
+
+Portfolio/Orders/Subscriptions/Equity-history flags:
+  --account-id <id>    Trading account ID (required)
+
+Orders optional flags:
+  --limit <n>          Max results
+  --source <source>    Filter by source
+  --since <timestamp>  Filter orders since timestamp
+
+Equity-history optional flags:
+  --timeframe <tf>     Timeframe (e.g. "1d", "1h")
+  --since-ms <ms>      Start timestamp in ms
+  --until-ms <ms>      End timestamp in ms
+
+Subscribe flags:
+  --account-id <id>            Account ID (required)
+  --source-username <user>     Source username (required)
+  --source-feed <feed>         Source feed (required)
+  --playbook-id <id>           Playbook ID (required)
+  --playbook-version <ver>     Playbook version (required)
+  --execute-latest             Execute latest signal on subscribe
+
+Unsubscribe flags:
+  --subscription-id <id>       Subscription ID (required)
+
+Execute flags:
+  --account-id <id>            Account ID (required)
+  --signal <json>              Signal JSON (required)
+  --dry-run                    Dry run mode
+  --source-username <user>     Source username (optional)
+  --source-feed <feed>         Source feed (optional)
+
+Update-risk-rules flags:
+  --max-single-order-value <n>       Max single order value (required)
+  --max-single-order-enabled <bool>  Max single order enabled (required)
+  --max-daily-turnover-value <n>     Max daily turnover value (required)
+  --max-daily-turnover-enabled <bool> Max daily turnover enabled (required)
+  --max-daily-orders-value <n>       Max daily orders value (required)
+  --max-daily-orders-enabled <bool>  Max daily orders enabled (required)
+
+Examples:
+  alva trading accounts
+  alva trading portfolio --account-id acc_123
+  alva trading orders --account-id acc_123 --limit 10
+  alva trading subscriptions --account-id acc_123
+  alva trading equity-history --account-id acc_123 --timeframe 1d
+  alva trading risk-rules
+  alva trading subscribe --account-id acc_123 --source-username alice --source-feed btc-signals --playbook-id pb_1 --playbook-version v1.0.0
+  alva trading unsubscribe --subscription-id sub_456
+  alva trading execute --account-id acc_123 --signal '{"symbol":"BTC","side":"buy","qty":0.1}' --dry-run
+  alva trading update-risk-rules --max-single-order-value 10000 --max-single-order-enabled true --max-daily-turnover-value 50000 --max-daily-turnover-enabled true --max-daily-orders-value 100 --max-daily-orders-enabled true`
 };
 async function handleConfigure(args, deps) {
-  const flags = parseFlags(args.slice(1));
+  const flags = parseFlags2(args.slice(1));
   const apiKey = flags["api-key"];
   if (!apiKey) {
-    throw new Error(
-      "--api-key is required. Usage: alva configure --api-key <key> [--base-url <url>] [--profile <name>]"
-    );
+    throw new CliUsageError("--api-key is required", "configure");
   }
   if (!apiKey.startsWith("alva_")) {
     process.stderr?.write?.(
@@ -1053,10 +1367,10 @@ async function handleConfigure(args, deps) {
   if (baseUrl) configInput.baseUrl = baseUrl;
   const writeDeps = deps ?? {
     env: process.env,
-    homedir: () => os.homedir(),
-    mkdir: (path, options) => fsPromises.mkdir(path, options).then(() => void 0),
-    writeFile: (path, data, options) => fsPromises.writeFile(path, data, options).then(() => void 0),
-    readFile: (path) => fsPromises.readFile(path, "utf-8")
+    homedir: () => os2.homedir(),
+    mkdir: (path, options) => fsPromises2.mkdir(path, options).then(() => void 0),
+    writeFile: (path, data, options) => fsPromises2.writeFile(path, data, options).then(() => void 0),
+    readFile: (path) => fsPromises2.readFile(path, "utf-8")
   };
   const result = await writeConfig(configInput, writeDeps, profileName);
   return {
@@ -1070,9 +1384,11 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "recursive",
   "mkdir-parents",
   "push-notify",
-  "help"
+  "help",
+  "execute-latest",
+  "dry-run"
 ]);
-function parseFlags(argv) {
+function parseFlags2(argv) {
   const flags = {};
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -1100,7 +1416,8 @@ function boolFlag(val) {
 function requireFlag(flags, name, command) {
   const val = flags[name];
   if (val === void 0) {
-    throw new Error(`--${name} is required for '${command}'`);
+    const group = command.split(" ")[0];
+    throw new CliUsageError(`--${name} is required for '${command}'`, group);
   }
   return val;
 }
@@ -1108,8 +1425,10 @@ function requireNumericFlag(flags, name, command) {
   const val = requireFlag(flags, name, command);
   const n = Number(val);
   if (Number.isNaN(n)) {
-    throw new Error(
-      `--${name} must be a number for '${command}', got '${val}'`
+    const group = command.split(" ")[0];
+    throw new CliUsageError(
+      `--${name} must be a number for '${command}', got '${val}'`,
+      group
     );
   }
   return n;
@@ -1153,7 +1472,7 @@ async function dispatch(client, args, meta) {
     return result;
   }
   const subcommand = args[1];
-  const flags = parseFlags(
+  const flags = parseFlags2(
     args.slice(
       group === "run" || group === "remix" || group === "screenshot" ? 1 : 2
     )
@@ -1164,11 +1483,13 @@ async function dispatch(client, args, meta) {
   }
   switch (group) {
     case "user":
-      if (!subcommand) throw new Error("Missing subcommand for user");
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for user", "user");
       if (subcommand === "me") return client.user.me();
-      throw new Error(`Unknown subcommand: user ${subcommand}`);
+      throw new CliUsageError(`Unknown subcommand: user ${subcommand}`, "user");
     case "fs": {
-      if (!subcommand) throw new Error("Missing subcommand for fs");
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for fs", "fs");
       switch (subcommand) {
         case "read":
           return client.fs.read({
@@ -1245,18 +1566,33 @@ async function dispatch(client, args, meta) {
             permission: requireFlag(flags, "permission", "fs revoke")
           });
         default:
-          throw new Error(`Unknown subcommand: fs ${subcommand}`);
+          throw new CliUsageError(`Unknown subcommand: fs ${subcommand}`, "fs");
       }
     }
-    case "run":
+    case "run": {
+      const sourceFlags = ["code", "local-file", "entry-path"].filter(
+        (f) => flags[f] !== void 0
+      );
+      if (sourceFlags.length > 1) {
+        throw new CliUsageError(
+          `--${sourceFlags.join(" and --")} are mutually exclusive`,
+          "run"
+        );
+      }
+      let code = flags["code"];
+      if (flags["local-file"]) {
+        code = fs.readFileSync(flags["local-file"], "utf-8");
+      }
       return client.run.execute({
-        code: flags["code"],
+        code,
         entry_path: flags["entry-path"],
         working_dir: flags["working-dir"],
         args: jsonParse(flags["args"])
       });
+    }
     case "deploy": {
-      if (!subcommand) throw new Error("Missing subcommand for deploy");
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for deploy", "deploy");
       switch (subcommand) {
         case "create":
           return client.deploy.create({
@@ -1295,12 +1631,27 @@ async function dispatch(client, args, meta) {
           return client.deploy.resume({
             id: requireNumericFlag(flags, "id", "deploy resume")
           });
+        case "runs":
+          return client.deploy.listRuns({
+            cronjob_id: requireNumericFlag(flags, "id", "deploy runs"),
+            first: num(flags["first"]),
+            cursor: num(flags["cursor"])
+          });
+        case "run-logs":
+          return client.deploy.getRunLogs({
+            cronjob_id: requireNumericFlag(flags, "id", "deploy run-logs"),
+            run_id: requireNumericFlag(flags, "run-id", "deploy run-logs")
+          });
         default:
-          throw new Error(`Unknown subcommand: deploy ${subcommand}`);
+          throw new CliUsageError(
+            `Unknown subcommand: deploy ${subcommand}`,
+            "deploy"
+          );
       }
     }
     case "release": {
-      if (!subcommand) throw new Error("Missing subcommand for release");
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for release", "release");
       switch (subcommand) {
         case "feed":
           return client.release.feed({
@@ -1339,11 +1690,15 @@ async function dispatch(client, args, meta) {
             changelog: requireFlag(flags, "changelog", "release playbook")
           });
         default:
-          throw new Error(`Unknown subcommand: release ${subcommand}`);
+          throw new CliUsageError(
+            `Unknown subcommand: release ${subcommand}`,
+            "release"
+          );
       }
     }
     case "secrets": {
-      if (!subcommand) throw new Error("Missing subcommand for secrets");
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for secrets", "secrets");
       switch (subcommand) {
         case "create":
           return client.secrets.create({
@@ -1366,11 +1721,15 @@ async function dispatch(client, args, meta) {
             name: requireFlag(flags, "name", "secrets delete")
           });
         default:
-          throw new Error(`Unknown subcommand: secrets ${subcommand}`);
+          throw new CliUsageError(
+            `Unknown subcommand: secrets ${subcommand}`,
+            "secrets"
+          );
       }
     }
     case "sdk": {
-      if (!subcommand) throw new Error("Missing subcommand for sdk");
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for sdk", "sdk");
       switch (subcommand) {
         case "doc":
           return client.sdk.doc({
@@ -1383,11 +1742,15 @@ async function dispatch(client, args, meta) {
             partition: requireFlag(flags, "partition", "sdk partition-summary")
           });
         default:
-          throw new Error(`Unknown subcommand: sdk ${subcommand}`);
+          throw new CliUsageError(
+            `Unknown subcommand: sdk ${subcommand}`,
+            "sdk"
+          );
       }
     }
     case "comments": {
-      if (!subcommand) throw new Error("Missing subcommand for comments");
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for comments", "comments");
       switch (subcommand) {
         case "create":
           return client.comments.create({
@@ -1409,7 +1772,10 @@ async function dispatch(client, args, meta) {
             )
           });
         default:
-          throw new Error(`Unknown subcommand: comments ${subcommand}`);
+          throw new CliUsageError(
+            `Unknown subcommand: comments ${subcommand}`,
+            "comments"
+          );
       }
     }
     case "remix":
@@ -1431,10 +1797,124 @@ async function dispatch(client, args, meta) {
       fs.writeFileSync(outFile, buf);
       return { written: outFile, bytes: buf.length };
     }
+    case "trading": {
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for trading", "trading");
+      switch (subcommand) {
+        case "accounts":
+          return client.trading.accounts();
+        case "portfolio":
+          return client.trading.portfolio(
+            requireFlag(flags, "account-id", "trading portfolio")
+          );
+        case "orders":
+          return client.trading.orders({
+            accountId: requireFlag(flags, "account-id", "trading orders"),
+            source: flags["source"],
+            since: num(flags["since"]),
+            limit: num(flags["limit"])
+          });
+        case "subscriptions":
+          return client.trading.subscriptions(
+            requireFlag(flags, "account-id", "trading subscriptions")
+          );
+        case "equity-history":
+          return client.trading.equityHistory({
+            accountId: requireFlag(
+              flags,
+              "account-id",
+              "trading equity-history"
+            ),
+            timeframe: flags["timeframe"],
+            sinceMs: num(flags["since-ms"]),
+            untilMs: num(flags["until-ms"])
+          });
+        case "risk-rules":
+          return client.trading.riskRules();
+        case "subscribe":
+          return client.trading.subscribe({
+            accountId: requireFlag(flags, "account-id", "trading subscribe"),
+            sourceUsername: requireFlag(
+              flags,
+              "source-username",
+              "trading subscribe"
+            ),
+            sourceFeed: requireFlag(flags, "source-feed", "trading subscribe"),
+            playbookId: requireFlag(flags, "playbook-id", "trading subscribe"),
+            playbookVersion: requireFlag(
+              flags,
+              "playbook-version",
+              "trading subscribe"
+            ),
+            executeLatest: boolFlag(flags["execute-latest"])
+          });
+        case "unsubscribe":
+          return client.trading.unsubscribe(
+            requireFlag(flags, "subscription-id", "trading unsubscribe")
+          );
+        case "execute":
+          return client.trading.execute({
+            accountId: requireFlag(flags, "account-id", "trading execute"),
+            signalJson: requireFlag(flags, "signal", "trading execute"),
+            dryRun: boolFlag(flags["dry-run"]) ?? false,
+            sourceUsername: flags["source-username"],
+            sourceFeed: flags["source-feed"]
+          });
+        case "update-risk-rules":
+          return client.trading.updateRiskRules({
+            maxSingleOrder: {
+              value: requireNumericFlag(
+                flags,
+                "max-single-order-value",
+                "trading update-risk-rules"
+              ),
+              enabled: requireFlag(
+                flags,
+                "max-single-order-enabled",
+                "trading update-risk-rules"
+              ) === "true"
+            },
+            maxDailyTurnover: {
+              value: requireNumericFlag(
+                flags,
+                "max-daily-turnover-value",
+                "trading update-risk-rules"
+              ),
+              enabled: requireFlag(
+                flags,
+                "max-daily-turnover-enabled",
+                "trading update-risk-rules"
+              ) === "true"
+            },
+            maxDailyOrders: {
+              value: requireNumericFlag(
+                flags,
+                "max-daily-orders-value",
+                "trading update-risk-rules"
+              ),
+              enabled: requireFlag(
+                flags,
+                "max-daily-orders-enabled",
+                "trading update-risk-rules"
+              ) === "true"
+            }
+          });
+        default:
+          throw new CliUsageError(
+            `Unknown subcommand: trading ${subcommand}`,
+            "trading"
+          );
+      }
+    }
+    case "auth": {
+      const authSub = args[1];
+      if (!authSub || authSub === "--help" || authSub === "-h" || args[2] === "--help" || args[2] === "-h") {
+        return { _help: true, text: COMMAND_HELP.auth };
+      }
+      throw new CliUsageError(`Unknown auth subcommand: '${authSub}'`, "auth");
+    }
     default:
-      throw new Error(
-        `Unknown command: '${group}'. Run 'alva --help' to see available commands.`
-      );
+      throw new CliUsageError(`Unknown command: '${group}'`);
   }
 }
 async function main() {
@@ -1454,11 +1934,28 @@ async function main() {
       process.stdout.write(JSON.stringify(result2, null, 2) + "\n");
       return;
     }
+    if (rawArgs[0] === "auth") {
+      const authSub = rawArgs[1];
+      if (!authSub || authSub === "--help" || authSub === "-h" || rawArgs[2] === "--help" || rawArgs[2] === "-h") {
+        process.stdout.write(`${COMMAND_HELP.auth}
+`);
+        return;
+      }
+      if (authSub === "login") {
+        const result2 = await handleAuthLogin(rawArgs);
+        process.stdout.write(`${JSON.stringify(result2, null, 2)}
+`);
+        return;
+      }
+      process.stdout.write(`${COMMAND_HELP.auth}
+`);
+      return;
+    }
     const config = loadConfig({
       argv: rawArgs,
       env: process.env,
       readFile: (path) => fs.readFileSync(path, "utf-8"),
-      homedir: () => os.homedir()
+      homedir: () => os2.homedir()
     });
     const client = new AlvaClient({
       apiKey: config.apiKey,
@@ -1500,12 +1997,29 @@ async function main() {
       process.stdout.write(JSON.stringify(result, null, 2) + "\n");
     }
   } catch (err) {
-    const error = err instanceof AlvaError ? { code: err.code, message: err.message, status: err.status } : {
-      code: "CLI_ERROR",
-      message: err instanceof Error ? err.message : String(err)
-    };
-    process.stderr.write(JSON.stringify({ error }, null, 2) + "\n");
-    process.exit(1);
+    if (err instanceof CliUsageError) {
+      const help = err.command ? COMMAND_HELP[err.command] : HELP_TEXT;
+      process.stderr.write(`Error: ${err.message}
+`);
+      if (help) process.stderr.write(`
+${help}
+`);
+      process.exit(1);
+    } else if (err instanceof AlvaError) {
+      const error = {
+        code: err.code,
+        message: err.message,
+        status: err.status
+      };
+      process.stderr.write(`${JSON.stringify({ error }, null, 2)}
+`);
+      process.exit(1);
+    } else {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Error: ${message}
+`);
+      process.exit(1);
+    }
   }
 }
 var isDirectRun = typeof process !== "undefined" && process.argv[1] && (process.argv[1].endsWith("cli.mjs") || process.argv[1].endsWith("cli.js") || process.argv[1].endsWith("/alva") || process.argv[1].endsWith("\\alva"));