@wafflebase/cli 0.1.0 → 0.2.1

package/dist/bin.js

@@ -5,10 +5,22 @@ import { registerTabCommand } from './commands/tab.js';
 import { registerCellCommand } from './commands/cell.js';
 import { registerApiKeyCommand } from './commands/api-key.js';
 import { registerSchemaCommand } from './commands/schema.js';
+import { registerLoginCommand } from './commands/login.js';
+import { registerLogoutCommand } from './commands/logout.js';
+import { registerStatusCommand } from './commands/status.js';
+import { registerCtxCommand } from './commands/ctx.js';
+import { registerImportCommand } from './commands/import.js';
+import { registerExportCommand } from './commands/export.js';
 const program = createProgram();
+registerLoginCommand(program);
+registerLogoutCommand(program);
+registerStatusCommand(program);
+registerCtxCommand(program);
 registerDocumentCommand(program);
 registerTabCommand(program);
 registerCellCommand(program);
 registerApiKeyCommand(program);
+registerImportCommand(program);
+registerExportCommand(program);
 registerSchemaCommand(program);
 program.parse();

package/dist/client/http-client.d.ts

@@ -16,6 +16,10 @@ export declare class HttpClient {
     constructor(config: CliConfig);
     private get headers();
     private get base();
+    /**
+     * Attempt to refresh the JWT session. Returns true on success.
+     */
+    private refreshSession;
     request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>>;
     listDocuments(): Promise<ApiResponse<unknown[]>>;
     createDocument(title: string): Promise<ApiResponse<unknown>>;

package/dist/client/http-client.js

@@ -1,18 +1,58 @@
+import { loadSession, saveSession, decodeJwtExpiry, } from '../config/session.js';
 export class HttpClient {
     config;
     constructor(config) {
         this.config = config;
     }
     get headers() {
-        return {
+        const h = {
             'Content-Type': 'application/json',
-            Authorization: `Bearer ${this.config.apiKey}`,
         };
+        if (this.config.authMode === 'api-key' && this.config.apiKey) {
+            h['Authorization'] = `Bearer ${this.config.apiKey}`;
+        }
+        else if (this.config.authMode === 'jwt' && this.config.accessToken) {
+            h['Authorization'] = `Bearer ${this.config.accessToken}`;
+        }
+        return h;
     }
     get base() {
         const server = this.config.server.replace(/\/$/, '');
         return `${server}/api/v1/workspaces/${this.config.workspace}`;
     }
+    /**
+     * Attempt to refresh the JWT session. Returns true on success.
+     */
+    async refreshSession() {
+        if (!this.config.refreshToken)
+            return false;
+        const server = this.config.server.replace(/\/$/, '');
+        const res = await fetch(`${server}/auth/refresh`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refreshToken: this.config.refreshToken }),
+        });
+        if (!res.ok)
+            return false;
+        const data = (await res.json().catch(() => null));
+        if (!data?.accessToken || !data?.refreshToken)
+            return false;
+        // Update in-memory config
+        this.config.accessToken = data.accessToken;
+        this.config.refreshToken = data.refreshToken;
+        // Persist refreshed tokens to session file (if it exists).
+        // If the session file is missing the in-memory config is already
+        // updated, so the current process will keep working; the user can
+        // run `wafflebase login` to recreate the session file.
+        const session = loadSession();
+        if (session) {
+            session.accessToken = data.accessToken;
+            session.refreshToken = data.refreshToken;
+            session.expiresAt = decodeJwtExpiry(data.accessToken);
+            saveSession(session);
+        }
+        return true;
+    }
     async request(method, path, body) {
         const url = `${this.base}${path}`;
         const res = await fetch(url, {
@@ -20,6 +60,33 @@ export class HttpClient {
             headers: this.headers,
             body: body ? JSON.stringify(body) : undefined,
         });
+        // Auto-refresh on 401 for JWT auth (one attempt only)
+        if (res.status === 401 &&
+            this.config.authMode === 'jwt' &&
+            this.config.refreshToken) {
+            const refreshed = await this.refreshSession();
+            if (refreshed) {
+                // Retry the original request with new token
+                const retryRes = await fetch(url, {
+                    method,
+                    headers: this.headers,
+                    body: body ? JSON.stringify(body) : undefined,
+                });
+                const retryData = (await retryRes.json().catch(() => null));
+                return { ok: retryRes.ok, status: retryRes.status, data: retryData };
+            }
+            // Refresh failed — return a clear error
+            return {
+                ok: false,
+                status: 401,
+                data: {
+                    error: {
+                        code: 'SESSION_EXPIRED',
+                        message: 'Session expired. Run `wafflebase login`.',
+                    },
+                },
+            };
+        }
         const data = (await res.json().catch(() => null));
         return { ok: res.ok, status: res.status, data };
     }

package/dist/commands/ctx.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+import type { WorkspaceInfo } from '../config/session.js';
+export declare function formatWorkspaceList(workspaces: WorkspaceInfo[], activeId: string): string;
+export declare function findWorkspace(workspaces: WorkspaceInfo[], query: string): WorkspaceInfo | undefined;
+export declare function registerCtxCommand(program: Command): void;

package/dist/commands/ctx.js

@@ -0,0 +1,56 @@
+import { loadSession, saveSession } from '../config/session.js';
+export function formatWorkspaceList(workspaces, activeId) {
+    return workspaces
+        .map((ws) => {
+        const marker = ws.id === activeId ? '*' : ' ';
+        return `${marker} ${ws.id.slice(0, 8)}  ${ws.name}`;
+    })
+        .join('\n');
+}
+export function findWorkspace(workspaces, query) {
+    // Exact ID match
+    const byId = workspaces.find((ws) => ws.id === query);
+    if (byId)
+        return byId;
+    // Exact name match (case-insensitive)
+    const byName = workspaces.find((ws) => ws.name.toLowerCase() === query.toLowerCase());
+    if (byName)
+        return byName;
+    // Prefix match on ID
+    const byPrefix = workspaces.filter((ws) => ws.id.startsWith(query));
+    if (byPrefix.length === 1)
+        return byPrefix[0];
+    return undefined;
+}
+export function registerCtxCommand(program) {
+    const ctx = program.command('ctx').description('Workspace context switching');
+    ctx
+        .command('list')
+        .description('List workspaces')
+        .action(() => {
+        const session = loadSession();
+        if (!session) {
+            console.log('Not logged in. Run `wafflebase login`.');
+            return;
+        }
+        console.log(formatWorkspaceList(session.workspaces, session.activeWorkspace));
+    });
+    ctx
+        .command('switch <name-or-id>')
+        .description('Switch active workspace')
+        .action((query) => {
+        const session = loadSession();
+        if (!session) {
+            console.error('Not logged in. Run `wafflebase login`.');
+            process.exit(1);
+        }
+        const ws = findWorkspace(session.workspaces, query);
+        if (!ws) {
+            console.error(`Workspace not found: ${query}`);
+            process.exit(1);
+        }
+        session.activeWorkspace = ws.id;
+        saveSession(session);
+        console.log(`Switched to ${ws.name}.`);
+    });
+}

package/dist/commands/export.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerExportCommand(program: Command): void;

package/dist/commands/export.js

@@ -0,0 +1,52 @@
+import { writeFileSync } from 'node:fs';
+import { extname } from 'node:path';
+import { getGlobalOpts, getClient } from './root.js';
+import { outputError } from '../output/formatter.js';
+import { formatCsv } from '../output/csv.js';
+import { formatJson } from '../output/json.js';
+const VALID_FORMATS = ['csv', 'json'];
+function detectFormat(file, formatFlag) {
+    if (formatFlag) {
+        if (!VALID_FORMATS.includes(formatFlag)) {
+            throw new Error(`Unsupported format "${formatFlag}". Use csv or json.`);
+        }
+        return formatFlag;
+    }
+    const ext = extname(file).toLowerCase();
+    if (ext === '.json')
+        return 'json';
+    return 'csv';
+}
+export function registerExportCommand(program) {
+    program
+        .command('export <doc-id> <file>')
+        .description('Export tab data to CSV/JSON')
+        .option('--tab <tab-id>', 'Source tab', 'tab-1')
+        .option('--range <range>', 'Cell range to export (e.g. A1:D100)')
+        .option('--file-format <fmt>', 'File format (csv, json)')
+        .action(async function (docId, file) {
+        const opts = getGlobalOpts(this);
+        const localOpts = this.opts();
+        try {
+            const res = await getClient(opts).getCells(docId, localOpts.tab, localOpts.range);
+            if (!res.ok) {
+                const msg = res.data?.error?.message;
+                throw new Error(msg ?? `HTTP ${res.status}`);
+            }
+            const fmt = detectFormat(file, localOpts.fileFormat);
+            const formatted = fmt === 'csv' ? formatCsv(res.data) : formatJson(res.data);
+            if (file === '-') {
+                process.stdout.write(formatted + '\n');
+            }
+            else {
+                writeFileSync(file, formatted + '\n', 'utf-8');
+                if (!opts.quiet) {
+                    console.log(`Exported to ${file}`);
+                }
+            }
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+}

package/dist/commands/import.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerImportCommand(program: Command): void;

package/dist/commands/import.js

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+import { getGlobalOpts, getClient, getConfig } from './root.js';
+import { output, outputError } from '../output/formatter.js';
+import { printDryRun } from '../client/dry-run.js';
+import { parseCsv, parseStartRef, buildCellMap } from '../util/csv-parse.js';
+const VALID_FORMATS = ['csv', 'json'];
+function detectFormat(file, formatFlag) {
+    if (formatFlag) {
+        if (!VALID_FORMATS.includes(formatFlag)) {
+            throw new Error(`Unsupported format "${formatFlag}". Use csv or json.`);
+        }
+        return formatFlag;
+    }
+    const ext = extname(file).toLowerCase();
+    if (ext === '.json')
+        return 'json';
+    return 'csv';
+}
+function readInput(file) {
+    if (file === '-') {
+        return readFileSync(0, 'utf-8');
+    }
+    return readFileSync(file, 'utf-8');
+}
+export function registerImportCommand(program) {
+    program
+        .command('import <doc-id> <file>')
+        .description('Import CSV/JSON into a tab')
+        .option('--tab <tab-id>', 'Target tab', 'tab-1')
+        .option('--file-format <fmt>', 'File format (csv, json)')
+        .option('--start <ref>', 'Top-left cell to start import', 'A1')
+        .action(async function (docId, file) {
+        const opts = getGlobalOpts(this);
+        const localOpts = this.opts();
+        try {
+            const fmt = detectFormat(file, localOpts.fileFormat);
+            const raw = readInput(file);
+            let rows;
+            if (fmt === 'json') {
+                const parsed = JSON.parse(raw);
+                // Expect either array of arrays or array of objects
+                if (Array.isArray(parsed) && parsed.length > 0) {
+                    if (Array.isArray(parsed[0])) {
+                        rows = parsed;
+                    }
+                    else if (typeof parsed[0] === 'object') {
+                        // Array of objects → header row + value rows
+                        const objs = parsed;
+                        const keys = Object.keys(objs[0]);
+                        rows = [keys, ...objs.map((o) => keys.map((k) => String(o[k] ?? '')))];
+                    }
+                    else {
+                        throw new Error('JSON must be an array of arrays or array of objects');
+                    }
+                }
+                else {
+                    throw new Error('JSON must be a non-empty array');
+                }
+            }
+            else {
+                rows = parseCsv(raw);
+            }
+            if (rows.length === 0) {
+                throw new Error('No data to import');
+            }
+            const { row: startRow, col: startCol } = parseStartRef(localOpts.start);
+            const cells = buildCellMap(rows, startRow, startCol);
+            const cellCount = Object.keys(cells).length;
+            if (opts.dryRun) {
+                printDryRun(getConfig(opts), 'PATCH', `/documents/${docId}/tabs/${localOpts.tab}/cells`, {
+                    cells,
+                });
+                return;
+            }
+            const res = await getClient(opts).batchCells(docId, localOpts.tab, cells);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const result = typeof res.data === 'object' && res.data !== null
+                ? { imported: cellCount, ...res.data }
+                : { imported: cellCount };
+            output(result, opts.format, opts.quiet);
+        }
+        catch (e) {
+            outputError(e, opts.quiet);
+        }
+    });
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerLoginCommand(program: Command): void;

package/dist/commands/login.js

@@ -0,0 +1,220 @@
+import { createServer } from 'node:http';
+import { createInterface } from 'node:readline';
+import { loadSession, saveSession, decodeJwtExpiry, } from '../config/session.js';
+import { DEFAULT_SERVER } from '../config/config.js';
+export function registerLoginCommand(program) {
+    program
+        .command('login')
+        .description('Log in via GitHub OAuth in the browser')
+        .action(async function () {
+        const parentOpts = this.optsWithGlobals();
+        const server = (parentOpts.server ?? DEFAULT_SERVER).replace(/\/$/, '');
+        // 1. Check existing session
+        const existing = loadSession();
+        if (existing) {
+            const answer = await ask(`Logged in as ${existing.user.username}. Continue? [Y/n] `);
+            if (answer.toLowerCase() === 'n') {
+                console.log('Cancelled.');
+                return;
+            }
+        }
+        // 2. Start local HTTP server
+        const { port, waitForCallback, close } = await startCallbackServer();
+        // 3. Build OAuth URL and open browser
+        const oauthUrl = `${server}/auth/github?mode=cli&port=${port}`;
+        console.error(`Opening browser: ${oauthUrl}`);
+        console.error('If the browser does not open, visit the URL above.');
+        try {
+            const open = (await import('open')).default;
+            await open(oauthUrl);
+        }
+        catch {
+            // Browser open failed — URL was already printed
+        }
+        // 4. Wait for callback
+        let code;
+        try {
+            code = await waitForCallback();
+        }
+        finally {
+            close();
+        }
+        // 5. Exchange code for tokens
+        const exchangeRes = await fetch(`${server}/auth/cli/exchange`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ code }),
+        });
+        if (!exchangeRes.ok) {
+            console.error('Token exchange failed. Try again with `wafflebase login`.');
+            process.exit(1);
+        }
+        const tokens = (await exchangeRes.json());
+        // 6. Get user info
+        const meRes = await fetch(`${server}/auth/me`, {
+            headers: { Authorization: `Bearer ${tokens.accessToken}` },
+        });
+        if (!meRes.ok) {
+            console.error('Failed to fetch user info.');
+            process.exit(1);
+        }
+        const user = (await meRes.json());
+        // 7. Get workspace list
+        const wsRes = await fetch(`${server}/workspaces`, {
+            headers: { Authorization: `Bearer ${tokens.accessToken}` },
+        });
+        if (!wsRes.ok) {
+            console.error(`Failed to fetch workspaces (HTTP ${wsRes.status}). Try again with \`wafflebase login\`.`);
+            process.exit(1);
+        }
+        const workspaces = (await wsRes.json());
+        // 8. Select workspace
+        let activeWorkspace = '';
+        if (workspaces.length === 0) {
+            console.log('No workspaces found.');
+        }
+        else if (workspaces.length === 1) {
+            activeWorkspace = workspaces[0].id;
+            console.log(`Workspace: ${workspaces[0].name}`);
+        }
+        else {
+            console.log('Select a workspace:');
+            workspaces.forEach((ws, i) => {
+                console.log(`  ${i + 1}. ${ws.name} (${ws.id.slice(0, 8)})`);
+            });
+            const choice = await ask('Enter number: ');
+            const idx = parseInt(choice, 10) - 1;
+            if (idx >= 0 && idx < workspaces.length) {
+                activeWorkspace = workspaces[idx].id;
+            }
+            else {
+                activeWorkspace = workspaces[0].id;
+                console.log(`Invalid choice, using ${workspaces[0].name}.`);
+            }
+        }
+        // 9. Save session
+        const session = {
+            server,
+            user,
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: decodeJwtExpiry(tokens.accessToken),
+            activeWorkspace,
+            workspaces,
+        };
+        saveSession(session);
+        console.log(`Logged in as ${user.username}.`);
+    });
+}
+function ask(prompt) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function startCallbackServer() {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let callbackResolve;
+        let callbackReject;
+        const callbackPromise = new Promise((res, rej) => {
+            callbackResolve = res;
+            callbackReject = rej;
+        });
+        const srv = createServer((req, res) => {
+            const url = new URL(req.url ?? '/', `http://127.0.0.1`);
+            if (url.pathname !== '/callback') {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const code = url.searchParams.get('code');
+            if (!code) {
+                res.writeHead(400);
+                res.end('Missing code');
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(`<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Wafflebase CLI</title>
+<style>
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    min-height: 100vh;
+    margin: 0;
+    background: #fafafa;
+    color: #1a1a1a;
+  }
+  .card {
+    text-align: center;
+    padding: 3rem 2.5rem;
+    background: #fff;
+    border-radius: 12px;
+    box-shadow: 0 1px 3px rgba(0,0,0,0.08), 0 4px 12px rgba(0,0,0,0.04);
+  }
+  .icon { font-size: 2.5rem; margin-bottom: 0.5rem; }
+  h2 { margin: 0 0 0.5rem; font-size: 1.25rem; font-weight: 600; }
+  p { margin: 0; color: #666; font-size: 0.95rem; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon">&#10003;</div>
+    <h2>Login successful!</h2>
+    <p>You can close this tab and return to the terminal.</p>
+  </div>
+</body>
+</html>`);
+            if (!settled) {
+                settled = true;
+                callbackResolve(code);
+            }
+        });
+        const timeout = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                callbackReject(new Error('Login timed out. Try again with `wafflebase login`.'));
+            }
+            srv.close();
+        }, 30_000);
+        // Try to listen on a random port (up to 3 attempts)
+        let attempts = 0;
+        const tryListen = () => {
+            attempts++;
+            srv.listen(0, '127.0.0.1', () => {
+                const addr = srv.address();
+                if (!addr || typeof addr === 'string') {
+                    reject(new Error('Failed to start callback server'));
+                    return;
+                }
+                resolve({
+                    port: addr.port,
+                    waitForCallback: () => callbackPromise,
+                    close: () => {
+                        clearTimeout(timeout);
+                        srv.close();
+                    },
+                });
+            });
+        };
+        srv.on('error', (err) => {
+            if (err.code === 'EADDRINUSE' && attempts < 3) {
+                tryListen();
+            }
+            else {
+                reject(err);
+            }
+        });
+        tryListen();
+    });
+}

package/dist/commands/logout.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerLogoutCommand(program: Command): void;

package/dist/commands/logout.js

@@ -0,0 +1,10 @@
+import { clearSession } from '../config/session.js';
+export function registerLogoutCommand(program) {
+    program
+        .command('logout')
+        .description('Log out and clear session')
+        .action(() => {
+        clearSession();
+        console.log('Logged out.');
+    });
+}

package/dist/commands/root.js

@@ -1,6 +1,9 @@
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { resolveConfig } from '../config/config.js';
 import { HttpClient } from '../client/http-client.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
 export function getGlobalOpts(cmd) {
     const root = cmd.optsWithGlobals();
     return root;
@@ -21,7 +24,7 @@ export function createProgram() {
     program
         .name('wafflebase')
         .description('CLI for Wafflebase spreadsheet API')
-        .version('0.1.0')
+        .version(version)
         .option('--server <url>', 'Server URL')
         .option('--api-key <key>', 'API key')
         .option('--workspace <id>', 'Workspace ID')

package/dist/commands/status.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerStatusCommand(program: Command): void;

package/dist/commands/status.js

@@ -0,0 +1,22 @@
+import { loadSession, isSessionExpired } from '../config/session.js';
+export function registerStatusCommand(program) {
+    program
+        .command('status')
+        .description('Show current auth state')
+        .action(() => {
+        const session = loadSession();
+        if (!session) {
+            console.log('Not logged in. Run `wafflebase login`.');
+            return;
+        }
+        console.log(`Logged in as ${session.user.username} (${session.user.email})`);
+        console.log(`Server:    ${session.server}`);
+        const ws = session.workspaces.find((w) => w.id === session.activeWorkspace);
+        const wsLabel = ws
+            ? `${ws.name} (${session.activeWorkspace.slice(0, 8)}...)`
+            : session.activeWorkspace;
+        console.log(`Workspace: ${wsLabel}`);
+        const expired = isSessionExpired(session);
+        console.log(`Session:   ${expired ? 'expired' : 'valid'} (expires ${session.expiresAt})`);
+    });
+}

package/dist/config/config.d.ts

@@ -1,10 +1,31 @@
+export declare const DEFAULT_SERVER = "https://api.wafflebase.io";
 export interface CliConfig {
     server: string;
     apiKey: string;
     workspace: string;
+    authMode: 'api-key' | 'jwt' | 'none';
+    accessToken?: string;
+    refreshToken?: string;
 }
 /**
- * Resolve CLI configuration from flags > env > config file.
+ * Migrate config from old path (~/.config/wafflebase/config.yaml) to new path
+ * (~/.wafflebase/config.yaml) if needed.
+ */
+export declare function migrateConfigIfNeeded(newPath: string, oldPath?: string): void;
+/**
+ * Return the resolved config file path.
+ * WAFFLEBASE_CONFIG env var overrides everything; otherwise defaults to
+ * ~/.wafflebase/config.yaml (with migration from old ~/.config/wafflebase path).
+ */
+export declare function getConfigPath(): string;
+/**
+ * Resolve CLI configuration from flags > env > session > config file.
+ *
+ * Auth resolution order:
+ * 1. Flag/env `--api-key` or `WAFFLEBASE_API_KEY` → API key auth
+ * 2. Session `~/.wafflebase/session.json` exists and token valid → JWT auth
+ * 3. Config profile `api-key` → API key auth
+ * 4. None → empty (commands will fail)
  */
 export declare function resolveConfig(flags: {
     server?: string;

package/dist/config/config.js

@@ -1,31 +1,117 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, existsSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
+import { loadSession, isSessionExpired } from './session.js';
+export const DEFAULT_SERVER = 'https://api.wafflebase.io';
 /**
- * Resolve CLI configuration from flags > env > config file.
+ * Migrate config from old path (~/.config/wafflebase/config.yaml) to new path
+ * (~/.wafflebase/config.yaml) if needed.
+ */
+export function migrateConfigIfNeeded(newPath, oldPath = join(homedir(), '.config', 'wafflebase', 'config.yaml')) {
+    if (existsSync(newPath))
+        return;
+    if (!existsSync(oldPath))
+        return;
+    try {
+        mkdirSync(dirname(newPath), { recursive: true });
+        copyFileSync(oldPath, newPath);
+        process.stderr.write(`[wafflebase] Config migrated from ${oldPath} to ${newPath}\n`);
+    }
+    catch {
+        // Silent failure — migration is best-effort
+    }
+}
+/**
+ * Return the resolved config file path.
+ * WAFFLEBASE_CONFIG env var overrides everything; otherwise defaults to
+ * ~/.wafflebase/config.yaml (with migration from old ~/.config/wafflebase path).
+ */
+export function getConfigPath() {
+    if (process.env.WAFFLEBASE_CONFIG) {
+        return process.env.WAFFLEBASE_CONFIG;
+    }
+    const newPath = join(homedir(), '.wafflebase', 'config.yaml');
+    migrateConfigIfNeeded(newPath);
+    return newPath;
+}
+/**
+ * Resolve CLI configuration from flags > env > session > config file.
+ *
+ * Auth resolution order:
+ * 1. Flag/env `--api-key` or `WAFFLEBASE_API_KEY` → API key auth
+ * 2. Session `~/.wafflebase/session.json` exists and token valid → JWT auth
+ * 3. Config profile `api-key` → API key auth
+ * 4. None → empty (commands will fail)
  */
 export function resolveConfig(flags) {
     const profile = loadProfile(flags.profile ?? 'default');
+    // Step 1: Check flags/env for API key
+    const flagOrEnvApiKey = flags.apiKey ?? process.env.WAFFLEBASE_API_KEY ?? undefined;
+    if (flagOrEnvApiKey) {
+        return {
+            server: flags.server ??
+                process.env.WAFFLEBASE_SERVER ??
+                profile.server ??
+                DEFAULT_SERVER,
+            apiKey: flagOrEnvApiKey,
+            workspace: flags.workspace ??
+                process.env.WAFFLEBASE_WORKSPACE ??
+                profile.workspace ??
+                '',
+            authMode: 'api-key',
+        };
+    }
+    // Step 2: Try session
+    const session = loadSession();
+    if (session && !isSessionExpired(session)) {
+        return {
+            server: flags.server ??
+                process.env.WAFFLEBASE_SERVER ??
+                session.server ??
+                profile.server ??
+                DEFAULT_SERVER,
+            apiKey: '',
+            workspace: flags.workspace ??
+                process.env.WAFFLEBASE_WORKSPACE ??
+                session.activeWorkspace ??
+                profile.workspace ??
+                '',
+            authMode: 'jwt',
+            accessToken: session.accessToken,
+            refreshToken: session.refreshToken,
+        };
+    }
+    // Step 3: Fallback to config profile API key
+    const profileApiKey = profile['api-key'];
+    if (profileApiKey) {
+        return {
+            server: flags.server ??
+                process.env.WAFFLEBASE_SERVER ??
+                profile.server ??
+                DEFAULT_SERVER,
+            apiKey: profileApiKey,
+            workspace: flags.workspace ??
+                process.env.WAFFLEBASE_WORKSPACE ??
+                profile.workspace ??
+                '',
+            authMode: 'api-key',
+        };
+    }
+    // Step 4: Nothing available
     return {
         server: flags.server ??
             process.env.WAFFLEBASE_SERVER ??
             profile.server ??
-            'http://localhost:3000',
-        apiKey: flags.apiKey ??
-            process.env.WAFFLEBASE_API_KEY ??
-            profile['api-key'] ??
-            '',
+            DEFAULT_SERVER,
+        apiKey: '',
         workspace: flags.workspace ??
             process.env.WAFFLEBASE_WORKSPACE ??
             profile.workspace ??
             '',
+        authMode: 'none',
     };
 }
-function getConfigPath() {
-    return (process.env.WAFFLEBASE_CONFIG ??
-        join(homedir(), '.config', 'wafflebase', 'config.yaml'));
-}
 function loadProfile(name) {
     const configPath = getConfigPath();
     if (!existsSync(configPath))

package/dist/config/session.d.ts

@@ -0,0 +1,49 @@
+export interface SessionUser {
+    id: number;
+    username: string;
+    email: string;
+    photo: string | null;
+}
+export interface WorkspaceInfo {
+    id: string;
+    name: string;
+}
+export interface Session {
+    server: string;
+    user: SessionUser;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    activeWorkspace: string;
+    workspaces: WorkspaceInfo[];
+}
+/**
+ * Returns the default session file path: ~/.wafflebase/session.json
+ */
+export declare function getSessionPath(): string;
+/**
+ * Loads the session from disk. Returns null if the file does not exist or
+ * contains invalid JSON.
+ */
+export declare function loadSession(path?: string): Session | null;
+/**
+ * Writes the session to disk with owner-only (0600) permissions.
+ * Creates the parent directory if it does not exist.
+ */
+export declare function saveSession(session: Session, path?: string): void;
+/**
+ * Deletes the session file if it exists. No-op otherwise.
+ */
+export declare function clearSession(path?: string): void;
+/**
+ * Returns true when the session's expiresAt timestamp is in the past.
+ */
+export declare function isSessionExpired(session: Session): boolean;
+/**
+ * Decodes the `exp` claim from a JWT's payload segment and returns an ISO
+ * 8601 string.
+ *
+ * JWT format: <header>.<payload>.<signature>
+ * The payload is base64url-encoded JSON.
+ */
+export declare function decodeJwtExpiry(token: string): string;

package/dist/config/session.js

@@ -0,0 +1,74 @@
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, chmodSync, } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+/**
+ * Returns the default session file path: ~/.wafflebase/session.json
+ */
+export function getSessionPath() {
+    if (process.env.WAFFLEBASE_SESSION) {
+        return process.env.WAFFLEBASE_SESSION;
+    }
+    return join(homedir(), '.wafflebase', 'session.json');
+}
+/**
+ * Loads the session from disk. Returns null if the file does not exist or
+ * contains invalid JSON.
+ */
+export function loadSession(path = getSessionPath()) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Writes the session to disk with owner-only (0600) permissions.
+ * Creates the parent directory if it does not exist.
+ */
+export function saveSession(session, path = getSessionPath()) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(session, null, 2), { mode: 0o600 });
+    // Explicitly chmod in case the file already existed with different permissions
+    chmodSync(path, 0o600);
+}
+/**
+ * Deletes the session file if it exists. No-op otherwise.
+ */
+export function clearSession(path = getSessionPath()) {
+    if (existsSync(path)) {
+        unlinkSync(path);
+    }
+}
+/**
+ * Returns true when the session's expiresAt timestamp is in the past.
+ */
+export function isSessionExpired(session) {
+    return new Date(session.expiresAt) <= new Date();
+}
+/**
+ * Decodes the `exp` claim from a JWT's payload segment and returns an ISO
+ * 8601 string.
+ *
+ * JWT format: <header>.<payload>.<signature>
+ * The payload is base64url-encoded JSON.
+ */
+export function decodeJwtExpiry(token) {
+    const parts = token.split('.');
+    if (parts.length < 2) {
+        throw new Error('Invalid JWT: expected at least 2 segments');
+    }
+    // Add padding back if needed for base64 decoding
+    const base64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+    const decoded = Buffer.from(padded, 'base64').toString('utf-8');
+    const payload = JSON.parse(decoded);
+    if (typeof payload.exp !== 'number') {
+        throw new Error('JWT payload does not contain an exp claim');
+    }
+    return new Date(payload.exp * 1000).toISOString();
+}

package/dist/schema/registry.js

@@ -1,4 +1,43 @@
 const registry = [
+    {
+        name: 'login',
+        description: 'Authenticate via GitHub OAuth in the browser',
+        safety: 'write',
+        parameters: {
+            '--server': { type: 'string', required: false, description: 'Server URL', default: 'https://api.wafflebase.io' },
+        },
+        response: { user: 'string', workspace: 'string' },
+    },
+    {
+        name: 'logout',
+        description: 'Clear session and log out',
+        safety: 'write',
+        parameters: {},
+        response: {},
+    },
+    {
+        name: 'status',
+        description: 'Show current auth state',
+        safety: 'read-only',
+        parameters: {},
+        response: { user: 'string', server: 'string', workspace: 'string', session: 'string' },
+    },
+    {
+        name: 'ctx.list',
+        description: 'List workspaces',
+        safety: 'read-only',
+        parameters: {},
+        response: { type: 'array', items: { id: 'string', name: 'string', active: 'boolean' } },
+    },
+    {
+        name: 'ctx.switch',
+        description: 'Switch active workspace',
+        safety: 'write',
+        parameters: {
+            'name-or-id': { type: 'string', required: true, description: 'Workspace name or ID' },
+        },
+        response: { workspace: 'string' },
+    },
     {
         name: 'doc.list',
         description: 'List documents in workspace',
@@ -100,6 +139,32 @@ const registry = [
         },
         response: { ref: 'string', deleted: 'boolean' },
     },
+    {
+        name: 'import',
+        description: 'Import CSV/JSON into a tab',
+        safety: 'write',
+        parameters: {
+            'doc-id': { type: 'string', required: true, description: 'Document ID' },
+            file: { type: 'string', required: true, description: 'File path or - for stdin' },
+            '--tab': { type: 'string', required: false, description: 'Target tab', default: 'tab-1' },
+            '--file-format': { type: 'string', required: false, description: 'File format (csv, json)' },
+            '--start': { type: 'string', required: false, description: 'Top-left cell', default: 'A1' },
+        },
+        response: { imported: 'number' },
+    },
+    {
+        name: 'export',
+        description: 'Export tab data to CSV/JSON',
+        safety: 'read-only',
+        parameters: {
+            'doc-id': { type: 'string', required: true, description: 'Document ID' },
+            file: { type: 'string', required: true, description: 'File path or - for stdout' },
+            '--tab': { type: 'string', required: false, description: 'Source tab', default: 'tab-1' },
+            '--range': { type: 'string', required: false, description: 'Cell range (e.g. A1:D100)' },
+            '--file-format': { type: 'string', required: false, description: 'File format (csv, json)' },
+        },
+        response: { type: 'string', description: 'Formatted cell data' },
+    },
     {
         name: 'api-key.create',
         description: 'Create a new API key',

package/dist/util/csv-parse.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Parse CSV text into a 2D array of strings.
+ */
+export declare function parseCsv(text: string): string[][];
+/**
+ * Convert a 1-based column number to a column label (1→A, 2→B, 27→AA).
+ */
+export declare function toColumnLabel(col: number): string;
+/**
+ * Parse a cell reference like "A1" into 1-based row and column numbers.
+ */
+export declare function parseStartRef(ref: string): {
+    row: number;
+    col: number;
+};
+/**
+ * Build a cell map from a 2D array for batch API.
+ */
+export declare function buildCellMap(data: string[][], startRow: number, startCol: number): Record<string, {
+    value: string;
+}>;

package/dist/util/csv-parse.js

@@ -0,0 +1,99 @@
+/**
+ * Parse CSV text into a 2D array of strings.
+ */
+export function parseCsv(text) {
+    const rows = [];
+    let current = '';
+    let inQuotes = false;
+    let row = [];
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (i + 1 < text.length && text[i + 1] === '"') {
+                    current += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                current += ch;
+            }
+        }
+        else if (ch === '"') {
+            inQuotes = true;
+        }
+        else if (ch === ',') {
+            row.push(current);
+            current = '';
+        }
+        else if (ch === '\n' || ch === '\r') {
+            if (ch === '\r' && i + 1 < text.length && text[i + 1] === '\n') {
+                i++;
+            }
+            row.push(current);
+            current = '';
+            if (row.length > 0)
+                rows.push(row);
+            row = [];
+        }
+        else {
+            current += ch;
+        }
+    }
+    // last field/row
+    row.push(current);
+    if (row.some((cell) => cell !== ''))
+        rows.push(row);
+    return rows;
+}
+/**
+ * Convert a 1-based column number to a column label (1→A, 2→B, 27→AA).
+ */
+export function toColumnLabel(col) {
+    let label = '';
+    while (col > 0) {
+        const rem = col % 26;
+        if (rem === 0) {
+            label = 'Z' + label;
+            col = Math.floor(col / 26) - 1;
+        }
+        else {
+            label = String.fromCharCode(rem + 64) + label;
+            col = Math.floor(col / 26);
+        }
+    }
+    return label;
+}
+/**
+ * Parse a cell reference like "A1" into 1-based row and column numbers.
+ */
+export function parseStartRef(ref) {
+    const match = ref.match(/^([A-Z]+)(\d+)$/i);
+    if (!match)
+        return { row: 1, col: 1 };
+    const letters = match[1].toUpperCase();
+    let col = 0;
+    for (const ch of letters) {
+        col = col * 26 + (ch.charCodeAt(0) - 64);
+    }
+    return { row: parseInt(match[2], 10), col };
+}
+/**
+ * Build a cell map from a 2D array for batch API.
+ */
+export function buildCellMap(data, startRow, startCol) {
+    const cells = {};
+    for (let r = 0; r < data.length; r++) {
+        for (let c = 0; c < data[r].length; c++) {
+            const value = data[r][c];
+            if (value === '')
+                continue;
+            const ref = toColumnLabel(startCol + c) + (startRow + r);
+            cells[ref] = { value };
+        }
+    }
+    return cells;
+}

package/package.json

@@ -1,24 +1,28 @@
 {
   "name": "@wafflebase/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI for Wafflebase spreadsheet API",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
     "wafflebase": "./dist/bin.js"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "files": [
     "dist"
   ],
   "dependencies": {
     "commander": "^13.0.0",
+    "open": "^11.0.0",
     "yaml": "^2.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",
     "eslint": "^9.18.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.3",
+    "typescript": "^5.9.3",
     "vitest": "^3.1.0"
   },
   "scripts": {