88eggs-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ptk-studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# 88eggs-cli
+
+CLI for [88eggs](https://github.com/thomaskwan/88eggs-frontend). Signs
+in with your Google account (the same one you'd use on the 88eggs
+frontend) and talks to
+[`88eggs-backend`](https://github.com/thomaskwan/88eggs-backend) on
+your behalf.
+
+This exists so [`88eggs-skills`](https://github.com/ptk-studio/88eggs-skills)
+has something to drive, mirroring how `vercel-labs/agent-skills`' deploy
+skill drives the `vercel` CLI and `supabase/agent-skills` drives the
+`supabase` CLI — a skill shells out to `88eggs`, `88eggs` owns its own
+login, and no skill ever handles a raw token itself.
+
+## Install
+
+```bash
+pnpm install
+pnpm build
+npm link   # makes the `88eggs` command available globally
+```
+
+## Commands
+
+```bash
+88eggs login           # sign in with Google via your browser
+88eggs logout          # sign out, remove stored credentials
+88eggs whoami           # show the currently signed-in account
+88eggs projects list    # list your projects (--scope mine|shared|all)
+```
+
+## Using this with an agent
+
+Install [`88eggs-skills`](https://github.com/ptk-studio/88eggs-skills)
+to let an agent (Claude Code, etc.) drive this CLI on your behalf:
+
+```bash
+npx skills add ptk-studio/88eggs-skills --skill list-projects
+```
+
+The skill checks `88eggs whoami` first and only runs `88eggs login`
+after asking you — since that opens your browser for a real Google
+sign-in — so `88eggs-cli` still needs to be installed and on your
+`PATH` (see **Install** above) before the skill can do anything.
+
+## How auth works
+
+`88eggs login` runs a real OAuth flow against the same Supabase project
+`88eggs-backend`/`88eggs-frontend` already use — there's no separate
+88eggs-specific auth server, and no new backend feature was needed for
+this to work:
+
+1. Opens your browser to Supabase's `/auth/v1/authorize?provider=google`
+   (the same endpoint the frontend's "Continue with Google" button
+   hits), with `redirect_to` pointed at a local callback server this CLI
+   starts on a fixed port (`127.0.0.1:51820`).
+2. You approve in the browser (or, if already signed in and previously
+   consented, this happens instantly with no visible prompt).
+3. Supabase redirects back to the local server with an authorization
+   code; the CLI exchanges it for a real session (access + refresh
+   token) via Supabase's PKCE flow.
+4. The session is written to `~/.88eggs/credentials.json` (mode `600`)
+   — never printed, never handled by anything other than this file.
+
+Every other command reads that file, refreshing the access token via
+the stored refresh token when it's near expiry, and calls
+`88eggs-backend` with it as a normal `Authorization: Bearer` header —
+exactly what the frontend already sends, just from a CLI instead of a
+browser tab. `requireUser()` on the backend doesn't know or care which
+one it came from.
+
+**Note on the redirect URL**: this worked against production without
+adding `http://127.0.0.1:51820/callback` to Supabase's redirect-URL
+allowlist first — empirically, Supabase appears to treat loopback
+(`127.0.0.1`/`localhost`) redirects as implicitly trusted for this kind
+of installed-app flow (matching the general pattern in
+[RFC 8252](https://www.rfc-editor.org/rfc/rfc8252) for native/CLI OAuth
+clients), rather than requiring an exact allowlist entry the way a
+hosted redirect URL would. Flagging this as observed behavior, not
+something confirmed against Supabase's own docs — if a fresh project
+ever rejects the redirect, add `http://127.0.0.1:51820/callback` to
+**Authentication → URL Configuration → Redirect URLs** in the Supabase
+dashboard.
+
+## Local development
+
+Point the CLI at a local Supabase + local `88eggs-backend` instead of
+production. Env vars are prefixed `EGGS_`, not `88EGGS_` — shell env var
+names can't start with a digit:
+
+```bash
+EGGS_SUPABASE_URL=http://127.0.0.1:54321 \
+EGGS_SUPABASE_PUBLISHABLE_KEY=<local anon/publishable key> \
+EGGS_API_URL=http://localhost:3000 \
+88eggs login
+```
+
+Local Supabase has Google sign-in **disabled by default**
+(`supabase/config.toml`'s `[auth.external.google]` block) — enable it
+with real (or test) OAuth credentials first, same as any other local
+Google sign-in testing against `88eggs-backend`.
+
+## Testing
+
+```bash
+pnpm test        # unit tests (credentials storage, token refresh logic)
+pnpm typecheck
+pnpm lint
+```
+
+The OAuth round-trip itself isn't unit-tested (there's no meaningful way
+to fake a real Google consent) — verified manually via `88eggs login`
+against production, confirming the credentials file is written
+correctly and `88eggs projects list` successfully calls the real API
+afterward.

package/dist/commands/login.js

@@ -0,0 +1,84 @@
+import { createServer } from "node:http";
+import open from "open";
+import { createAuthClient } from "../lib/supabase-client.js";
+import { saveCredentials } from "../lib/credentials.js";
+import { LOGIN_CALLBACK_PORT, LOGIN_CALLBACK_URL } from "../lib/constants.js";
+const SUCCESS_HTML = `<!doctype html><html><body style="font-family: system-ui; text-align: center; padding: 4rem;">
+<h1>Signed in to 88eggs</h1><p>You can close this tab and return to your terminal.</p>
+</body></html>`;
+const ERROR_HTML = (message) => `<!doctype html><html><body style="font-family: system-ui; text-align: center; padding: 4rem;">
+<h1>Sign-in failed</h1><p>${message}</p><p>You can close this tab and return to your terminal.</p>
+</body></html>`;
+export async function login() {
+    const supabase = createAuthClient();
+    const { data, error } = await supabase.auth.signInWithOAuth({
+        provider: "google",
+        options: {
+            redirectTo: LOGIN_CALLBACK_URL,
+            skipBrowserRedirect: true,
+        },
+    });
+    if (error || !data.url) {
+        console.error("Failed to start sign-in:", error?.message ?? "no URL returned");
+        process.exitCode = 1;
+        return;
+    }
+    console.log("Opening your browser to sign in with Google...");
+    console.log(`If it doesn't open automatically, visit:\n  ${data.url}\n`);
+    const result = await waitForCallback(supabase, data.url);
+    if (!result.ok) {
+        console.error(`Sign-in failed: ${result.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Signed in as ${result.email}.`);
+}
+function waitForCallback(supabase, authUrl) {
+    return new Promise((resolve) => {
+        const server = createServer((request, response) => {
+            const url = new URL(request.url ?? "/", LOGIN_CALLBACK_URL);
+            if (url.pathname !== "/callback") {
+                response.writeHead(404).end();
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const oauthError = url.searchParams.get("error_description") ?? url.searchParams.get("error");
+            void (async () => {
+                if (oauthError) {
+                    response.writeHead(200, { "Content-Type": "text/html" }).end(ERROR_HTML(oauthError));
+                    server.close();
+                    resolve({ ok: false, message: oauthError });
+                    return;
+                }
+                if (!code) {
+                    response.writeHead(400, { "Content-Type": "text/html" }).end(ERROR_HTML("No authorization code received."));
+                    server.close();
+                    resolve({ ok: false, message: "No authorization code received." });
+                    return;
+                }
+                const { data, error } = await supabase.auth.exchangeCodeForSession(code);
+                if (error || !data.session) {
+                    response.writeHead(200, { "Content-Type": "text/html" }).end(ERROR_HTML(error?.message ?? "Could not complete sign-in."));
+                    server.close();
+                    resolve({ ok: false, message: error?.message ?? "Could not complete sign-in." });
+                    return;
+                }
+                await saveCredentials({
+                    access_token: data.session.access_token,
+                    refresh_token: data.session.refresh_token,
+                    expires_at: data.session.expires_at ?? Math.floor(Date.now() / 1000) + data.session.expires_in,
+                    email: data.session.user.email ?? "",
+                });
+                response.writeHead(200, { "Content-Type": "text/html" }).end(SUCCESS_HTML);
+                server.close();
+                resolve({ ok: true, email: data.session.user.email ?? "unknown" });
+            })();
+        });
+        server.listen(LOGIN_CALLBACK_PORT, () => {
+            void open(authUrl);
+        });
+        server.on("error", (err) => {
+            resolve({ ok: false, message: `Could not start local callback server: ${err.message}` });
+        });
+    });
+}

package/dist/commands/logout.js

@@ -0,0 +1,10 @@
+import { clearCredentials, loadCredentials } from "../lib/credentials.js";
+export async function logout() {
+    const credentials = await loadCredentials();
+    if (!credentials) {
+        console.log("Not signed in.");
+        return;
+    }
+    await clearCredentials();
+    console.log(`Signed out (was ${credentials.email}).`);
+}

package/dist/commands/projects.js

@@ -0,0 +1,32 @@
+import { apiFetch, isErrorBody } from "../lib/api.js";
+export async function listProjects(options) {
+    const query = options.scope && options.scope !== "all" ? `?scope=${options.scope}` : "";
+    let response;
+    try {
+        response = await apiFetch(`/projects${query}`);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : "Request failed.");
+        process.exitCode = 1;
+        return;
+    }
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+        const message = isErrorBody(body)
+            ? body.error
+            : `Request failed with status ${response.status}`;
+        console.error(`Error: ${message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const { projects } = body;
+    if (projects.length === 0) {
+        console.log("No projects found.");
+        return;
+    }
+    for (const project of projects) {
+        const owner = project.owner?.full_name ?? "Unknown";
+        const sharing = project.team ? `shared with ${project.team.name}` : `owner: ${owner}`;
+        console.log(`${project.name} -- ${sharing} -- updated ${project.updated_at}`);
+    }
+}

package/dist/commands/whoami.js

@@ -0,0 +1,16 @@
+import { loadCredentials } from "../lib/credentials.js";
+// Deliberately reads the local credentials file only -- no network call,
+// same spirit as `vercel whoami` -- a fast, side-effect-free check a
+// skill can run before attempting anything else. It doesn't verify the
+// token is still valid server-side (a revoked/expired session still
+// reports as "signed in" here); `88eggs projects list` etc. are what
+// surface a real auth failure.
+export async function whoami() {
+    const credentials = await loadCredentials();
+    if (!credentials) {
+        console.log("Not signed in. Run `88eggs login`.");
+        process.exitCode = 1;
+        return;
+    }
+    console.log(credentials.email);
+}

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { login } from "./commands/login.js";
+import { logout } from "./commands/logout.js";
+import { whoami } from "./commands/whoami.js";
+import { listProjects } from "./commands/projects.js";
+const program = new Command();
+program.name("88eggs").description("CLI for 88eggs").version("0.1.0");
+program
+    .command("login")
+    .description("Sign in with Google via your browser")
+    .action(login);
+program
+    .command("logout")
+    .description("Sign out and remove stored credentials")
+    .action(logout);
+program
+    .command("whoami")
+    .description("Show the currently signed-in account")
+    .action(whoami);
+const projects = program.command("projects").description("Manage 88eggs projects");
+projects
+    .command("list")
+    .description("List your projects")
+    .option("--scope <scope>", "mine, shared, or all", "all")
+    .action((options) => listProjects(options));
+program.parseAsync(process.argv);

package/dist/lib/api.js

@@ -0,0 +1,43 @@
+import { createAuthClient } from "./supabase-client.js";
+import { loadCredentials, saveCredentials } from "./credentials.js";
+import { BACKEND_API_URL } from "./constants.js";
+// Refreshes silently when the stored access token is at or near expiry
+// (within 60s) -- every command that hits the API goes through this
+// rather than each one separately checking expiry.
+async function getAccessToken() {
+    const credentials = await loadCredentials();
+    if (!credentials) {
+        throw new Error("Not signed in. Run `88eggs login` first.");
+    }
+    const now = Math.floor(Date.now() / 1000);
+    if (credentials.expires_at - now > 60) {
+        return credentials.access_token;
+    }
+    const supabase = createAuthClient();
+    const { data, error } = await supabase.auth.refreshSession({
+        refresh_token: credentials.refresh_token,
+    });
+    if (error || !data.session) {
+        throw new Error(`Session expired and refresh failed (${error?.message ?? "unknown error"}). Run \`88eggs login\` again.`);
+    }
+    await saveCredentials({
+        access_token: data.session.access_token,
+        refresh_token: data.session.refresh_token,
+        expires_at: data.session.expires_at ?? now + data.session.expires_in,
+        email: data.session.user.email ?? credentials.email,
+    });
+    return data.session.access_token;
+}
+export async function apiFetch(path, init) {
+    const token = await getAccessToken();
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    headers.set("Content-Type", "application/json");
+    return fetch(`${BACKEND_API_URL}${path}`, { ...init, headers });
+}
+export function isErrorBody(body) {
+    return (typeof body === "object" &&
+        body !== null &&
+        "error" in body &&
+        typeof body.error === "string");
+}

package/dist/lib/constants.js

@@ -0,0 +1,14 @@
+// Public, client-safe values -- same ones 88eggs-frontend embeds in its
+// own bundle (NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY).
+// Overridable via env vars for local development against a local
+// Supabase/backend instance. Prefixed EGGS_ not 88EGGS_ -- shell env var
+// names can't start with a digit.
+export const SUPABASE_URL = process.env.EGGS_SUPABASE_URL ?? "https://kuptszxhqksekiltppgu.supabase.co";
+export const SUPABASE_PUBLISHABLE_KEY = process.env.EGGS_SUPABASE_PUBLISHABLE_KEY ??
+    "sb_publishable_91cZ6e6YU1MrEoZbBbXaXA_Rk0TuAHT";
+export const BACKEND_API_URL = process.env.EGGS_API_URL ?? "https://88eggs-backend.vercel.app";
+// Fixed port for the login callback server -- fixed (not random) so it
+// can be added once to Supabase's redirect-URL allowlist as an exact
+// match, no wildcard needed.
+export const LOGIN_CALLBACK_PORT = 51820;
+export const LOGIN_CALLBACK_URL = `http://127.0.0.1:${LOGIN_CALLBACK_PORT}/callback`;

package/dist/lib/credentials.js

@@ -0,0 +1,24 @@
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// Overridable so tests don't touch a real developer's ~/.88eggs.
+const CONFIG_DIR = process.env.EGGS_CONFIG_DIR ?? join(homedir(), ".88eggs");
+const CREDENTIALS_PATH = join(CONFIG_DIR, "credentials.json");
+export async function saveCredentials(credentials) {
+    await mkdir(CONFIG_DIR, { recursive: true });
+    await writeFile(CREDENTIALS_PATH, JSON.stringify(credentials, null, 2), {
+        mode: 0o600,
+    });
+}
+export async function loadCredentials() {
+    try {
+        const raw = await readFile(CREDENTIALS_PATH, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function clearCredentials() {
+    await rm(CREDENTIALS_PATH, { force: true });
+}

package/dist/lib/supabase-client.js

@@ -0,0 +1,32 @@
+import { createClient } from "@supabase/supabase-js";
+import { SUPABASE_PUBLISHABLE_KEY, SUPABASE_URL } from "./constants.js";
+// In-memory storage adapter -- Node has no localStorage, and each CLI
+// invocation is a fresh process anyway, so there's nothing worth
+// persisting via supabase-js's own storage. It only needs *some* backing
+// store to hold the PKCE code_verifier between signInWithOAuth() and
+// exchangeCodeForSession() within a single `88eggs login` run. Session
+// persistence across invocations is handled entirely by our own
+// credentials.json (see lib/credentials.ts), not by this client.
+function createMemoryStorage() {
+    const store = new Map();
+    return {
+        getItem: (key) => store.get(key) ?? null,
+        setItem: (key, value) => {
+            store.set(key, value);
+        },
+        removeItem: (key) => {
+            store.delete(key);
+        },
+    };
+}
+export function createAuthClient() {
+    return createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, {
+        auth: {
+            flowType: "pkce",
+            persistSession: false,
+            autoRefreshToken: false,
+            detectSessionInUrl: false,
+            storage: createMemoryStorage(),
+        },
+    });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "88eggs-cli",
+  "version": "0.1.0",
+  "description": "CLI for 88eggs -- sign in and drive 88eggs-backend from the command line.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ptk-studio/88eggs-cli.git"
+  },
+  "homepage": "https://github.com/ptk-studio/88eggs-cli#readme",
+  "bugs": "https://github.com/ptk-studio/88eggs-cli/issues",
+  "type": "module",
+  "bin": {
+    "88eggs": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.58.0",
+    "commander": "^12.1.0",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.10.2",
+    "eslint": "^9.17.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.62.1",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}