@alva-ai/toolkit 0.1.4 → 0.2.1

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
@@ -472,7 +497,7 @@ var TradingResource = class {
 var DEFAULT_BASE_URL = "https://api-llm.prd.alva.ai";
 var AlvaClient = class {
   baseUrl;
-  token;
+  viewer_token;
   apiKey;
   _fs;
   _run;
@@ -487,7 +512,7 @@ var AlvaClient = class {
   _trading;
   constructor(config) {
     this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
-    this.token = config.token;
+    this.viewer_token = config.viewer_token;
     this.apiKey = config.apiKey;
   }
   get fs() {
@@ -524,10 +549,10 @@ var AlvaClient = class {
     return this._trading ??= new TradingResource(this);
   }
   _requireAuth() {
-    if (!this.token && !this.apiKey) {
+    if (!this.viewer_token && !this.apiKey) {
       throw new AlvaError(
         "UNAUTHENTICATED",
-        "Authentication is required. Pass token or apiKey in the constructor.",
+        "Authentication is required. Pass viewer_token or apiKey in the constructor.",
         401
       );
     }
@@ -547,8 +572,8 @@ var AlvaClient = class {
       }
     }
     const headers = {};
-    if (this.token) {
-      headers.Authorization = `${this.token}`;
+    if (this.viewer_token) {
+      headers["x-Playbook-Viewer"] = this.viewer_token;
     } else if (this.apiKey) {
       headers["X-Alva-Api-Key"] = this.apiKey;
     }
@@ -681,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);
@@ -710,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.4" : "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.1" : "dev";
 function isVersionOlderThan(a, b) {
   const parse = (v) => {
     if (!v) return null;
@@ -736,17 +885,18 @@ var HELP_TEXT = `Usage: alva <command> [options]
 
 Commands:
   configure   Save API key and endpoint to a named profile
-  whoami      Verify credentials and show current user info
-  user        User profile operations
+  whoami      Verify credentials and show current identity
+  user        User profile operations (me)
   fs          Filesystem operations (read, write, stat, readdir, mkdir, remove, rename, copy, symlink, readlink, chmod, grant, revoke)
   run         Execute code in the Alva runtime
-  deploy      Cronjob management (create, list, get, update, delete, pause, resume)
+  deploy      Cronjob management (create, list, get, update, delete, pause, resume, runs, run-logs)
   release     Feed and playbook releases (feed, playbook-draft, playbook)
   secrets     Secret management (create, list, get, update, delete)
   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)
   screenshot  Capture a web screenshot as PNG
 
 Global options:
@@ -790,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
@@ -829,16 +987,26 @@ Subcommands:
   grant      Grant access permission to a user or group
   revoke     Revoke access permission
 
-Common flags:
-  --path <path>          File or directory path (required for most subcommands)
-  --recursive            Enable recursive operation (readdir, remove)
-  --no-recursive         Disable recursive operation
-  --mkdir-parents        Create parent directories on write (default for write)
-  --no-mkdir-parents     Disable automatic parent directory creation on write
+Subcommand flags:
+  read       --path (required), [--offset <n>], [--size <n>]
+  write      --path (required), --data <text> OR --file <local-path> (one required),
+             [--mkdir-parents | --no-mkdir-parents]
+  stat       --path (required)
+  readdir    --path (required), [--recursive | --no-recursive]
+  mkdir      --path (required)
+  remove     --path (required), [--recursive | --no-recursive]
+  rename     --old-path (required), --new-path (required)
+  copy       --src-path (required), --dst-path (required)
+  symlink    --target-path (required), --link-path (required)
+  readlink   --path (required)
+  chmod      --path (required), --mode <octal> (required)
+  grant      --path (required), --subject <s> (required), --permission <p> (required)
+  revoke     --path (required), --subject <s> (required), --permission <p> (required)
 
 Path conventions:
   ~/...                  Home-relative path (expands to /alva/home/<username>/...)
   /alva/home/alice/...   Absolute path (required for public/unauthenticated reads)
+  Quote tilde paths to prevent shell expansion: --path "~/data" (not --path ~/data).
 
 Time series reads:
   Paths under feed data directories support virtual suffixes:
@@ -854,21 +1022,23 @@ Grant/revoke subjects:
   user:<id>              Specific user by ID
 
 Examples:
-  alva fs readdir --path ~/
-  alva fs readdir --path ~/data --recursive
-  alva fs read --path ~/data/prices.json
-  alva fs read --path ~/feeds/btc-ema/v1/data/metrics/prices/@last/100
+  alva fs readdir --path "~/"
+  alva fs readdir --path "~/data" --recursive
+  alva fs read --path "~/data/prices.json"
+  alva fs read --path "~/feeds/btc-ema/v1/data/metrics/prices/@last/100"
   alva fs read --path /alva/home/alice/feeds/btc-ema/v1/data/metrics/prices/@last/10
-  alva fs write --path ~/hello.txt --data "Hello, world!"
-  alva fs write --path ~/feeds/my-feed/v1/src/index.js --file ./local-script.js --mkdir-parents
-  alva fs stat --path ~/hello.txt
-  alva fs mkdir --path ~/feeds/my-feed/v1/src
-  alva fs remove --path ~/old-folder --recursive
-  alva fs rename --old-path ~/a.txt --new-path ~/b.txt
-  alva fs copy --src-path ~/a.txt --dst-path ~/b.txt
-  alva fs chmod --path ~/script.js --mode 755
-  alva fs grant --path ~/feeds/btc-ema --subject "special:user:*" --permission read
-  alva fs revoke --path ~/feeds/btc-ema --subject "special:user:*" --permission read`,
+  alva fs write --path "~/hello.txt" --data "Hello, world!"
+  alva fs write --path "~/feeds/my-feed/v1/src/index.js" --file ./local-script.js --mkdir-parents
+  alva fs stat --path "~/hello.txt"
+  alva fs mkdir --path "~/feeds/my-feed/v1/src"
+  alva fs remove --path "~/old-folder" --recursive
+  alva fs rename --old-path "~/a.txt" --new-path "~/b.txt"
+  alva fs copy --src-path "~/a.txt" --dst-path "~/b.txt"
+  alva fs chmod --path "~/script.js" --mode 755
+  alva fs grant --path "~/feeds/btc-ema" --subject "special:user:*" --permission read
+  alva fs revoke --path "~/feeds/btc-ema" --subject "special:user:*" --permission read
+  alva fs symlink --target-path "~/real-file.txt" --link-path "~/my-link.txt"
+  alva fs readlink --path "~/my-link.txt"`,
   run: `Usage: alva run [options]
 
 Execute JavaScript code in the Alva V8 runtime. Provide either inline code
@@ -877,11 +1047,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
@@ -907,8 +1079,9 @@ Constraints:
 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 "~/feeds/my-feed/v1/src/index.js"
+  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.
@@ -922,6 +1095,8 @@ Subcommands:
   delete     Delete a cronjob
   pause      Pause a running cronjob
   resume     Resume a paused cronjob
+  runs       List runs for a cronjob (cursor-paginated)
+  run-logs   Get stdout/stderr logs for a single cronjob run
 
 Create flags:
   --name <name>          Cronjob name (required, 1-63 lowercase alphanumeric/hyphens)
@@ -938,6 +1113,15 @@ List flags:
 Get/Update/Delete/Pause/Resume flags:
   --id <id>              Cronjob ID (required)
 
+Runs flags:
+  --id <id>              Cronjob ID (required)
+  --first <n>            Max results per page
+  --cursor <cursor>      Pagination cursor from previous response
+
+Run-logs flags:
+  --id <id>              Cronjob ID (required)
+  --run-id <id>          Run ID (required)
+
 Name format: 1-63 lowercase alphanumeric or hyphens, no leading/trailing hyphens.
   Valid:   btc-ema-update, my-strategy-1
   Invalid: BTC EMA, -my-job-, my_job
@@ -949,15 +1133,18 @@ Recommended cron schedules:
   "0 0 * * *"      Daily at midnight (end-of-day summaries)
 
 Examples:
-  alva deploy create --name btc-ema --path ~/feeds/btc-ema/v1/src/index.js --cron "0 */4 * * *"
-  alva deploy create --name alert --path ~/feeds/alert/v1/src/index.js --cron "*/5 * * * *" --push-notify --args '{"threshold":100}'
+  alva deploy create --name btc-ema --path "~/feeds/btc-ema/v1/src/index.js" --cron "0 */4 * * *"
+  alva deploy create --name alert --path "~/feeds/alert/v1/src/index.js" --cron "*/5 * * * *" --push-notify --args '{"threshold":100}'
   alva deploy list
   alva deploy list --limit 10
   alva deploy get --id 42
   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:
@@ -1187,12 +1374,10 @@ Examples:
   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?.(
@@ -1205,10 +1390,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 {
@@ -1226,7 +1411,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "execute-latest",
   "dry-run"
 ]);
-function parseFlags(argv) {
+function parseFlags2(argv) {
   const flags = {};
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -1254,7 +1439,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;
 }
@@ -1262,8 +1448,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;
@@ -1307,7 +1495,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
     )
@@ -1318,11 +1506,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({
@@ -1399,18 +1589,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({
@@ -1449,12 +1654,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({
@@ -1493,11 +1713,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({
@@ -1520,11 +1744,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({
@@ -1537,11 +1765,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({
@@ -1563,7 +1795,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":
@@ -1586,7 +1821,8 @@ async function dispatch(client, args, meta) {
       return { written: outFile, bytes: buf.length };
     }
     case "trading": {
-      if (!subcommand) throw new Error("Missing subcommand for trading");
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for trading", "trading");
       switch (subcommand) {
         case "accounts":
           return client.trading.accounts();
@@ -1687,13 +1923,21 @@ async function dispatch(client, args, meta) {
             }
           });
         default:
-          throw new Error(`Unknown subcommand: trading ${subcommand}`);
+          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() {
@@ -1713,11 +1957,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,
@@ -1759,12 +2020,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"));