@pyxis-labs/cli 0.0.1 → 0.1.0

package/README.md

@@ -1,8 +1,10 @@
 # `@pyxis-labs/cli`
 
-Pyxis on the command line. Run Web3 research briefings from your terminal — same 5-agent pipeline as [usepyxis.com](https://usepyxis.com).
+[![npm version](https://img.shields.io/npm/v/@pyxis-labs/cli?style=flat-square&color=3b82f6)](https://www.npmjs.com/package/@pyxis-labs/cli)
+[![license](https://img.shields.io/npm/l/@pyxis-labs/cli?style=flat-square&color=3b82f6)](https://github.com/pyxis-app/cli/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/pyxis-app/cli/ci.yml?branch=main&style=flat-square&color=3b82f6)](https://github.com/pyxis-app/cli/actions/workflows/ci.yml)
 
-> **Status:** early scaffold (v0.0.1). Only `pyxis health` is wired up. `pyxis research` lands next once the SIWE auth flow ships.
+Pyxis on the command line. Run Web3 research briefings from your terminal — same 5-agent pipeline as [usepyxis.com](https://www.usepyxis.com).
 
 ## Install
 
@@ -14,22 +16,43 @@ npx @pyxis-labs/cli health
 
 Requires Node.js ≥ 18.17.
 
-## Usage
+## Quickstart
 
 ```bash
-pyxis <command> [options]
+pyxis login                           # opens browser, sign in with wallet
+pyxis research "ondo finance Q2"      # 5-agent briefing in your terminal
+pyxis status                          # check session
+pyxis logout                          # clear local credentials
 ```
 
-| Command | Status | What it does |
-|---|---|---|
-| `pyxis health` | ✅ shipped | Ping `usepyxis.com/api/health` — confirms API + DB are up |
-| `pyxis research <topic>` | 🚧 planned | Run a briefing — 5-agent pipeline against any token/chain/protocol/narrative |
+## Commands
+
+| Command | What it does |
+|---|---|
+| `pyxis login` | Browser-callback sign-in. Token saved to `~/.config/pyxis/credentials` (mode 0600). Valid 24h. |
+| `pyxis logout` | Removes local credentials. (Token remains valid server-side until natural expiry.) |
+| `pyxis status` | Shows current wallet + expiry. Exit 1 if not logged in. |
+| `pyxis research <topic>` | Runs the 5-agent research pipeline against your topic. 30-90s typical. |
+| `pyxis health` | Pings `/api/health` — confirms API + DB are up. |
+| `pyxis help`, `--version` | Self-explanatory. |
 
 ## Configuration
 
 | Env var | Default | Purpose |
 |---|---|---|
 | `PYXIS_API_BASE` | `https://usepyxis.com` | Override for self-hosted or staging |
+| `NO_COLOR` | unset | When `1`, disable all ANSI colors and the banner |
+| `PYXIS_NO_BANNER` | unset | When `1`, suppress only the login banner (keep colors) |
+| `XDG_CONFIG_HOME` | `~/.config` | POSIX credentials directory base |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | User error (not logged in, invalid topic, token expired) |
+| 2 | Server / network error (5xx, timeout, rate-limited) |
+| 130 | Interrupted (Ctrl+C) |
 
 ## Development
 
@@ -37,11 +60,22 @@ pyxis <command> [options]
 git clone git@github.com:pyxis-app/cli.git
 cd cli
 npm install
-npm run dev -- health        # run from source via tsx
-npm run build                # emit dist/
-node dist/index.js health    # run built artifact
+npm test                       # vitest
+npm run dev -- health          # run from source via tsx
+npm run build                  # emit dist/
+node dist/index.js login       # run built artifact
 ```
 
+## Related
+
+| Project | What it is |
+|---|---|
+| [usepyxis.com](https://www.usepyxis.com) | Live web app — same 5-agent pipeline, rendered briefings |
+| [docs.usepyxis.com](https://docs.usepyxis.com) | Docs site — methodology, sources, FAQ |
+| [`pyxis-app/pyxis`](https://github.com/pyxis-app/pyxis) | Main app source (AGPL-3.0) |
+| [`@pyxis-labs/web3-sources`](https://github.com/pyxis-app/web3-sources) | Sibling: typed TS clients for the 13 data sources Pyxis pulls from |
+| [@pyxisbase](https://x.com/pyxisbase) on X | Project updates, build-in-public |
+
 ## License
 
-MIT © Pyxis Authors. App itself (`pyxis-app/pyxis`) is AGPL-3.0 — this CLI is intentionally MIT so it can be embedded freely.
+MIT © 2026 Pyxis Authors. App itself (`pyxis-app/pyxis`) is AGPL-3.0 — this CLI is intentionally MIT so it can be embedded freely.

package/dist/commands/login.d.ts

@@ -0,0 +1 @@
+export declare function login(_args: string[]): Promise<number>;

package/dist/commands/login.js

@@ -0,0 +1,64 @@
+import { performLogin } from "../lib/auth.js";
+import { save } from "../lib/credentials.js";
+import { printBanner, ok, step, meta, dim, bright, cyan, bold, spin } from "../lib/ui.js";
+import { API_BASE } from "../config.js";
+import { LoginCancelledError, AuthError } from "../lib/errors.js";
+export async function login(_args) {
+    printBanner();
+    let spinner;
+    try {
+        const creds = await performLogin({
+            apiBase: API_BASE,
+            onUrl(url) {
+                process.stdout.write(step("Open this URL in your browser:") + "\n");
+                process.stdout.write(`     ${bright(url)}\n`);
+                process.stdout.write(`     ${dim("(attempting to launch your default browser…)")}` + "\n\n");
+            },
+            onWaiting() {
+                spinner = spin(`Waiting for sign-in...  ${dim("(Ctrl+C to cancel)")}`);
+            },
+        });
+        spinner?.stop();
+        await save(creds);
+        const expiresIn = formatRelative(creds.exp);
+        const expiresAt = new Date(creds.exp * 1000).toUTCString();
+        process.stdout.write("\n" + ok(bold("Logged in")) + "\n");
+        process.stdout.write(meta("wallet", cyan(shortWallet(creds.wallet))) + "\n");
+        process.stdout.write(meta("expires", `${expiresAt} ${dim(`(${expiresIn})`)}`) + "\n");
+        process.stdout.write(meta("stored at", credentialsPathStr()) + "\n");
+        return 0;
+    }
+    catch (e) {
+        spinner?.stop();
+        if (e instanceof LoginCancelledError) {
+            process.stderr.write("\n" + step(e.message) + "\n");
+            return 1;
+        }
+        if (e instanceof AuthError) {
+            process.stderr.write("\n" + step(`Login failed: ${e.message}`) + "\n");
+            return 1;
+        }
+        throw e;
+    }
+}
+function shortWallet(w) {
+    return `${w.slice(0, 6)}…${w.slice(-4)}`;
+}
+function formatRelative(expUnixSec) {
+    const seconds = expUnixSec - Math.floor(Date.now() / 1000);
+    if (seconds <= 0)
+        return "expired";
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    return `${hours}h${minutes.toString().padStart(2, "0")}m`;
+}
+function credentialsPathStr() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (process.platform === "win32") {
+        return process.env.APPDATA
+            ? `${process.env.APPDATA}\\pyxis\\credentials`
+            : "%APPDATA%\\pyxis\\credentials";
+    }
+    const xdg = process.env.XDG_CONFIG_HOME ?? `${home}/.config`;
+    return xdg.replace(home, "~") + "/pyxis/credentials";
+}

package/dist/commands/logout.d.ts

@@ -0,0 +1 @@
+export declare function logout(_args: string[]): Promise<number>;

package/dist/commands/logout.js

@@ -0,0 +1,26 @@
+import { clear, load } from "../lib/credentials.js";
+import { ok, meta, dim, bold } from "../lib/ui.js";
+export async function logout(_args) {
+    const existing = await load();
+    await clear();
+    process.stdout.write("\n" + ok(bold("Logged out")) + "\n");
+    if (existing) {
+        process.stdout.write(meta("removed", credentialsDisplay()) + "\n");
+        process.stdout.write(meta("note", dim("token remains valid server-side up to 24h until natural expiry")) +
+            "\n");
+    }
+    else {
+        process.stdout.write(meta("info", dim("no credentials were present")) + "\n");
+    }
+    return 0;
+}
+function credentialsDisplay() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (process.platform === "win32") {
+        return process.env.APPDATA
+            ? `${process.env.APPDATA}\\pyxis\\credentials`
+            : "%APPDATA%\\pyxis\\credentials";
+    }
+    const xdg = process.env.XDG_CONFIG_HOME ?? `${home}/.config`;
+    return xdg.replace(home, "~") + "/pyxis/credentials";
+}

package/dist/commands/research.d.ts

@@ -1 +1 @@
-export declare function research(_args: string[]): Promise<number>;
+export declare function research(args: string[]): Promise<number>;

package/dist/commands/research.js

@@ -1,6 +1,62 @@
-export async function research(_args) {
-    process.stderr.write("research: not yet implemented\n\n" +
-        "Needs SIWE auth flow first (the /api/research endpoint is wallet-gated).\n" +
-        "Track: https://github.com/pyxis-app/cli/issues\n");
-    return 2;
+import { load } from "../lib/credentials.js";
+import { callResearch } from "../lib/api.js";
+import { ok, fail, step, meta, dim, cyan, bright, bold, spin } from "../lib/ui.js";
+import { API_BASE } from "../config.js";
+import { AuthError, RateLimitError, ServerError } from "../lib/errors.js";
+export async function research(args) {
+    const topic = args.join(" ").trim();
+    if (!topic) {
+        process.stderr.write(fail("Usage: pyxis research <topic>") + "\n");
+        return 1;
+    }
+    if (topic.length < 3 || topic.length > 200) {
+        process.stderr.write(fail("Topic must be 3-200 characters") + "\n");
+        return 1;
+    }
+    const creds = await load();
+    if (!creds) {
+        process.stderr.write(fail("Not logged in") + "\n");
+        process.stderr.write(meta("hint", dim("run `pyxis login` first")) + "\n");
+        return 1;
+    }
+    process.stdout.write("\n");
+    process.stdout.write(step(`Running as ${cyan(shortWallet(creds.wallet))} on ${bright("usepyxis.com")}`) + "\n");
+    const spinner = spin("Researching…");
+    const startedAt = Date.now();
+    let result;
+    try {
+        result = await callResearch({ apiBase: API_BASE, credentials: creds, topic });
+    }
+    catch (e) {
+        spinner.stop();
+        if (e instanceof AuthError) {
+            process.stderr.write("\n" + fail(e.message) + "\n");
+            return 1;
+        }
+        if (e instanceof RateLimitError) {
+            process.stderr.write("\n" + fail(e.message) + "\n");
+            return 2;
+        }
+        if (e instanceof ServerError) {
+            process.stderr.write("\n" + fail(e.message) + "\n");
+            return 2;
+        }
+        throw e;
+    }
+    const elapsedSec = Math.round((Date.now() - startedAt) / 1000);
+    spinner.stop();
+    process.stdout.write("\n" + ok(bold(`Done in ${elapsedSec}s.`)) + "\n\n");
+    const markdown = result?.briefing?.markdown;
+    if (typeof markdown === "string" && markdown.length > 0) {
+        process.stdout.write(markdown);
+        if (!markdown.endsWith("\n"))
+            process.stdout.write("\n");
+    }
+    else {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    return 0;
+}
+function shortWallet(w) {
+    return `${w.slice(0, 6)}…${w.slice(-4)}`;
 }

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function status(_args: string[]): Promise<number>;

package/dist/commands/status.js

@@ -0,0 +1,39 @@
+import { load } from "../lib/credentials.js";
+import { ok, fail, meta, dim, cyan, bold } from "../lib/ui.js";
+export async function status(_args) {
+    const creds = await load();
+    if (!creds) {
+        process.stdout.write("\n" + fail(bold("Not logged in")) + "\n");
+        process.stdout.write(meta("hint", dim("run `pyxis login`")) + "\n");
+        return 1;
+    }
+    const nowSec = Math.floor(Date.now() / 1000);
+    const remainingSec = creds.exp - nowSec;
+    if (remainingSec <= 0) {
+        process.stdout.write("\n" + fail(bold("Session expired")) + "\n");
+        process.stdout.write(meta("wallet", cyan(shortWallet(creds.wallet))) + "\n");
+        process.stdout.write(meta("hint", dim("run `pyxis login` to refresh")) + "\n");
+        return 1;
+    }
+    const hours = Math.floor(remainingSec / 3600);
+    const minutes = Math.floor((remainingSec % 3600) / 60);
+    const expiresAt = new Date(creds.exp * 1000).toUTCString();
+    process.stdout.write("\n" + ok(bold("Logged in")) + "\n");
+    process.stdout.write(meta("wallet", cyan(shortWallet(creds.wallet))) + "\n");
+    process.stdout.write(meta("expires", `${expiresAt} ${dim(`(${hours}h${minutes.toString().padStart(2, "0")}m remaining)`)}`) + "\n");
+    process.stdout.write(meta("stored at", credentialsDisplay()) + "\n");
+    return 0;
+}
+function shortWallet(w) {
+    return `${w.slice(0, 6)}…${w.slice(-4)}`;
+}
+function credentialsDisplay() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (process.platform === "win32") {
+        return process.env.APPDATA
+            ? `${process.env.APPDATA}\\pyxis\\credentials`
+            : "%APPDATA%\\pyxis\\credentials";
+    }
+    const xdg = process.env.XDG_CONFIG_HOME ?? `${home}/.config`;
+    return xdg.replace(home, "~") + "/pyxis/credentials";
+}

package/dist/index.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
 import { health } from "./commands/health.js";
 import { research } from "./commands/research.js";
+import { login } from "./commands/login.js";
+import { logout } from "./commands/logout.js";
+import { status } from "./commands/status.js";
 const USAGE = `pyxis — Web3 research from your terminal
 
 Usage:
   pyxis <command> [options]
 
 Commands:
+  login              Sign in with your wallet (opens browser)
+  logout             Sign out and remove local credentials
+  status             Show current sign-in state
   research <topic>   Run a research briefing (5-agent pipeline)
   health             Check usepyxis.com API status
   help               Show this message
@@ -29,10 +35,11 @@ async function main(argv) {
         return 0;
     }
     switch (cmd) {
-        case "health":
-            return health(rest);
-        case "research":
-            return research(rest);
+        case "health": return health(rest);
+        case "login": return login(rest);
+        case "logout": return logout(rest);
+        case "status": return status(rest);
+        case "research": return research(rest);
         default:
             process.stderr.write(`Unknown command: ${cmd}\n\n${USAGE}`);
             return 1;

package/dist/lib/__tests__/api.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/api.test.js

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { callResearch, isCredentialsFresh } from "../api.js";
+import { AuthError, RateLimitError, ServerError } from "../errors.js";
+const FRESH_CREDS = {
+    token: "jwt",
+    wallet: "0xabc",
+    exp: Math.floor(Date.now() / 1000) + 3600,
+    savedAt: Date.now(),
+};
+const EXPIRED_CREDS = {
+    ...FRESH_CREDS,
+    exp: Math.floor(Date.now() / 1000) - 60,
+};
+describe("isCredentialsFresh", () => {
+    it("true when exp is well in the future", () => {
+        expect(isCredentialsFresh(FRESH_CREDS)).toBe(true);
+    });
+    it("false when exp is in the past", () => {
+        expect(isCredentialsFresh(EXPIRED_CREDS)).toBe(false);
+    });
+    it("false when exp is within the 60s buffer", () => {
+        expect(isCredentialsFresh({ ...FRESH_CREDS, exp: Math.floor(Date.now() / 1000) + 30 })).toBe(false);
+    });
+});
+describe("callResearch error mapping", () => {
+    const origFetch = global.fetch;
+    beforeEach(() => { global.fetch = vi.fn(); });
+    afterEach(() => { global.fetch = origFetch; });
+    it("throws AuthError when client-side credentials are stale", async () => {
+        await expect(callResearch({ apiBase: "http://x", credentials: EXPIRED_CREDS, topic: "btc" })).rejects.toBeInstanceOf(AuthError);
+    });
+    it("throws AuthError on 401 response", async () => {
+        global.fetch.mockResolvedValue(new Response(JSON.stringify({ error: "sign in required" }), { status: 401 }));
+        await expect(callResearch({ apiBase: "http://x", credentials: FRESH_CREDS, topic: "btc" })).rejects.toBeInstanceOf(AuthError);
+    });
+    it("throws RateLimitError on 429 with Retry-After", async () => {
+        global.fetch.mockResolvedValue(new Response("", { status: 429, headers: { "retry-after": "30" } }));
+        await expect(callResearch({ apiBase: "http://x", credentials: FRESH_CREDS, topic: "btc" })).rejects.toBeInstanceOf(RateLimitError);
+    });
+    it("throws ServerError on 500", async () => {
+        global.fetch.mockResolvedValue(new Response("oops", { status: 500 }));
+        await expect(callResearch({ apiBase: "http://x", credentials: FRESH_CREDS, topic: "btc" })).rejects.toBeInstanceOf(ServerError);
+    });
+    it("returns parsed result on 200", async () => {
+        global.fetch.mockResolvedValue(new Response(JSON.stringify({ briefing: { markdown: "# Hello" } }), { status: 200 }));
+        const result = await callResearch({ apiBase: "http://x", credentials: FRESH_CREDS, topic: "btc" });
+        expect(result.briefing?.markdown).toBe("# Hello");
+    });
+});

package/dist/lib/__tests__/callback.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/callback.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { startCallbackServer } from "../callback.js";
+describe("callback server", () => {
+    it("resolves on matching state + code", async () => {
+        const server = await startCallbackServer({ state: "ST", challenge: "CH" });
+        const fetched = fetch(`http://127.0.0.1:${server.port}/?state=ST&code=CH`);
+        const result = await server.awaitCallback({ timeoutMs: 5_000 });
+        expect(result.code).toBe("CH");
+        await fetched;
+        await server.close();
+    });
+    it("rejects mismatched state and keeps waiting", async () => {
+        const server = await startCallbackServer({ state: "ST", challenge: "CH" });
+        const badResp = await fetch(`http://127.0.0.1:${server.port}/?state=WRONG&code=CH`);
+        expect(badResp.status).toBe(400);
+        const fetched = fetch(`http://127.0.0.1:${server.port}/?state=ST&code=CH`);
+        const result = await server.awaitCallback({ timeoutMs: 5_000 });
+        expect(result.code).toBe("CH");
+        await fetched;
+        await server.close();
+    });
+    it("rejects after timeout when no valid callback arrives", async () => {
+        const server = await startCallbackServer({ state: "ST", challenge: "CH" });
+        await expect(server.awaitCallback({ timeoutMs: 100 })).rejects.toThrow(/timeout/i);
+        await server.close();
+    });
+});

package/dist/lib/__tests__/credentials.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/credentials.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, stat, readFile, writeFile } from "node:fs/promises";
+import { tmpdir, platform } from "node:os";
+import { join } from "node:path";
+import { save, load, clear, _setPathForTests } from "../credentials.js";
+let dir;
+beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "pyxis-cred-"));
+    _setPathForTests(join(dir, "credentials"));
+});
+afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+    _setPathForTests(null);
+});
+const sample = {
+    token: "jwt-here",
+    wallet: "0xabc",
+    exp: 1234567890,
+    savedAt: Date.now(),
+};
+describe("credentials.save", () => {
+    it("writes JSON to the path", async () => {
+        await save(sample);
+        const raw = await readFile(join(dir, "credentials"), "utf8");
+        expect(JSON.parse(raw)).toEqual(sample);
+    });
+    it("sets mode 0600 on POSIX", async () => {
+        if (platform() === "win32")
+            return;
+        await save(sample);
+        const s = await stat(join(dir, "credentials"));
+        expect(s.mode & 0o777).toBe(0o600);
+    });
+});
+describe("credentials.load", () => {
+    it("returns null when file missing", async () => {
+        const result = await load();
+        expect(result).toBeNull();
+    });
+    it("returns parsed object when file exists", async () => {
+        await save(sample);
+        const result = await load();
+        expect(result).toEqual(sample);
+    });
+    it("returns null on malformed JSON", async () => {
+        await writeFile(join(dir, "credentials"), "not json", "utf8");
+        const result = await load();
+        expect(result).toBeNull();
+    });
+    it("returns null when JSON shape does not match Credentials", async () => {
+        await writeFile(join(dir, "credentials"), JSON.stringify({ token: "only" }), "utf8");
+        const result = await load();
+        expect(result).toBeNull();
+    });
+});
+describe("credentials.clear", () => {
+    it("removes the file (idempotent)", async () => {
+        await save(sample);
+        await clear();
+        expect(await load()).toBeNull();
+        await expect(clear()).resolves.toBeUndefined();
+    });
+});

package/dist/lib/__tests__/ui.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/__tests__/ui.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { ok, fail, warn, step, meta, isColorEnabled } from "../ui.js";
+// Strip ANSI escapes so assertions don't depend on TTY/FORCE_COLOR detection
+// (picocolors emits codes when CI sets FORCE_COLOR even though our isColorEnabled
+// returns false — the helpers always run picocolors regardless).
+// eslint-disable-next-line no-control-regex
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+describe("ui status helpers", () => {
+    beforeEach(() => {
+        delete process.env.NO_COLOR;
+        delete process.env.PYXIS_NO_BANNER;
+    });
+    it("ok wraps with green check", () => {
+        const out = stripAnsi(ok("Logged in"));
+        expect(out).toContain("✓");
+        expect(out).toContain("Logged in");
+    });
+    it("fail wraps with red x", () => {
+        const out = stripAnsi(fail("oops"));
+        expect(out).toContain("✗");
+        expect(out).toContain("oops");
+    });
+    it("warn uses yellow tilde", () => {
+        const out = stripAnsi(warn("careful"));
+        expect(out).toContain("~");
+        expect(out).toContain("careful");
+    });
+    it("step uses cyan arrow", () => {
+        const out = stripAnsi(step("Opening browser"));
+        expect(out).toContain("→");
+    });
+    it("meta aligns label width 11", () => {
+        const out = stripAnsi(meta("wallet", "0xabc"));
+        expect(out).toMatch(/wallet\s+0xabc/);
+    });
+    it("isColorEnabled returns false when NO_COLOR=1", () => {
+        process.env.NO_COLOR = "1";
+        expect(isColorEnabled()).toBe(false);
+    });
+});

package/dist/lib/api.d.ts

@@ -0,0 +1,13 @@
+import type { Credentials } from "./credentials.js";
+export declare function isCredentialsFresh(c: Credentials, now?: number): boolean;
+export interface ResearchResult {
+    briefing?: {
+        markdown?: string;
+    };
+    [key: string]: unknown;
+}
+export declare function callResearch(opts: {
+    apiBase: string;
+    credentials: Credentials;
+    topic: string;
+}): Promise<ResearchResult>;

package/dist/lib/api.js

@@ -0,0 +1,51 @@
+import { AuthError, RateLimitError, ServerError } from "./errors.js";
+const CLOCK_SKEW_BUFFER_SEC = 60;
+const RESEARCH_TIMEOUT_MS = 120_000;
+export function isCredentialsFresh(c, now = Date.now()) {
+    const nowSec = Math.floor(now / 1000);
+    return c.exp - nowSec > CLOCK_SKEW_BUFFER_SEC;
+}
+export async function callResearch(opts) {
+    if (!isCredentialsFresh(opts.credentials)) {
+        throw new AuthError("Token expired or about to expire — run `pyxis login`");
+    }
+    let res;
+    try {
+        res = await fetch(`${opts.apiBase}/api/research`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Cookie: `pyxis_session=${opts.credentials.token}`,
+            },
+            body: JSON.stringify({ topic: opts.topic }),
+            signal: AbortSignal.timeout(RESEARCH_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        if (e.name === "TimeoutError") {
+            throw new ServerError(`Request timed out after ${RESEARCH_TIMEOUT_MS / 1000}s`, 0);
+        }
+        throw new ServerError(`Could not reach ${opts.apiBase}: ${e.message}`, 0);
+    }
+    if (res.status === 401) {
+        throw new AuthError("Authentication failed — run `pyxis login`");
+    }
+    if (res.status === 429) {
+        const ra = res.headers.get("retry-after");
+        const seconds = ra ? Number(ra) : null;
+        throw new RateLimitError(seconds != null
+            ? `Rate limited — retry after ${seconds}s`
+            : "Rate limited — try again later", seconds);
+    }
+    if (res.status === 400) {
+        const body = (await res.json().catch(() => ({ error: "bad request" })));
+        throw new AuthError(body.error ?? "bad request");
+    }
+    if (res.status >= 500) {
+        throw new ServerError(`Server returned ${res.status}`, res.status);
+    }
+    if (!res.ok) {
+        throw new ServerError(`Unexpected status ${res.status}`, res.status);
+    }
+    return (await res.json());
+}

package/dist/lib/auth.d.ts

@@ -0,0 +1,8 @@
+import type { Credentials } from "./credentials.js";
+export interface LoginOptions {
+    apiBase: string;
+    timeoutMs?: number;
+    onUrl?: (url: string) => void;
+    onWaiting?: () => void;
+}
+export declare function performLogin(opts: LoginOptions): Promise<Credentials>;

package/dist/lib/auth.js

@@ -0,0 +1,42 @@
+import { randomBytes, createHash } from "node:crypto";
+import { startCallbackServer } from "./callback.js";
+import { openBrowser } from "./browser.js";
+import { AuthError, LoginCancelledError, TimeoutError } from "./errors.js";
+export async function performLogin(opts) {
+    const state = randomBytes(16).toString("hex");
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const server = await startCallbackServer({ state, challenge });
+    const url = `${opts.apiBase}/cli-auth?state=${state}&port=${server.port}&challenge=${encodeURIComponent(challenge)}`;
+    opts.onUrl?.(url);
+    await openBrowser(url);
+    opts.onWaiting?.();
+    let callback;
+    try {
+        callback = await server.awaitCallback({ timeoutMs: opts.timeoutMs ?? 5 * 60_000 });
+    }
+    catch (e) {
+        await server.close();
+        if (e instanceof TimeoutError) {
+            throw new LoginCancelledError("Login cancelled or timed out — run `pyxis login` again");
+        }
+        throw e;
+    }
+    await server.close();
+    const res = await fetch(`${opts.apiBase}/api/cli/token`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ code: callback.code, verifier }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+        throw new AuthError(`Token exchange failed (HTTP ${res.status})`);
+    }
+    const payload = (await res.json());
+    return {
+        token: payload.token,
+        wallet: payload.wallet,
+        exp: payload.exp,
+        savedAt: Date.now(),
+    };
+}

package/dist/lib/browser.d.ts

@@ -0,0 +1,3 @@
+export declare function openBrowser(url: string): Promise<{
+    opened: boolean;
+}>;

package/dist/lib/browser.js

@@ -0,0 +1,53 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync } from "node:fs";
+const execFileAsync = promisify(execFile);
+function isWsl() {
+    if (process.platform !== "linux")
+        return false;
+    if (process.env.WSL_DISTRO_NAME)
+        return true;
+    try {
+        const proc = readFileSync("/proc/version", "utf8");
+        return /microsoft|wsl/i.test(proc);
+    }
+    catch {
+        return false;
+    }
+}
+export async function openBrowser(url) {
+    // WSL2 → reach into Windows to launch the actual user-facing browser.
+    // We deliberately use PowerShell Start-Process instead of `cmd.exe /c start`
+    // or `wslview` because cmd.exe re-parses the command line and treats `&` in
+    // a URL as a command separator, which fragments URLs like
+    // /cli-auth?state=X&port=Y&challenge=Z into multiple browser-launch attempts
+    // (one with the full URL, one with just ?state=X). Start-Process keeps the
+    // URL atomic.
+    if (isWsl()) {
+        const safeUrl = url.replace(/"/g, '\\"');
+        try {
+            await execFileAsync("powershell.exe", [
+                "-NoProfile",
+                "-Command",
+                `Start-Process "${safeUrl}"`,
+            ]);
+            return { opened: true };
+        }
+        catch {
+            return { opened: false };
+        }
+    }
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        await execFileAsync(cmd, args);
+        return { opened: true };
+    }
+    catch {
+        return { opened: false };
+    }
+}

package/dist/lib/callback.d.ts

@@ -0,0 +1,14 @@
+export interface CallbackResult {
+    code: string;
+}
+export interface CallbackServer {
+    port: number;
+    awaitCallback(opts: {
+        timeoutMs: number;
+    }): Promise<CallbackResult>;
+    close(): Promise<void>;
+}
+export declare function startCallbackServer(expected: {
+    state: string;
+    challenge: string;
+}): Promise<CallbackServer>;

package/dist/lib/callback.js

@@ -0,0 +1,110 @@
+import { createServer } from "node:http";
+import { TimeoutError } from "./errors.js";
+const SUCCESS_PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>pyxis · signed in</title>
+<style>
+  :root {
+    --bg:#0a0c10; --panel:#11141a; --border:#1f2630;
+    --fg:#d6deeb; --dim:#7a8aa3; --cyan:#4fc3f7;
+    --green:#4ade80; --accent:#67e8f9;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  html,body{
+    background:var(--bg);color:var(--fg);min-height:100vh;
+    font-family:'JetBrains Mono','SF Mono',Menlo,Consolas,monospace;
+    display:flex;align-items:center;justify-content:center;padding:24px;
+  }
+  .card{
+    background:var(--panel);border:1px solid var(--border);border-radius:14px;
+    padding:48px 40px;max-width:540px;width:100%;text-align:center;
+    box-shadow:0 24px 60px -24px rgba(0,0,0,0.6),
+               0 0 0 1px rgba(79,195,247,0.04);
+  }
+  .logo{color:var(--cyan);font-size:11px;line-height:1.05;white-space:pre;margin-bottom:10px}
+  .tagline{color:var(--dim);font-size:11px;letter-spacing:0.25em;text-transform:uppercase;margin-bottom:36px}
+  .check{
+    width:64px;height:64px;border-radius:50%;
+    background:rgba(74,222,128,0.10);
+    color:var(--green);font-size:32px;font-weight:700;
+    display:inline-flex;align-items:center;justify-content:center;
+    margin-bottom:18px;
+    box-shadow:0 0 0 1px rgba(74,222,128,0.18),
+               0 0 24px -4px rgba(74,222,128,0.25);
+  }
+  h1{font-size:22px;color:#fff;margin-bottom:10px;font-weight:600;letter-spacing:-0.01em}
+  p{color:var(--dim);font-size:13px;line-height:1.65;max-width:380px;margin:0 auto}
+  .row{
+    margin-top:28px;padding-top:24px;border-top:1px solid var(--border);
+    color:var(--accent);font-size:10px;letter-spacing:0.3em;text-transform:uppercase;
+  }
+  .row .key{color:var(--dim);margin-right:8px}
+  @media (prefers-reduced-motion:no-preference){
+    .check{animation:pulse 2.4s ease-in-out infinite}
+    @keyframes pulse{
+      0%,100%{box-shadow:0 0 0 1px rgba(74,222,128,0.18),0 0 24px -4px rgba(74,222,128,0.25)}
+      50%{box-shadow:0 0 0 1px rgba(74,222,128,0.35),0 0 32px -2px rgba(74,222,128,0.4)}
+    }
+  }
+</style>
+</head>
+<body>
+  <div class="card" role="status" aria-live="polite">
+    <div class="logo">██████╗ ██╗   ██╗██╗  ██╗██╗███████╗
+██╔══██╗╚██╗ ██╔╝╚██╗██╔╝██║██╔════╝
+██████╔╝ ╚████╔╝  ╚███╔╝ ██║███████╗
+██╔═══╝   ╚██╔╝   ██╔██╗ ██║╚════██║
+██║        ██║   ██╔╝ ██╗██║███████║
+╚═╝        ╚═╝   ╚═╝  ╚═╝╚═╝╚══════╝</div>
+    <div class="tagline">the research swarm</div>
+    <div class="check" aria-hidden="true">✓</div>
+    <h1>Signed in</h1>
+    <p>The CLI received your token. You can close this tab and return to your terminal to start researching.</p>
+    <div class="row"><span class="key">next</span><span id="hint">type pyxis research &lt;topic&gt;</span></div>
+  </div>
+  <script>
+    // Try to auto-close (only works if the tab was opened by JS, which it
+    // wasn't — but harmless to attempt). Otherwise the user closes manually.
+    setTimeout(() => { try { window.close(); } catch {} }, 4000);
+  </script>
+</body>
+</html>`;
+export async function startCallbackServer(expected) {
+    let resolveFn = null;
+    let rejectFn = null;
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", `http://localhost`);
+        const state = url.searchParams.get("state");
+        const code = url.searchParams.get("code");
+        if (state !== expected.state || code !== expected.challenge) {
+            res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+            res.end("<h1>Invalid callback</h1><p>State or code mismatch.</p>");
+            return;
+        }
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(SUCCESS_PAGE);
+        if (resolveFn)
+            resolveFn({ code });
+    });
+    await new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const port = server.address().port;
+    return {
+        port,
+        awaitCallback({ timeoutMs }) {
+            return new Promise((resolve, reject) => {
+                resolveFn = resolve;
+                rejectFn = reject;
+                setTimeout(() => {
+                    reject(new TimeoutError(`Callback timeout after ${timeoutMs}ms`));
+                }, timeoutMs);
+            });
+        },
+        async close() {
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}

package/dist/lib/credentials.d.ts

@@ -0,0 +1,11 @@
+export interface Credentials {
+    token: string;
+    wallet: string;
+    exp: number;
+    savedAt: number;
+}
+export declare function _setPathForTests(p: string | null): void;
+export declare function credentialsPath(): string;
+export declare function save(c: Credentials): Promise<void>;
+export declare function load(): Promise<Credentials | null>;
+export declare function clear(): Promise<void>;

package/dist/lib/credentials.js

@@ -0,0 +1,50 @@
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { mkdir, writeFile, readFile, chmod, unlink } from "node:fs/promises";
+let pathOverride = null;
+export function _setPathForTests(p) {
+    pathOverride = p;
+}
+export function credentialsPath() {
+    if (pathOverride)
+        return pathOverride;
+    if (platform() === "win32") {
+        const appdata = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+        return join(appdata, "pyxis", "credentials");
+    }
+    const xdg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(xdg, "pyxis", "credentials");
+}
+export async function save(c) {
+    const p = credentialsPath();
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, JSON.stringify(c, null, 2) + "\n", "utf8");
+    if (platform() !== "win32") {
+        await chmod(p, 0o600);
+    }
+}
+export async function load() {
+    try {
+        const raw = await readFile(credentialsPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.token === "string" &&
+            typeof parsed?.wallet === "string" &&
+            typeof parsed?.exp === "number" &&
+            typeof parsed?.savedAt === "number") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function clear() {
+    try {
+        await unlink(credentialsPath());
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,19 @@
+export declare class AuthError extends Error {
+    readonly code: "AUTH_ERROR";
+}
+export declare class RateLimitError extends Error {
+    retryAfterSeconds: number | null;
+    readonly code: "RATE_LIMIT";
+    constructor(message: string, retryAfterSeconds?: number | null);
+}
+export declare class ServerError extends Error {
+    status: number;
+    readonly code: "SERVER_ERROR";
+    constructor(message: string, status: number);
+}
+export declare class LoginCancelledError extends Error {
+    readonly code: "LOGIN_CANCELLED";
+}
+export declare class TimeoutError extends Error {
+    readonly code: "TIMEOUT";
+}

package/dist/lib/errors.js

@@ -0,0 +1,25 @@
+export class AuthError extends Error {
+    code = "AUTH_ERROR";
+}
+export class RateLimitError extends Error {
+    retryAfterSeconds;
+    code = "RATE_LIMIT";
+    constructor(message, retryAfterSeconds = null) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class ServerError extends Error {
+    status;
+    code = "SERVER_ERROR";
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export class LoginCancelledError extends Error {
+    code = "LOGIN_CANCELLED";
+}
+export class TimeoutError extends Error {
+    code = "TIMEOUT";
+}

package/dist/lib/ui.d.ts

@@ -0,0 +1,16 @@
+export declare function isColorEnabled(): boolean;
+export declare function isBannerEnabled(): boolean;
+export declare const ok: (s: string) => string;
+export declare const fail: (s: string) => string;
+export declare const warn: (s: string) => string;
+export declare const step: (s: string) => string;
+export declare const meta: (label: string, value: string) => string;
+export declare const dim: (s: string) => string;
+export declare const bold: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const bright: (s: string) => string;
+export declare function printBanner(): void;
+export interface Spinner {
+    stop(finalLine?: string): void;
+}
+export declare function spin(label: string): Spinner;

package/dist/lib/ui.js

@@ -0,0 +1,63 @@
+import c from "picocolors";
+import cliSpinners from "cli-spinners";
+export function isColorEnabled() {
+    if (process.env.NO_COLOR === "1")
+        return false;
+    return process.stdout.isTTY === true;
+}
+export function isBannerEnabled() {
+    if (process.env.PYXIS_NO_BANNER === "1")
+        return false;
+    return isColorEnabled();
+}
+export const ok = (s) => `  ${c.green("✓")}  ${s}`;
+export const fail = (s) => `  ${c.red("✗")}  ${s}`;
+export const warn = (s) => `  ${c.yellow("~")}  ${s}`;
+export const step = (s) => `  ${c.cyan("→")}  ${s}`;
+export const meta = (label, value) => `     ${c.dim(label.padEnd(11))}${value}`;
+export const dim = (s) => c.dim(s);
+export const bold = (s) => c.bold(s);
+export const cyan = (s) => c.cyan(s);
+export const bright = (s) => c.cyanBright(s);
+const BANNER = [
+    "██████╗ ██╗   ██╗██╗  ██╗██╗███████╗",
+    "██╔══██╗╚██╗ ██╔╝╚██╗██╔╝██║██╔════╝",
+    "██████╔╝ ╚████╔╝  ╚███╔╝ ██║███████╗",
+    "██╔═══╝   ╚██╔╝   ██╔██╗ ██║╚════██║",
+    "██║        ██║   ██╔╝ ██╗██║███████║",
+    "╚═╝        ╚═╝   ╚═╝  ╚═╝╚═╝╚══════╝",
+];
+export function printBanner() {
+    if (!isBannerEnabled())
+        return;
+    for (const line of BANNER) {
+        process.stdout.write(`  ${c.cyan(line)}\n`);
+    }
+    process.stdout.write(`  ${c.dim("the research swarm")}\n\n`);
+}
+export function spin(label) {
+    if (!isColorEnabled()) {
+        process.stdout.write(`  ${label}\n`);
+        return {
+            stop(finalLine) {
+                if (finalLine)
+                    process.stdout.write(`${finalLine}\n`);
+            },
+        };
+    }
+    const frames = cliSpinners.dots.frames;
+    const intervalMs = cliSpinners.dots.interval;
+    let i = 0;
+    const timer = setInterval(() => {
+        process.stdout.write(`\r  ${c.cyan(frames[i % frames.length] ?? "")}  ${label}`);
+        i++;
+    }, intervalMs);
+    return {
+        stop(finalLine) {
+            clearInterval(timer);
+            process.stdout.write(`\r\x1b[K`);
+            if (finalLine)
+                process.stdout.write(`${finalLine}\n`);
+        },
+    };
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@pyxis-labs/cli",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Pyxis on the command line — run Web3 research from your terminal. Hits usepyxis.com.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "pyxis": "./dist/index.js"
+    "pyxis": "dist/index.js"
   },
   "files": [
     "dist",
@@ -19,6 +19,8 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "dev": "node --import=tsx/esm src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -40,6 +42,11 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "~2.1.0"
+  },
+  "dependencies": {
+    "cli-spinners": "~3.0.0",
+    "picocolors": "~1.1.0"
   }
 }