@aexhq/cli 0.36.0 → 0.37.0

package/README.md

@@ -1,12 +1,35 @@
-# @aexhq/cli
+# Aex CLI
+
+Node.js 22 or newer. The CLI uses `@aexhq/sdk` and the same public Aex HTTP API as
+the dashboard. No dashboard cookies, site credentials or operator credentials are needed.
 
 ```sh
-npm install --global @aexhq/cli
+npm install -g @aexhq/cli
 aex login
-aex session list
-aex session send ses_... "Summarise the repository."
-aex session events ses_...
+aex keys create "My application"
+aex keys list
+aex keys rename KEY_ID "New name"
+aex keys revoke KEY_ID
+aex account
+aex billing
+aex usage
+aex docs
+aex logout
 ```
 
-The CLI stores the pasted API key in `~/.aex/config.json`, requests mode `0600` on POSIX systems,
-and uses `https://api.aex.dev` by default.
+`login` opens your browser for Google sign-in or registration. Confirm the account on
+the Aex page, then return to your terminal. The browser must run on the same computer
+as the CLI. `--no-browser` prints the URL instead of opening it. A loopback listener,
+state and S256 PKCE bind a one-use, 60-second code to the initiating CLI. Account
+credentials expire after seven days; run `login` again. `logout` revokes this session.
+
+Results are JSON on stdout; errors and login progress go to stderr. A created key's
+token is returned once. Existing keys expose only their metadata and prefix.
+Billing currently reports free preview hosting with customer-paid model usage.
+
+The credential file is `~/.aex/account.json` on Unix or `%LOCALAPPDATA%/.aex/account.json`
+on Windows, restricted to the current user (and Windows SYSTEM). `AEX_CONFIG_DIR`
+overrides its directory. For automation, supply `AEX_ACCOUNT_TOKEN`; a workload API
+key cannot manage account credentials. `AEX_API_URL` or `--api-url` changes the API
+origin; stored credentials cannot be reused against a different origin. `--site-url`
+selects the matching login website for a self-hosted installation.

package/package.json

@@ -1,39 +1,14 @@
 {
   "name": "@aexhq/cli",
-  "version": "0.36.0",
-  "description": "Command-line client for Aex sessions",
-  "license": "Apache-2.0",
-  "homepage": "https://aex.dev",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aexhq/aex.git",
-    "directory": "packages/cli"
-  },
+  "version": "0.37.0",
+  "description": "Aex account and API key management from the terminal",
+  "license": "MIT",
   "type": "module",
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": false,
-    "tag": "next"
-  },
-  "bin": {
-    "aex": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "tsc -p tsconfig.json && node --test"
-  },
-  "dependencies": {
-    "@aexhq/sdk": "0.68.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "5.9.3"
-  }
+  "engines": { "node": ">=22" },
+  "bin": { "aex": "src/index.mjs" },
+  "files": ["src", "README.md"],
+  "repository": { "type": "git", "url": "git+https://github.com/aexhq/aex.git", "directory": "packages/cli" },
+  "publishConfig": { "access": "public", "tag": "next" },
+  "dependencies": { "@aexhq/sdk": "0.70.0" },
+  "scripts": { "test": "node --test test/*.test.mjs" }
 }

package/src/config.mjs

@@ -0,0 +1,34 @@
+import { mkdir, chmod, writeFile, rename, readFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+
+const directory = () => process.env.AEX_CONFIG_DIR ?? join(process.platform === "win32" ? process.env.LOCALAPPDATA ?? homedir() : homedir(), ".aex");
+export function origin(value) {
+  const url = new URL(value);
+  if ((url.protocol !== "https:" && !(url.protocol === "http:" && url.hostname === "127.0.0.1")) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) throw new Error("Use an HTTPS origin (or http://127.0.0.1:PORT for local testing).");
+  return url.origin;
+}
+export async function saveSession(session) {
+  const dir = directory();
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") {
+    const exec = promisify(execFile);
+    const { stdout } = await exec("whoami.exe", ["/user", "/fo", "csv", "/nh"], { windowsHide: true });
+    const sid = stdout.match(/S-1-5-\d+(?:-\d+)+/)?.[0];
+    if (!sid) throw new Error("Cannot determine Windows account for credential permissions.");
+    await exec("icacls.exe", [dir, "/inheritance:r", "/grant:r", `*${sid}:(OI)(CI)F`, "*S-1-5-18:(OI)(CI)F"], { windowsHide: true });
+  } else await chmod(dir, 0o700);
+  const temporary = join(dir, `${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, JSON.stringify(session) + "\n", { mode: 0o600, flag: "wx" });
+    await rename(temporary, join(dir, "account.json"));
+  } finally { await rm(temporary, { force: true }); }
+}
+export async function readSession() {
+  try { return JSON.parse(await readFile(join(directory(), "account.json"), "utf8")); }
+  catch (error) { if (error.code === "ENOENT") throw new Error("Sign in first with aex login."); throw error; }
+}
+export async function removeSession() { await rm(join(directory(), "account.json"), { force: true }); }

package/src/index.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { Aex } from "@aexhq/sdk";
+import { login, openBrowser } from "./login.mjs";
+import { origin, readSession, saveSession, removeSession } from "./config.mjs";
+
+const help = `Usage: aex <command>
+
+  login                    Open browser sign-in and save an account session
+  logout                   Revoke this session and remove local credentials
+  keys list                List API keys (secrets are never returned)
+  keys create <name>        Create a key; save the returned token now
+  keys rename <id> <name>   Rename a key
+  keys revoke <id>          Revoke a key
+  account                  Show account, limits and billing status
+  billing                  Show billing status
+  usage                    Show current usage
+  docs                     Open the documentation
+
+Results are JSON on stdout; login progress and errors go to stderr.
+Options: --no-browser, --api-url <origin>, --site-url <origin>, --help
+Automation: AEX_ACCOUNT_TOKEN and optional AEX_API_URL.
+`;
+
+async function main() {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: { help: { type: "boolean", short: "h" }, "no-browser": { type: "boolean" }, "api-url": { type: "string" }, "site-url": { type: "string" } } });
+  if (values.help || !positionals.length) { process.stdout.write(help); return; }
+  const [command, operation, ...args] = positionals;
+  const expected = { "keys list": 0, "keys create": 1, "keys rename": 2, "keys revoke": 1 };
+  if (command === "keys" ? expected[`keys ${operation}`] !== args.length : !["login", "logout", "account", "billing", "usage", "docs"].includes(command) || positionals.length !== 1) throw new Error("Unknown command or incorrect arguments. Run aex --help.");
+  const explicitApi = values["api-url"] ?? process.env.AEX_API_URL;
+  const siteUrl = origin(values["site-url"] ?? "https://aex.dev");
+  if (command === "docs") {
+    const url = `${siteUrl}/docs`; process.stdout.write(url + "\n");
+    if (!values["no-browser"]) await openBrowser(url);
+    return;
+  }
+  if (command === "login") {
+    const apiUrl = origin(explicitApi ?? "https://api.aex.dev");
+    const controller = new AbortController(), timeout = setTimeout(() => controller.abort(), 600_000);
+    const cancel = () => controller.abort(); process.once("SIGINT", cancel);
+    try {
+      const session = await login({ apiUrl, siteUrl, signal: controller.signal, onReady: async url => {
+        process.stderr.write(`Sign in using this browser on this computer:\n${url}\n`);
+        if (!values["no-browser"]) await openBrowser(url).catch(() => process.stderr.write("Could not open a browser. Open the URL above to continue.\n"));
+      } });
+      const client = new Aex({ accountToken: session.token, baseUrl: apiUrl, timeoutMs: 15_000 });
+      try { await saveSession({ ...session, apiUrl }); }
+      catch (error) { await client.account.logout(); throw error; }
+      process.stdout.write(JSON.stringify(await client.account.get(), null, 2) + "\n");
+    } finally { clearTimeout(timeout); process.removeListener("SIGINT", cancel); }
+    return;
+  }
+  const session = process.env.AEX_ACCOUNT_TOKEN ? { token: process.env.AEX_ACCOUNT_TOKEN, apiUrl: origin(explicitApi ?? "https://api.aex.dev") } : await readSession();
+  const apiUrl = origin(explicitApi ?? session.apiUrl);
+  if (apiUrl !== session.apiUrl) throw new Error("Saved credentials belong to a different API origin. Run aex login for this origin.");
+  const client = new Aex({ accountToken: session.token, baseUrl: apiUrl, timeoutMs: 15_000 });
+  let result;
+  if (command === "logout") {
+    try { await client.account.logout(); } catch (error) { if (error.status !== 401) throw error; }
+    if (!process.env.AEX_ACCOUNT_TOKEN) await removeSession();
+    result = { signed_out: true };
+  } else if (command === "account") result = await client.account.get();
+  else if (command === "billing") result = { billing: (await client.account.get()).billing };
+  else if (command === "usage") result = await client.account.usage();
+  else if (operation === "list") result = await client.keys.list();
+  else if (operation === "create") result = await client.keys.create({ name: args[0] });
+  else if (operation === "rename") result = await client.keys.update(args[0], { name: args[1] });
+  else { await client.keys.delete(args[0]); result = { revoked: args[0] }; }
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+main().catch(error => { process.stderr.write(`aex: ${error.message}\n`); process.exitCode = 1; });

package/src/login.mjs

@@ -0,0 +1,47 @@
+import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Aex } from "@aexhq/sdk";
+
+const exec = promisify(execFile);
+export async function openBrowser(url) {
+  const [command, args] = process.platform === "win32"
+    ? ["rundll32.exe", ["url.dll,FileProtocolHandler", url]]
+    : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  await exec(command, args, { windowsHide: true });
+}
+
+export async function login({ apiUrl, siteUrl, onReady, signal = AbortSignal.timeout(600_000) }) {
+  const verifier = randomBytes(32).toString("base64url"), state = randomBytes(32).toString("base64url");
+  const server = createServer();
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+  const redirect = `http://127.0.0.1:${server.address().port}/callback`;
+  const url = new URL("/cli", siteUrl);
+  url.search = new URLSearchParams({ redirect_uri: redirect, state, code_challenge: createHash("sha256").update(verifier).digest("base64url") }).toString();
+  try {
+    return await new Promise((resolve, reject) => {
+      let exchanging = false;
+      const abort = () => reject(new Error("Login cancelled or timed out. Run aex login again."));
+      signal.addEventListener("abort", abort, { once: true });
+      server.once("close", () => signal.removeEventListener("abort", abort));
+      server.on("request", async (request, response) => {
+        response.setHeader("content-type", "text/plain; charset=utf-8");
+        response.setHeader("cache-control", "no-store");
+        response.setHeader("referrer-policy", "no-referrer");
+        const callback = new URL(request.url, redirect);
+        if (request.method !== "GET" || request.headers.host !== new URL(redirect).host || callback.pathname !== "/callback" || callback.searchParams.get("state") !== state || !callback.searchParams.get("code") || exchanging) {
+          response.writeHead(400).end("Invalid login callback."); return;
+        }
+        exchanging = true;
+        try {
+          const session = await Aex.exchangeLogin({ code: callback.searchParams.get("code"), code_verifier: verifier, redirect_uri: redirect }, { baseUrl: apiUrl, timeoutMs: 15_000 });
+          response.end("Signed in to Aex. You can close this tab and return to your terminal.");
+          resolve(session);
+        } catch (error) { response.writeHead(400).end("Login failed. Return to your terminal and try again."); reject(error); }
+      });
+      if (signal.aborted) abort();
+      else Promise.resolve().then(() => onReady(url.toString())).catch(reject);
+    });
+  } finally { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); }
+}

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/index.js

@@ -1,203 +0,0 @@
-#!/usr/bin/env node
-import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import process from "node:process";
-import { Aex, AexError } from "@aexhq/sdk";
-const HELP = `Aex — the session backend for AI apps
-
-Usage:
-  aex login
-  aex doctor
-  aex session list
-  aex session get <session-id>
-  aex session send <session-id> <message>
-  aex session events <session-id>
-  aex session cancel <session-id>
-  aex session end <session-id>
-  aex session delete <session-id>
-
-The API defaults to https://api.aex.dev.`;
-async function main(argv) {
-    const [command, ...rest] = argv;
-    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-        process.stdout.write(`${HELP}\n`);
-        return;
-    }
-    if (command === "login") {
-        await login();
-        return;
-    }
-    const aex = await client();
-    if (command === "doctor") {
-        await aex.sessions.list();
-        process.stdout.write("Aex API: ok\n");
-        return;
-    }
-    if (command !== "session")
-        usage(`Unknown command: ${command}`);
-    await sessionCommand(aex, rest);
-}
-async function sessionCommand(aex, argv) {
-    const [command, id, ...tail] = argv;
-    switch (command) {
-        case "list": {
-            print(await aex.sessions.list());
-            return;
-        }
-        case "get": {
-            requireId(id, command);
-            print((await aex.sessions.get(id)).state);
-            return;
-        }
-        case "send": {
-            requireId(id, command);
-            const message = tail.join(" ").trim();
-            if (message === "")
-                usage("session send requires a message");
-            const session = await aex.sessions.get(id);
-            print(await session.send(message));
-            return;
-        }
-        case "events": {
-            requireId(id, command);
-            const session = await aex.sessions.get(id);
-            const controller = new AbortController();
-            process.once("SIGINT", () => controller.abort());
-            try {
-                for await (const event of session.events()) {
-                    process.stdout.write(`${JSON.stringify(event)}\n`);
-                }
-            }
-            catch (error) {
-                if (!controller.signal.aborted)
-                    throw error;
-            }
-            return;
-        }
-        case "cancel": {
-            requireId(id, command);
-            const session = await aex.sessions.get(id);
-            await session.cancel();
-            print(session.state);
-            return;
-        }
-        case "end": {
-            requireId(id, command);
-            const session = await aex.sessions.get(id);
-            print(await session.end());
-            return;
-        }
-        case "delete": {
-            requireId(id, command);
-            const session = await aex.sessions.get(id);
-            await session.delete();
-            return;
-        }
-        default:
-            usage(command === undefined ? "Missing session command" : `Unknown session command: ${command}`);
-    }
-}
-async function client() {
-    const apiKey = process.env.AEX_API_KEY ?? (await readConfig())?.apiKey;
-    if (apiKey === undefined || apiKey === "") {
-        throw new Error("No Aex API key. Run `aex login` first.");
-    }
-    return new Aex({
-        apiKey,
-        ...(process.env.AEX_BASE_URL === undefined ? {} : { baseUrl: process.env.AEX_BASE_URL }),
-    });
-}
-async function login() {
-    const apiKey = (await readSecret("Paste Aex API key: ")).trim();
-    if (!/^aex_sk_[A-Za-z0-9]{40,64}$/.test(apiKey)) {
-        throw new Error("That does not look like an Aex session API key.");
-    }
-    const path = configPath();
-    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    const temporary = `${path}.${process.pid}.tmp`;
-    await writeFile(temporary, `${JSON.stringify({ apiKey }, null, 2)}\n`, {
-        encoding: "utf8",
-        mode: 0o600,
-    });
-    await rename(temporary, path);
-    await chmod(path, 0o600).catch(() => undefined);
-    process.stdout.write("Saved.\n");
-}
-async function readConfig() {
-    try {
-        const value = JSON.parse(await readFile(configPath(), "utf8"));
-        return typeof value.apiKey === "string" ? { apiKey: value.apiKey } : undefined;
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return undefined;
-        throw error;
-    }
-}
-function configPath() {
-    return process.env.AEX_CONFIG ?? join(homedir(), ".aex", "config.json");
-}
-async function readSecret(prompt) {
-    if (!process.stdin.isTTY) {
-        const chunks = [];
-        for await (const chunk of process.stdin)
-            chunks.push(Buffer.from(chunk));
-        return Buffer.concat(chunks).toString("utf8");
-    }
-    process.stdout.write(prompt);
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    return new Promise((resolveValue, reject) => {
-        let value = "";
-        const cleanup = () => {
-            process.stdin.off("data", onData);
-            process.stdin.setRawMode(false);
-            process.stdin.pause();
-            process.stdout.write("\n");
-        };
-        const onData = (chunk) => {
-            for (const byte of chunk) {
-                if (byte === 3) {
-                    cleanup();
-                    reject(new Error("Login cancelled."));
-                    return;
-                }
-                if (byte === 13 || byte === 10) {
-                    cleanup();
-                    resolveValue(value);
-                    return;
-                }
-                if (byte === 8 || byte === 127) {
-                    if (value.length > 0) {
-                        value = value.slice(0, -1);
-                        process.stdout.write("\b \b");
-                    }
-                    continue;
-                }
-                value += String.fromCharCode(byte);
-                process.stdout.write("*");
-            }
-        };
-        process.stdin.on("data", onData);
-    });
-}
-function requireId(id, command) {
-    if (id === undefined || id === "")
-        usage(`session ${command} requires a session id`);
-}
-function print(value) {
-    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
-}
-function usage(message) {
-    throw new Error(`${message}\n\n${HELP}`);
-}
-main(process.argv.slice(2)).catch((error) => {
-    if (error instanceof AexError) {
-        process.stderr.write(`${error.name}: ${error.message}${error.code === undefined ? "" : ` (${error.code})`}\n`);
-    }
-    else {
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-    process.exitCode = 1;
-});