sella-cli 0.5.0

package/dist/index.js

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+import * as readline from 'node:readline/promises';
+import * as path from 'node:path';
+import { detectClients, installSellaIntoClient, defaultEnv } from './clients.js';
+import { pair } from './pairing.js';
+import { runDoctor, runStatus, loadStoredKey } from './doctor.js';
+import { runMcpBridge } from './mcp-bridge.js';
+import { scaffoldCard, pushDataset, CARD_FILENAME } from './publish.js';
+import { sandboxSearch } from './api.js';
+import { getFundingInfo, annotateFunding } from './fund.js';
+import { capabilityLabel } from './chains.js';
+import { defaultIo, Printer } from './output.js';
+const DEFAULT_MCP_URL = 'https://sella.network/api/mcp';
+const VERSION = '0.5.0';
+function parseFlags(argv) {
+    const flags = {
+        json: false, yes: false, noColor: false, dryRun: false, noKeychain: false,
+        help: false, version: false, positional: [],
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--json')
+            flags.json = true;
+        else if (arg === '--yes' || arg === '-y')
+            flags.yes = true;
+        else if (arg === '--no-color')
+            flags.noColor = true;
+        else if (arg === '--dry-run')
+            flags.dryRun = true;
+        else if (arg === '--no-keychain')
+            flags.noKeychain = true;
+        else if (arg === '--client' || arg === '--clients')
+            flags.clients = argv[(i += 1)];
+        else if (arg === '--setup-code')
+            flags.setupCode = argv[(i += 1)];
+        else if (arg === '--email')
+            flags.email = argv[(i += 1)];
+        else if (arg === '--card')
+            flags.card = argv[(i += 1)];
+        else if (arg === '--install')
+            flags.positional.push('--install');
+        else if (arg === '--help' || arg === '-h')
+            flags.help = true;
+        else if (arg === '--version' || arg === '-v')
+            flags.version = true;
+        else
+            flags.positional.push(arg);
+    }
+    return flags;
+}
+const HELP = `sella — the Sella onboarding CLI
+
+Usage: sella <command> [options]
+
+Commands:
+  init       Install the Sella MCP server into your agent clients, pair, done
+  pair       Pair this machine only (setup code or email + OTP)
+  sandbox    Try Sella with no signup — search the live marketplace (rate-limited)
+  clients    List detected agent clients (--install to write configs)
+  doctor     Verify the install: endpoint, credentials, auth, wallets, pay-quote
+  status     Show your key + AgentWallet balances
+  fund       Show deposit addresses + funding links to add USDC to your agent wallet
+  mcp        Run as a local stdio MCP server that proxies Sella with your stored key
+  publish    Publish a dataset from a CSV: 'publish init <file.csv>' then 'publish push'
+
+Options:
+  --setup-code <code>   Pair with a dashboard setup code (also: SELLA_SETUP_CODE env)
+  --email <address>     Pair with email + OTP (interactive)
+  --card <path>         Dataset card for 'publish push' (default ./sella-dataset.json)
+  --client <ids>        Comma-separated subset (claude-code,claude-desktop,cursor,windsurf,vscode,cline)
+  --no-keychain         Skip the OS keychain; store the key in a 0600 file (also: SELLA_NO_KEYCHAIN)
+  --dry-run             Show what would change without writing
+  --json                Machine-readable output (one JSON document on stdout)
+  --yes, -y             Assume yes for prompts (non-interactive)
+  --no-color            Disable colors (NO_COLOR env honored too)
+  --help, -h            Show this help
+  --version, -v         Show version
+
+Environment:
+  SELLA_MCP_URL         Override the MCP endpoint (default ${DEFAULT_MCP_URL})
+  SELLA_SETUP_CODE      Setup code for headless/CI pairing
+  SELLA_NO_KEYCHAIN     Set to 1 to force file storage for the API key
+`;
+function selectClientIds(flags, detected) {
+    if (flags.clients) {
+        return flags.clients.split(',').map((s) => s.trim()).filter(Boolean);
+    }
+    return detected.filter((c) => c.installed).map((c) => c.id);
+}
+function installAll(ctx, flags, printer, apiKey) {
+    const detected = detectClients(ctx.env);
+    const targets = selectClientIds(flags, detected);
+    const results = [];
+    let failed = false;
+    for (const id of targets) {
+        try {
+            const result = installSellaIntoClient(id, { mcpUrl: ctx.mcpUrl, env: ctx.env, dryRun: flags.dryRun, apiKey });
+            results.push({ ...result });
+            printer.ok(`${id}: ${flags.dryRun ? `would be ${result.action}` : result.action} → ${result.configPath}`);
+        }
+        catch (err) {
+            failed = true;
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({ id, error: message });
+            printer.error(`${id}: ${message}`);
+        }
+    }
+    return { results, failed, targets };
+}
+function makeAsk(ctx) {
+    if (!ctx.io.isTTY)
+        return undefined;
+    return async (question) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        try {
+            return await rl.question(question);
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
+async function runPair(ctx, flags, printer) {
+    const outcome = await pair({
+        mcpUrl: ctx.mcpUrl,
+        env: ctx.env,
+        interactive: ctx.io.isTTY && !flags.yes && !flags.json,
+        setupCode: flags.setupCode || ctx.io.env.SELLA_SETUP_CODE,
+        email: flags.email,
+        allowKeychain: !flags.noKeychain && !ctx.io.env.SELLA_NO_KEYCHAIN,
+        ask: makeAsk(ctx),
+    });
+    if (!outcome.ok) {
+        printer.error(outcome.error);
+        return { code: outcome.exitCode, summary: { paired: false, error: outcome.error } };
+    }
+    printer.ok(`Paired via ${outcome.method} — status: ${outcome.payload.status || 'ok'}`);
+    for (const file of outcome.save.files)
+        printer.ok(`wrote ${file}`);
+    printer.info(outcome.save.custodyNote);
+    if (outcome.payload.agentWallet?.status === 'unavailable') {
+        printer.warn(`AgentWallet not provisioned (${outcome.payload.agentWallet.reason || 'backend unavailable'}) — MCP access still works; re-run \`sella pair\` later.`);
+    }
+    return {
+        code: 0,
+        apiKey: outcome.payload.apiKey,
+        summary: {
+            paired: true,
+            method: outcome.method,
+            status: outcome.payload.status,
+            keyStorage: outcome.save.keyStorage,
+            files: outcome.save.files,
+            agentWallet: outcome.payload.agentWallet?.status || 'none',
+        },
+    };
+}
+async function previewSandbox(ctx, flags, printer) {
+    if (flags.json)
+        return; // cosmetic; skip in machine mode
+    try {
+        const result = await sandboxSearch(ctx.mcpUrl, 'data');
+        const n = result.datasets.length + result.apis.length;
+        if (n === 0)
+            return;
+        printer.info('Here’s a taste of what your agent can buy on Sella (no signup needed):');
+        for (const d of result.datasets.slice(0, 2))
+            printer.info(`  dataset  ${d.title || d.id}`);
+        for (const a of result.apis.slice(0, 2))
+            printer.info(`  api      ${a.name || ''}`);
+        printer.info('');
+    }
+    catch {
+        /* best-effort — never blocks onboarding */
+    }
+}
+async function cmdInit(ctx, flags, printer) {
+    printer.info('Sella init — 1/3 install, 2/3 pair, 3/3 verify.\n');
+    await previewSandbox(ctx, flags, printer);
+    const install = installAll(ctx, flags, printer);
+    if (install.targets.length === 0) {
+        printer.error('No agent clients found (and none specified via --client). Nothing to install into.');
+        printer.jsonOut({ installed: [], paired: false, error: 'no_clients' });
+        return 2;
+    }
+    printer.info('\nPairing this machine…');
+    const paired = await runPair(ctx, flags, printer);
+    let reinstalled = [];
+    if (paired.code === 0 && paired.apiKey && !flags.dryRun) {
+        reinstalled = installAll(ctx, flags, printer, paired.apiKey).results;
+        printer.info('\nDone. Your agent clients are connected to Sella — fund your wallet to enable paid calls:');
+        printer.info('  https://sella.network/dashboard/funding');
+    }
+    printer.jsonOut({ installed: install.results, pairing: paired.summary, reinstalled });
+    return install.failed ? 1 : paired.code;
+}
+export async function runCli(argv, io = defaultIo(), env = defaultEnv()) {
+    const flags = parseFlags(argv);
+    const printer = new Printer(io, flags.json, flags.noColor);
+    const ctx = { io, env, mcpUrl: io.env.SELLA_MCP_URL || DEFAULT_MCP_URL };
+    const command = flags.positional[0];
+    if (flags.version) {
+        io.stdout(VERSION);
+        return 0;
+    }
+    if (flags.help || !command) {
+        io.stdout(HELP);
+        return 0;
+    }
+    try {
+        switch (command) {
+            case 'clients': {
+                const install = flags.positional.includes('--install');
+                if (!install) {
+                    const detected = detectClients(ctx.env);
+                    printer.jsonOut({ clients: detected });
+                    printer.info('Detected agent clients:');
+                    for (const c of detected) {
+                        printer.info(`  ${c.installed ? '[found]  ' : '[absent] '} ${c.name.padEnd(15)} ${c.configPath}`);
+                    }
+                    printer.info('\nRun `sella clients --install` to add the Sella MCP server to the found clients.');
+                    return 0;
+                }
+                const { results, failed, targets } = installAll(ctx, flags, printer);
+                if (targets.length === 0) {
+                    printer.error('No agent clients found (and none specified via --client). Nothing to install into.');
+                    printer.jsonOut({ installed: [], error: 'no_clients' });
+                    return 2;
+                }
+                printer.jsonOut({ dryRun: flags.dryRun, installed: results });
+                return failed ? 1 : 0;
+            }
+            case 'pair': {
+                const paired = await runPair(ctx, flags, printer);
+                printer.jsonOut(paired.summary || {});
+                return paired.code;
+            }
+            case 'init':
+                return await cmdInit(ctx, flags, printer);
+            case 'sandbox': {
+                const query = flags.positional.slice(1).filter((s) => s !== '--install').join(' ').trim();
+                if (!query) {
+                    printer.error('Usage: sella sandbox <query>  (e.g. `sella sandbox "web search"`)');
+                    return 2;
+                }
+                const result = await sandboxSearch(ctx.mcpUrl, query);
+                printer.jsonOut(result);
+                if (!flags.json) {
+                    const total = result.datasets.length + result.apis.length;
+                    printer.info(`Sandbox results for "${query}" (no account, rate-limited):`);
+                    for (const d of result.datasets) {
+                        printer.info(`  dataset  ${d.title || d.id}${d.priceUSDC ? ` — $${d.priceUSDC}/call` : ' — free'}`);
+                    }
+                    for (const a of result.apis) {
+                        printer.info(`  api      ${a.name || ''}${a.chains?.length ? ` [${a.chains.join('/')}]` : ''}`);
+                    }
+                    printer.info(total ? '\nPair to buy any of these: `sella init`.' : 'No matches — try a broader query.');
+                }
+                return 0;
+            }
+            case 'fund': {
+                const info = await annotateFunding(getFundingInfo(ctx.env, ctx.mcpUrl));
+                printer.jsonOut(info);
+                if (!flags.json) {
+                    if (!info.paired) {
+                        printer.error('Not paired yet — run `sella pair` first, then `sella fund`.');
+                        return 2;
+                    }
+                    printer.info('Fund your Sella agent wallet with USDC:\n');
+                    for (const w of info.wallets) {
+                        const label = w.capability ? capabilityLabel(w.capability) : '';
+                        printer.info(`  ${w.chain.padEnd(9)} ${w.address}${label ? `   (${label})` : ''}`);
+                    }
+                    printer.info(`\nFiat on-ramp (card / Apple Pay) + QR codes: ${info.fundingUrl}`);
+                    printer.info('Send only USDC on the matching chain. Balances appear after on-chain confirmation.');
+                    if (info.wallets.some((w) => w.capability === 'deposit-only')) {
+                        printer.info('Chains marked deposit-only accept funds now; spending from them turns on as Sella verifies settlement.');
+                    }
+                }
+                return info.paired ? 0 : 2;
+            }
+            case 'doctor': {
+                const result = await runDoctor({ mcpUrl: ctx.mcpUrl, env: ctx.env });
+                printer.jsonOut(result);
+                if (!flags.json) {
+                    printer.info('Sella doctor:');
+                    for (const check of result.checks) {
+                        if (check.ok)
+                            printer.ok(`${check.label} — ${check.detail}`);
+                        else {
+                            printer.error(`${check.label} — ${check.detail}`);
+                            if (check.fix)
+                                printer.info(`      ↳ ${check.fix}`);
+                        }
+                    }
+                    printer.info(result.ok ? '\nAll checks passed. Your agent is ready to buy.' : '\nSome checks failed — see the fixes above.');
+                }
+                return result.ok ? 0 : 1;
+            }
+            case 'status': {
+                const status = await runStatus({ mcpUrl: ctx.mcpUrl, env: ctx.env });
+                printer.jsonOut(status);
+                if (!flags.json) {
+                    const key = status.key;
+                    printer.info(key.present ? `API key: ${key.prefix}… (${key.source})` : 'API key: not paired — run `sella pair`');
+                    const aw = status.agentWallet;
+                    if (aw?.username) {
+                        printer.info(`AgentWallet: ${aw.username}${aw.fundingStatus ? ` · ${aw.fundingStatus}` : ''}`);
+                        for (const w of aw.wallets || []) {
+                            const cap = w.capability;
+                            const label = cap ? capabilityLabel(cap) : '';
+                            printer.info(`  ${String(w.chain).padEnd(9)} ${w.address}${label ? `   (${label})` : ''}`);
+                        }
+                    }
+                    else {
+                        printer.info('AgentWallet: not provisioned');
+                    }
+                }
+                return 0;
+            }
+            case 'publish': {
+                const sub = flags.positional[1];
+                const origin = ctx.mcpUrl.replace(/\/api\/mcp\/?$/, '') || 'https://sella.network';
+                if (sub === 'init') {
+                    const csv = flags.positional.slice(2).find((s) => !s.startsWith('--'));
+                    if (!csv) {
+                        printer.error('Usage: sella publish init <file.csv>');
+                        return 2;
+                    }
+                    let result;
+                    try {
+                        result = scaffoldCard(csv);
+                    }
+                    catch (err) {
+                        printer.error(`Could not read ${csv}: ${err instanceof Error ? err.message : String(err)}`);
+                        return 2;
+                    }
+                    printer.jsonOut({ cardPath: result.cardPath, wroteNew: result.wroteNew, card: result.card, precheck: result.precheck });
+                    if (!flags.json) {
+                        printer.ok(result.wroteNew ? `Scaffolded ${result.cardPath}` : `Card already exists (left unchanged): ${result.cardPath}`);
+                        printer.info(`Pre-check: ${result.precheck.columns.length} columns, ${result.precheck.rows} rows.`);
+                        for (const w of result.precheck.warnings)
+                            printer.warn(w);
+                        printer.info('\nNext: set title / description / price in the card, then run `sella publish push`.');
+                    }
+                    return 0;
+                }
+                if (sub === 'push') {
+                    const stored = loadStoredKey(ctx.env);
+                    if (!stored) {
+                        printer.error('Not paired — run `sella pair` first, then `sella publish push`.');
+                        printer.jsonOut({ ok: false, error: 'not_paired' });
+                        return 2;
+                    }
+                    const cardPath = flags.card || path.join(process.cwd(), CARD_FILENAME);
+                    const result = await pushDataset({ origin, apiKey: stored.apiKey, cardPath });
+                    printer.jsonOut(result);
+                    if (!flags.json) {
+                        if (!result.ok) {
+                            printer.error(result.error || 'Publish failed.');
+                            if (result.fieldErrors)
+                                for (const [k, v] of Object.entries(result.fieldErrors))
+                                    printer.error(`  ${k}: ${v}`);
+                        }
+                        else {
+                            printer.ok(`Published — status: ${result.status}`);
+                            printer.info(`  listing: ${result.listingUrl}`);
+                            if (result.status === 'manual_review')
+                                printer.info('  Sella is reviewing it; it goes live once approved.');
+                            else if (result.status === 'processing')
+                                printer.info('  Still scoring — re-check later with `sella status` or the dashboard.');
+                        }
+                    }
+                    return result.ok ? 0 : 1;
+                }
+                printer.error('Usage: sella publish <init|push>');
+                return 2;
+            }
+            case 'mcp': {
+                // Long-running stdio MCP server: stdout is the JSON-RPC channel — only the bridge writes
+                // there. Startup notes and the credential status go to stderr so they never corrupt it.
+                const stored = loadStoredKey(ctx.env);
+                if (stored) {
+                    ctx.io.stderr(`ok  Sella MCP bridge → ${ctx.mcpUrl} (key from ${stored.source})`);
+                }
+                else {
+                    ctx.io.stderr('warn  No stored key — bridging free/sandbox tools only; run `sella pair` to enable paid tools.');
+                }
+                return await runMcpBridge({ mcpUrl: ctx.mcpUrl, apiKey: stored?.apiKey });
+            }
+            default:
+                printer.error(`Unknown command: ${command}. Run \`sella --help\`.`);
+                return 2;
+        }
+    }
+    catch (err) {
+        printer.error(err instanceof Error ? err.message : String(err));
+        printer.jsonOut({ error: err instanceof Error ? err.message : String(err) });
+        return 1;
+    }
+}
+// Bin entry (skipped when imported by tests).
+const isMain = process.argv[1]?.endsWith('index.js') || process.argv[1]?.endsWith('sella');
+if (isMain) {
+    runCli(process.argv.slice(2))
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}

package/dist/mcp-bridge.js

@@ -0,0 +1,115 @@
+/**
+ * `sella mcp` (CLI sprint C6): the package doubles as a **stdio MCP server**.
+ *
+ * Many agent clients can only launch an MCP server as a local command over stdio — they don't
+ * support remote HTTP MCP endpoints. This bridge lets those clients use Sella anyway: it reads
+ * newline-delimited JSON-RPC from stdin, forwards each request to the remote `/api/mcp` with the
+ * machine's stored Bearer token injected, and writes the response back on stdout. One credential
+ * (paired once via `sella pair`) unlocks Sella in every stdio-only client, with no key ever pasted
+ * into a client config.
+ *
+ * Contract: stdout is the MCP channel — ONLY JSON-RPC lines go there. All human logging goes to
+ * stderr. Notifications (no `id`) get no reply and aren't forwarded (our stateless proxy has no
+ * lifecycle state). Network/HTTP failures become JSON-RPC errors so the client sees them instead
+ * of a dropped connection.
+ */
+import * as readline from 'node:readline';
+function isRequest(msg) {
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg))
+        return false;
+    const id = msg.id;
+    return id !== undefined && id !== null; // notifications omit id → no reply expected
+}
+/**
+ * Forward one JSON-RPC message to the remote endpoint. Returns the response object to write back,
+ * or `null` for notifications (nothing to reply). Never throws — failures become JSON-RPC errors.
+ */
+export async function forwardMessage(msg, opts) {
+    if (!isRequest(msg))
+        return null;
+    const id = msg.id;
+    const fetchImpl = opts.fetchImpl || fetch;
+    try {
+        const res = await fetchImpl(opts.mcpUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                ...(opts.apiKey ? { authorization: `Bearer ${opts.apiKey}` } : {}),
+            },
+            body: JSON.stringify(msg),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            const hint = res.status === 401 ? ' — run `sella pair` to (re)authenticate this machine' : '';
+            return { jsonrpc: '2.0', id, error: { code: -32000, message: `Sella endpoint responded ${res.status}${hint}` } };
+        }
+        if (!text)
+            return { jsonrpc: '2.0', id, result: null };
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { jsonrpc: '2.0', id, error: { code: -32603, message: 'Malformed response from the Sella MCP endpoint' } };
+        }
+    }
+    catch (err) {
+        return {
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32001, message: `Could not reach the Sella endpoint: ${err instanceof Error ? err.message : 'network error'}` },
+        };
+    }
+}
+/**
+ * Run the stdio bridge: pipe stdin (newline-delimited JSON-RPC) → remote → stdout, until stdin
+ * closes. Resolves 0 after all in-flight forwards settle. Requests are matched by `id`, so the
+ * concurrent forwarding here is safe even if responses complete out of order.
+ */
+export function runMcpBridge(opts) {
+    const input = opts.input || process.stdin;
+    const write = opts.output || ((line) => process.stdout.write(line + '\n'));
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input, crlfDelay: Infinity });
+        let pending = 0;
+        let closed = false;
+        const settle = () => {
+            if (closed && pending === 0)
+                resolve(0);
+        };
+        rl.on('line', (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(trimmed);
+            }
+            catch {
+                write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }));
+                return;
+            }
+            pending += 1;
+            const work = Array.isArray(msg)
+                ? Promise.all(msg.map((m) => forwardMessage(m, opts))).then((rs) => rs.filter((r) => r !== null))
+                : forwardMessage(msg, opts);
+            Promise.resolve(work)
+                .then((result) => {
+                if (Array.isArray(result)) {
+                    if (result.length)
+                        write(JSON.stringify(result));
+                }
+                else if (result !== null) {
+                    write(JSON.stringify(result));
+                }
+            })
+                .finally(() => {
+                pending -= 1;
+                settle();
+            });
+        });
+        rl.on('close', () => {
+            closed = true;
+            settle();
+        });
+    });
+}

package/dist/output.js

@@ -0,0 +1,48 @@
+/**
+ * Output contract (inclusiveness is a feature, not a vibe — CLI sprint §3):
+ * - `--json` mode prints exactly one JSON document to stdout and nothing else.
+ * - Colors honor NO_COLOR / --no-color / non-TTY. Never communicate through color alone.
+ * - No spinner-only feedback: every long step prints a plain line a screen reader can speak.
+ */
+export function defaultIo() {
+    return {
+        stdout: (line) => process.stdout.write(line + '\n'),
+        stderr: (line) => process.stderr.write(line + '\n'),
+        isTTY: Boolean(process.stdout.isTTY),
+        env: process.env,
+    };
+}
+export class Printer {
+    io;
+    json;
+    useColor;
+    constructor(io, json, noColorFlag) {
+        this.io = io;
+        this.json = json;
+        this.useColor = io.isTTY && !json && !noColorFlag && !io.env.NO_COLOR;
+    }
+    paint(code, text) {
+        return this.useColor ? `[${code}m${text}` : text;
+    }
+    info(text) {
+        if (!this.json)
+            this.io.stdout(text);
+    }
+    ok(text) {
+        if (!this.json)
+            this.io.stdout(`${this.paint('32', 'ok')} ${text}`);
+    }
+    warn(text) {
+        if (!this.json)
+            this.io.stderr(`${this.paint('33', 'warn')} ${text}`);
+    }
+    error(text) {
+        // Errors go to stderr even in --json mode so the JSON document on stdout stays parseable.
+        this.io.stderr(`${this.paint('31', 'error')} ${text}`);
+    }
+    /** The single stdout document in --json mode. */
+    jsonOut(payload) {
+        if (this.json)
+            this.io.stdout(JSON.stringify(payload, null, 2));
+    }
+}

package/dist/pairing.js

@@ -0,0 +1,37 @@
+import { claimSetupCode, completeEmailOtp, startEmailOtp } from './api.js';
+import { saveCredentials } from './credentials.js';
+const NO_TTY_HELP = 'Non-interactive run without credentials. Pass --setup-code <SELLA-…>, set SELLA_SETUP_CODE, ' +
+    'or run interactively. Mint a code at https://sella.network/onboarding (Connect your agent).';
+export async function pair(opts) {
+    const finish = (payload, method) => {
+        if (!payload.ok || !payload.apiKey) {
+            return { ok: false, error: payload.error || 'Pairing failed.', exitCode: 1 };
+        }
+        const save = saveCredentials(payload, { env: opts.env, allowKeychain: opts.allowKeychain, execFile: opts.execFile });
+        return { ok: true, payload, save, method };
+    };
+    // Path 1: setup code (explicit, env, or prompted).
+    let code = opts.setupCode?.trim();
+    if (!code && opts.interactive && !opts.email && opts.ask) {
+        const answer = (await opts.ask('Paste a Sella setup code (SELLA-…), or press Enter to pair with email + OTP: ')).trim();
+        if (answer)
+            code = answer;
+    }
+    if (code) {
+        return finish(await claimSetupCode(opts.mcpUrl, code, opts.fetchImpl), 'setup-code');
+    }
+    // Path 2: email + OTP — interactive only.
+    if (!opts.interactive || !opts.ask) {
+        return { ok: false, error: NO_TTY_HELP, exitCode: 2 };
+    }
+    const email = (opts.email || (await opts.ask('Email address for your Sella account: '))).trim();
+    if (!email)
+        return { ok: false, error: 'An email address is required to pair.', exitCode: 2 };
+    const started = await startEmailOtp(opts.mcpUrl, email, opts.fetchImpl);
+    if (started.ok === false) {
+        const wait = started.retryAfterMs ? ` Try again in ${Math.ceil(started.retryAfterMs / 1000)}s.` : '';
+        return { ok: false, error: (started.error || 'Could not send the verification code.') + wait, exitCode: 1 };
+    }
+    const otp = (await opts.ask('6-digit code from your inbox: ')).trim();
+    return finish(await completeEmailOtp(opts.mcpUrl, email, otp, opts.fetchImpl), 'email-otp');
+}