@tiny-fish/cli 0.48.3-next.389 → 0.48.3-next.392

package/README.md

@@ -331,6 +331,47 @@ TINYFISH_PROXY_PASSWORD=<password> \
 tinyfish browser session create --no-proxy
 ```
 
+A session bills until it closes or times out, so close it when you are done:
+
+```bash
+tinyfish browser session list --status running
+tinyfish browser session close <session_id>
+```
+
+### Monitors
+
+```bash
+# Watch search results for a topic, every 6 hours (runs a billed baseline now)
+tinyfish monitor create --query "tinyfish funding news" --schedule "0 */6 * * *"
+
+# Watch a page for changes, daily at 09:00 UTC
+tinyfish monitor create --url https://example.com/pricing --schedule "0 9 * * *"
+
+tinyfish monitor list --pretty
+tinyfish monitor pause <monitor_id>
+tinyfish monitor resume <monitor_id>
+tinyfish monitor run <monitor_id>     # billed
+tinyfish monitor cancel <monitor_id>  # deletes it
+```
+
+### Profiles
+
+```bash
+tinyfish profile list --pretty
+
+# Create a profile and get a link to sign in and save it (opens at a terminal)
+tinyfish profile create --name work --site github.com --proxy-country GB
+
+# Change the proxy later; every run on the profile uses it
+tinyfish profile update <profile_id> --proxy-country DE
+
+# Or import cookies from your local Chrome instead
+tinyfish profile create --name work --import-cookies --domain github.com
+
+# Sign in to another site on an existing profile
+tinyfish profile sign-in <profile_id> --site accounts.google.com
+```
+
 ### Vault
 
 Connect a credential provider (1Password / Bitwarden), then have runs consume those credentials.

package/dist/commands/browser.js

@@ -1,5 +1,6 @@
-import { getApiKey } from '../lib/auth.js';
-import { browserSessionCreate } from '../lib/client.js';
+import { getApiKey, withResolvedKey } from '../lib/auth.js';
+import { browserSessionClose, browserSessionCreate, browserSessionList } from '../lib/client.js';
+import { addPageOptions, pageParams, printPage } from '../lib/list-options.js';
 import { err, handleApiError, out, outLine } from '../lib/output.js';
 const VALID_BROWSER_PROFILES = ['lite', 'stealth'];
 function parseBrowserProfile(value) {
@@ -48,6 +49,26 @@ function printPrettyBrowserSession(session) {
     outLine(`CDP URL: ${session.cdp_url}`);
     outLine(`Base URL: ${session.base_url}`);
 }
+function browserSessionListAction(opts) {
+    const params = {
+        ...pageParams(opts),
+        ...(opts.sessionId !== undefined ? { session_id: opts.sessionId } : {}),
+    };
+    return withResolvedKey(async (apiKey) => {
+        const result = await browserSessionList(params, apiKey);
+        printPage(result, opts.pretty, (s) => `${s.session_id}  ${s.status ?? '-'}  ${s.start_time ?? '-'}`);
+    });
+}
+// REST answers 204; echo the MCP close_browser_session shape instead.
+function browserSessionCloseAction(sessionId, opts) {
+    return withResolvedKey(async (apiKey) => {
+        await browserSessionClose(sessionId, apiKey);
+        if (opts.pretty)
+            outLine(`Browser session ${sessionId} closed`);
+        else
+            out({ session_id: sessionId, status: 'closed' });
+    });
+}
 export function registerBrowser(program) {
     const browserCmd = program
         .command('browser')
@@ -88,4 +109,12 @@ export function registerBrowser(program) {
             handleApiError(error);
         }
     });
+    addPageOptions(sessionCmd.command('list').description('List browser sessions'), 'running|ended')
+        .option('--session-id <id>', 'Only this session')
+        .action(browserSessionListAction);
+    sessionCmd
+        .command('close <session_id>')
+        .description('Close a browser session and stop its billing (idempotent)')
+        .option('--pretty', 'Human-readable output')
+        .action(browserSessionCloseAction);
 }

package/dist/commands/fetch.js

@@ -1,23 +1,12 @@
-import { InvalidArgumentError } from 'commander';
-import { getApiKey } from '../lib/auth.js';
-import { fetchContentGet } from '../lib/client.js';
+import { getApiKey, withResolvedKey } from '../lib/auth.js';
+import { fetchContentGet, fetchUsage } from '../lib/client.js';
+import { addPageOptions, integerInRange, pageParams, printPage, } from '../lib/list-options.js';
 import { err, handleApiError, out, outLine } from '../lib/output.js';
 const MIN_PER_URL_TIMEOUT_MS = 1;
 const MAX_PER_URL_TIMEOUT_MS = 110000;
 const MIN_HIGHLIGHT_SNIPPETS = 1;
 const MAX_HIGHLIGHT_SNIPPETS = 20;
 const MAX_URLS = 10;
-function integerInRange(min, max) {
-    return (value) => {
-        const parsed = Number(value);
-        if (!Number.isSafeInteger(parsed) || parsed < min || (max !== undefined && parsed > max)) {
-            throw new InvalidArgumentError(max === undefined
-                ? 'must be a positive integer'
-                : `must be an integer between ${min} and ${max}`);
-        }
-        return parsed;
-    };
-}
 function validateHighlightsOptions(opts) {
     const hasSubFlag = opts.maxSnippets !== undefined ||
         opts.maxCharacters !== undefined ||
@@ -102,6 +91,11 @@ function printPrettyFetch(response) {
         }
     }
 }
+function fetchUsageAction(opts) {
+    return withResolvedKey(async (apiKey) => {
+        printPage(await fetchUsage(pageParams(opts), apiKey), opts.pretty, (item) => `${item.created_at}  ${item.status}  ${item.url}`);
+    });
+}
 export function registerFetch(program) {
     const fetchCmd = program.command('fetch').description('Fetch commands').enablePositionalOptions();
     const contentCmd = fetchCmd
@@ -156,4 +150,5 @@ export function registerFetch(program) {
             handleApiError(error);
         }
     });
+    addPageOptions(fetchCmd.command('usage').description('List your past fetch requests'), 'completed|failed').action(fetchUsageAction);
 }

package/dist/commands/monitor.d.ts

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

package/dist/commands/monitor.js

@@ -0,0 +1,150 @@
+import { withResolvedKey } from '../lib/auth.js';
+import { monitorCreate, monitorDelete, monitorGet, monitorList, monitorRun, monitorSetStatus, } from '../lib/client.js';
+import { integerInRange } from '../lib/list-options.js';
+import { err, out, outLine } from '../lib/output.js';
+const MAX_RESULT_LIMIT = 10;
+function searchConfig(query, opts) {
+    return {
+        query,
+        ...(opts.recencyMinutes !== undefined ? { recency_minutes: opts.recencyMinutes } : {}),
+        ...(opts.resultLimit !== undefined ? { result_limit: opts.resultLimit } : {}),
+    };
+}
+function fetchConfig(url, opts) {
+    return {
+        url,
+        ...(opts.format !== undefined ? { format: opts.format } : {}),
+        ...(opts.links ? { links: true } : {}),
+        ...(opts.imageLinks ? { image_links: true } : {}),
+    };
+}
+const SEARCH_ONLY_FLAGS = { recencyMinutes: '--recency-minutes', resultLimit: '--result-limit' };
+const FETCH_ONLY_FLAGS = { format: '--format', links: '--links', imageLinks: '--image-links' };
+function exitWithError(message) {
+    err({ error: message });
+    process.exit(1);
+}
+// Unsent flags would otherwise vanish silently on a billed create.
+function rejectFlags(opts, flags, type) {
+    const used = Object.entries(flags).filter(([key]) => opts[key] !== undefined);
+    if (used.length > 0) {
+        exitWithError(`${used.map(([, flag]) => flag).join(', ')} cannot be used with a ${type} monitor`);
+    }
+}
+function buildCreateBody(opts) {
+    if ((opts.query === undefined) === (opts.url === undefined)) {
+        exitWithError('Provide exactly one of --query (search monitor) or --url (fetch monitor)');
+    }
+    if (opts.query !== undefined)
+        rejectFlags(opts, FETCH_ONLY_FLAGS, 'search');
+    else
+        rejectFlags(opts, SEARCH_ONLY_FLAGS, 'fetch');
+    const target = opts.query !== undefined
+        ? { type: 'search', config: searchConfig(opts.query, opts) }
+        : { type: 'fetch', config: fetchConfig(opts.url, opts) };
+    return {
+        ...target,
+        schedule_cron: opts.schedule,
+        ...(opts.name !== undefined ? { name: opts.name } : {}),
+        ...(opts.webhookUrl !== undefined ? { webhook_url: opts.webhookUrl } : {}),
+        ...(opts.purpose !== undefined ? { purpose: opts.purpose } : {}),
+    };
+}
+function monitorLine(monitor) {
+    const target = monitor.config.query ?? monitor.config.url ?? '';
+    return `${monitor.id}  ${monitor.type}  ${monitor.status}  ${monitor.schedule_cron}  ${target}`;
+}
+function printPrettyRun(run) {
+    outLine(`Run: ${run.id}`);
+    if (run.result_count !== undefined)
+        outLine(`Results: ${run.result_count}`);
+    else
+        outLine(`Fetched: ${run.results?.length ?? 0}, errors: ${run.errors?.length ?? 0}`);
+}
+function monitorCreateAction(opts) {
+    const body = buildCreateBody(opts);
+    return withResolvedKey(async (apiKey) => {
+        const result = await monitorCreate(body, apiKey);
+        if (!opts.pretty)
+            return out(result);
+        outLine(monitorLine(result.monitor));
+        printPrettyRun(result.run);
+    });
+}
+function monitorListAction(opts) {
+    return withResolvedKey(async (apiKey) => {
+        const result = await monitorList(apiKey);
+        if (!opts.pretty)
+            return out(result);
+        if (result.monitors.length === 0)
+            outLine('No monitors.');
+        for (const monitor of result.monitors)
+            outLine(monitorLine(monitor));
+    });
+}
+function monitorShow(fetchMonitor) {
+    return (id, opts) => withResolvedKey(async (apiKey) => {
+        const monitor = await fetchMonitor(id, apiKey);
+        if (opts.pretty)
+            outLine(monitorLine(monitor));
+        else
+            out(monitor);
+    });
+}
+function monitorRunAction(id, opts) {
+    return withResolvedKey(async (apiKey) => {
+        const result = await monitorRun(id, apiKey);
+        if (opts.pretty)
+            printPrettyRun(result.run);
+        else
+            out(result);
+    });
+}
+function monitorCancelAction(id, opts) {
+    return withResolvedKey(async (apiKey) => {
+        const result = await monitorDelete(id, apiKey);
+        if (opts.pretty)
+            outLine(`Monitor ${result.id} deleted`);
+        else
+            out(result);
+    });
+}
+function addIdCommand(parent, name, description, action) {
+    parent
+        .command(`${name} <monitor_id>`)
+        .description(description)
+        .option('--pretty', 'Human-readable output')
+        .action(action);
+}
+export function registerMonitor(program) {
+    const monitorCmd = program
+        .command('monitor')
+        .description('Recurring search and fetch monitors')
+        .enablePositionalOptions();
+    monitorCmd
+        .command('create')
+        .description('Create a monitor and run its baseline now. Each completed run is billed to your wallet.')
+        .option('--query <query>', 'Search monitor: query to watch')
+        .option('--url <url>', 'Fetch monitor: page to watch')
+        .requiredOption('--schedule <cron>', '5-field cron, UTC unless prefixed "CRON_TZ=<zone> " (search: every 30 min at most)')
+        .option('--name <name>', 'Monitor name')
+        .option('--webhook-url <url>', 'POST each run result to this URL')
+        .option('--purpose <text>', 'Why you are monitoring this')
+        .option('--recency-minutes <n>', 'Search: only results this recent', integerInRange(1))
+        .option('--result-limit <n>', `Search: results per run, 1-${MAX_RESULT_LIMIT} (default ${MAX_RESULT_LIMIT})`, integerInRange(1, MAX_RESULT_LIMIT))
+        .option('--format <format>', 'Fetch: markdown, html, or json (default json)')
+        .option('--links', 'Fetch: include extracted links')
+        .option('--image-links', 'Fetch: include extracted image links')
+        .option('--pretty', 'Human-readable output')
+        .action(monitorCreateAction);
+    monitorCmd
+        .command('list')
+        .description('List your monitors')
+        .option('--pretty', 'Human-readable output')
+        .action(monitorListAction);
+    addIdCommand(monitorCmd, 'get', 'Get a monitor by ID', monitorShow(monitorGet));
+    addIdCommand(monitorCmd, 'pause', 'Pause a monitor', monitorShow((id, apiKey) => monitorSetStatus(id, 'paused', apiKey)));
+    addIdCommand(monitorCmd, 'resume', 'Resume a paused monitor', monitorShow((id, apiKey) => monitorSetStatus(id, 'active', apiKey)));
+    addIdCommand(monitorCmd, 'run', 'Run a monitor now (billed)', monitorRunAction);
+    addIdCommand(monitorCmd, 'cancel', 'Delete a monitor and its schedule', monitorCancelAction);
+}

package/dist/commands/profile.js

@@ -2,10 +2,13 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { createRequire } from 'module';
+import { InvalidArgumentError } from 'commander';
 import { z } from 'zod';
-import { getResolvedApiKey, rejectedKeyHint } from '../lib/auth.js';
+import { getResolvedApiKey, rejectedKeyHint, withResolvedKey } from '../lib/auth.js';
 import { deriveChromeKey, listAuthRelevantHostKeys, openCookiesDb, readCookiesForHost, } from '../lib/chrome-cookies.js';
-import { profileCreate, profileGet, profileList, profileUpload } from '../lib/client.js';
+import { profileCreate, profileGet, profileList, profileUpdate, profileUpload, } from '../lib/client.js';
+import { BASE_URL } from '../lib/constants.js';
+import { detectHumanInitiated } from '../lib/harness.js';
 import { err, errLine, handleApiError, out, outLine } from '../lib/output.js';
 // ── Helpers ───────────────────────────────────────────────────────────────────
 const chromeLocalStateSchema = z.object({
@@ -249,12 +252,6 @@ export function buildChunks(groups) {
     return chunks;
 }
 // ── Pretty printers ───────────────────────────────────────────────────────────
-function printPrettyProfileCreate(profile) {
-    outLine('Profile created');
-    outLine(`ID:         ${profile.id}`);
-    outLine(`Name:       ${profile.name}`);
-    outLine(`Created at: ${profile.created_at}`);
-}
 function printPrettyProfileUpload(result) {
     if (result.profile_id)
         outLine(`Profile ID:       ${result.profile_id}`);
@@ -313,79 +310,178 @@ export async function uploadAllDomains(profileId, cookies, apiKey) {
         ...(domainsFailed.length > 0 ? { domains_failed: domainsFailed } : {}),
     };
 }
+// Commander defaults `proxy` to true once --no-proxy is declared.
+function proxyParams(opts) {
+    if (opts.proxy === false) {
+        if (opts.proxyCountry) {
+            err({ error: '--proxy-country cannot be combined with --no-proxy' });
+            process.exit(1);
+        }
+        return { proxy_country_code: null };
+    }
+    return opts.proxyCountry ? { proxy_country_code: opts.proxyCountry.toUpperCase() } : {};
+}
+function printPrettyProfileList({ profiles }) {
+    if (profiles.length === 0)
+        outLine('No profiles.');
+    for (const profile of profiles) {
+        const sites = profile.signed_in_sites?.map((entry) => entry.site).join(', ');
+        const proxy = profile.proxy_country_code ? `  proxy: ${profile.proxy_country_code}` : '';
+        outLine(`${profile.id}  ${profile.name}${proxy}${sites ? `  signed in: ${sites}` : ''}`);
+    }
+}
+// The setup page ignores anything but a bare hostname.
+function parseSite(value) {
+    try {
+        return new URL(value.includes('://') ? value : `https://${value}`).hostname;
+    }
+    catch {
+        throw new InvalidArgumentError('must be a site such as github.com or a URL');
+    }
+}
+// Dashboard page with its own browser and Save button; nothing bills until opened.
+function profileSetupUrl(profileId, site) {
+    const url = new URL(`/profiles/${encodeURIComponent(profileId)}/setup`, BASE_URL);
+    if (site)
+        url.searchParams.set('domain', site);
+    // The page opens domain= only for agent sources (mcp, cli).
+    url.searchParams.set('source', 'cli');
+    return url.toString();
+}
+function signInNextStep(profileId) {
+    return `Give the user setup_url. They sign in there and click Save profile; never ask for their password. Confirm with \`tinyfish profile list\`. Runs use \`tinyfish agent run --use-profile --profile-id ${profileId}\`.`;
+}
+async function handOffSignIn(profile, opts, created) {
+    const setupUrl = profileSetupUrl(profile.id, opts.site);
+    if (detectHumanInitiated()) {
+        const { openExternalUrl } = await import('../lib/connect-clients.js');
+        openExternalUrl(setupUrl);
+    }
+    if (!opts.pretty) {
+        return out({ ...profile, setup_url: setupUrl, next_step: signInNextStep(profile.id) });
+    }
+    if (created)
+        outLine(`Profile ${profile.id} created`);
+    outLine(`Sign in at: ${setupUrl}`);
+    outLine('Click Save profile there when you are done.');
+}
+function profileListAction(opts) {
+    return withResolvedKey(async (apiKey) => {
+        const result = await profileList(apiKey);
+        if (opts.pretty)
+            printPrettyProfileList(result);
+        else
+            out(result);
+    });
+}
+function profileCreateAction(opts) {
+    const newProfile = { name: opts.name, ...proxyParams(opts) };
+    if (opts.importCookies)
+        return profileImportCookiesAction({ ...opts, newProfile });
+    return withResolvedKey(async (apiKey) => {
+        await handOffSignIn(await profileCreate(newProfile, apiKey), opts, true);
+    });
+}
+function profileUpdateAction(profileId, opts) {
+    const params = { ...(opts.name !== undefined ? { name: opts.name } : {}), ...proxyParams(opts) };
+    if (Object.keys(params).length === 0) {
+        err({ error: 'Provide --name, --proxy-country, or --no-proxy' });
+        process.exit(1);
+    }
+    return withResolvedKey(async (apiKey) => {
+        const profile = await profileUpdate(profileId, params, apiKey);
+        if (opts.pretty)
+            outLine(`Profile ${profile.id} updated`);
+        else
+            out(profile);
+    });
+}
+function profileSignInAction(profileId, opts) {
+    return withResolvedKey(async (apiKey) => {
+        await handOffSignIn(await profileGet(profileId, apiKey), opts, false);
+    });
+}
+async function profileImportCookiesAction(opts) {
+    if (Boolean(opts.domain) === Boolean(opts.allDomains)) {
+        err({ error: 'Provide exactly one of --domain or --all-domains' });
+        process.exit(1);
+    }
+    const { key: apiKey, source } = getResolvedApiKey();
+    if (opts.domain) {
+        validateDomain(opts.domain);
+    }
+    let profileId = opts.profileId;
+    try {
+        const cookiesPath = resolveCookiesPath(opts.chromeProfile);
+        await verifyImportTarget(profileId, apiKey);
+        const cookies = extractCookiesOrThrow(opts, cookiesPath);
+        if (profileId === undefined) {
+            const fallbackName = opts.allDomains ? 'chrome-import' : opts.domain;
+            const created = await profileCreate(opts.newProfile ?? { name: fallbackName }, apiKey);
+            profileId = created.id;
+        }
+        const uploadResult = opts.allDomains
+            ? await uploadAllDomains(profileId, cookies, apiKey)
+            : await profileUpload(profileId, cookies, apiKey);
+        const result = { ...uploadResult, profile_id: profileId };
+        if (result.domains_failed && result.domains_failed.length > 0) {
+            errLine(`Warning: failed to update cookies for domains: ${result.domains_failed.join(', ')}`);
+        }
+        if (opts.pretty) {
+            printPrettyProfileUpload(result);
+        }
+        else {
+            out(result);
+        }
+    }
+    catch (error) {
+        handleApiError(error, rejectedKeyHint(source));
+    }
+}
+const SITE_OPTION_HELP = 'Site to sign in to, e.g. github.com (a URL works too)';
+const PROXY_COUNTRY_HELP = 'Exit country for sign-in and every run on this profile (ISO 3166-1 alpha-2, e.g. GB)';
+function addImportOptions(cmd) {
+    return cmd
+        .option('--domain <domain>', 'Domain to import cookies for (e.g. github.com)')
+        .option('--all-domains', 'Import cookies for all registrable domains (e.g. github.com) found in your Chrome profile. IPs and non-resolvable hostnames (e.g. localhost) are skipped.')
+        .option('--chrome-profile <name>', 'Chrome profile directory, e.g. "Profile 1" (default: last-used profile, else Default)');
+}
 export function registerProfile(program) {
     const profileCmd = program
         .command('profile')
         .description('Profile commands')
         .enablePositionalOptions();
     profileCmd
+        .command('list')
+        .description('List your browser profiles and the sites each is signed in to')
+        .option('--pretty', 'Human-readable output')
+        .action(profileListAction);
+    addImportOptions(profileCmd
         .command('create')
-        .description('Create a browser profile')
+        .description('Create a browser profile and get a link where the user signs in and saves it. Opens the link at a terminal.')
         .requiredOption('--name <name>', 'Profile name')
+        .option('--site <site>', SITE_OPTION_HELP, parseSite)
+        .option('--import-cookies', 'Import Chrome cookies instead of signing in through a link')
+        .option('--proxy-country <code>', PROXY_COUNTRY_HELP)
+        .option('--pretty', 'Human-readable output')).action(profileCreateAction);
+    profileCmd
+        .command('update <profile_id>')
+        .description('Rename a profile or change its proxy')
+        .option('--name <name>', 'New profile name')
+        .option('--proxy-country <code>', PROXY_COUNTRY_HELP)
+        .option('--no-proxy', 'Connect directly, without a proxy')
         .option('--pretty', 'Human-readable output')
-        .action(async (opts) => {
-        const { key: apiKey, source } = getResolvedApiKey();
-        try {
-            const response = await profileCreate(opts.name, apiKey);
-            if (opts.pretty) {
-                printPrettyProfileCreate(response);
-            }
-            else {
-                out(response);
-            }
-        }
-        catch (error) {
-            handleApiError(error, rejectedKeyHint(source));
-        }
-    });
+        .action(profileUpdateAction);
     profileCmd
+        .command('sign-in <profile_id>')
+        .description('Get a sign-in link for an existing profile, to add or refresh a site')
+        .option('--site <site>', SITE_OPTION_HELP, parseSite)
+        .option('--pretty', 'Human-readable output')
+        .action(profileSignInAction);
+    addImportOptions(profileCmd
         .command('import-cookies')
-        .description('Import Chrome cookies into a profile. Use --domain for a single domain or --all-domains for every domain in your Chrome profile. Exactly one must be provided.')
-        .option('--domain <domain>', 'Domain to import cookies for (e.g. github.com)')
-        .option('--all-domains', 'Import cookies for all registrable domains (e.g. github.com) found in your Chrome profile. IPs and non-resolvable hostnames (e.g. localhost) are skipped.')
-        .option('--chrome-profile <name>', 'Chrome profile directory, e.g. "Profile 1" (default: last-used profile, else Default)')
+        .description('Import Chrome cookies into a profile. Use --domain for a single domain or --all-domains for every domain in your Chrome profile. Exactly one must be provided.'))
         .option('--profile-id <id>', 'Profile ID to import cookies into (creates new profile if omitted)')
         .option('--pretty', 'Human-readable output')
-        .action(async (opts) => {
-        // Mutual-exclusivity guard — must provide exactly one of --domain / --all-domains
-        if (!opts.domain && !opts.allDomains) {
-            err({ error: 'Provide exactly one of --domain or --all-domains' });
-            process.exit(1);
-        }
-        if (opts.domain && opts.allDomains) {
-            err({ error: 'Provide exactly one of --domain or --all-domains' });
-            process.exit(1);
-        }
-        const { key: apiKey, source } = getResolvedApiKey();
-        if (opts.domain) {
-            validateDomain(opts.domain);
-        }
-        let profileId = opts.profileId;
-        try {
-            const cookiesPath = resolveCookiesPath(opts.chromeProfile);
-            await verifyImportTarget(profileId, apiKey);
-            const cookies = extractCookiesOrThrow(opts, cookiesPath);
-            if (profileId === undefined) {
-                const name = opts.allDomains ? 'chrome-import' : opts.domain;
-                const created = await profileCreate(name, apiKey);
-                profileId = created.id;
-            }
-            const uploadResult = opts.allDomains
-                ? await uploadAllDomains(profileId, cookies, apiKey)
-                : await profileUpload(profileId, cookies, apiKey);
-            const result = { ...uploadResult, profile_id: profileId };
-            if (result.domains_failed && result.domains_failed.length > 0) {
-                errLine(`Warning: failed to update cookies for domains: ${result.domains_failed.join(', ')}`);
-            }
-            if (opts.pretty) {
-                printPrettyProfileUpload(result);
-            }
-            else {
-                out(result);
-            }
-        }
-        catch (error) {
-            handleApiError(error, rejectedKeyHint(source));
-        }
-    });
+        .action(profileImportCookiesAction);
 }

package/dist/commands/search.js

@@ -1,5 +1,6 @@
-import { getApiKey } from '../lib/auth.js';
-import { searchQuery } from '../lib/client.js';
+import { getApiKey, withResolvedKey } from '../lib/auth.js';
+import { searchQuery, searchUsage } from '../lib/client.js';
+import { addPageOptions, pageParams, printPage } from '../lib/list-options.js';
 import { err, handleApiError, out, outLine } from '../lib/output.js';
 function printPrettySearch(response) {
     outLine(`Query: ${response.query}`);
@@ -27,6 +28,11 @@ function parsePageOption(value) {
     }
     return Number(value);
 }
+function searchUsageAction(opts) {
+    return withResolvedKey(async (apiKey) => {
+        printPage(await searchUsage(pageParams(opts), apiKey), opts.pretty, (item) => `${item.created_at}  ${item.status_code}  ${item.query} (${item.result_count ?? 0} results)`);
+    });
+}
 export function registerSearch(program) {
     const searchCmd = program
         .command('search')
@@ -65,4 +71,5 @@ export function registerSearch(program) {
             handleApiError(error);
         }
     });
+    addPageOptions(searchCmd.command('usage').description('List your past search requests, newest first'), 'completed|failed').action(searchUsageAction);
 }

package/dist/lib/auth.d.ts

@@ -72,5 +72,6 @@ export declare function validatedApiKey(explicitApiKey?: string): string | undef
 export declare function apiKeyStatus(explicitApiKey?: string): ResolvedKey | UnresolvedKey;
 export declare function getResolvedApiKey(): ResolvedKey;
 export declare function getApiKey(): string;
+export declare function withResolvedKey(call: (apiKey: string) => Promise<void>): Promise<void>;
 /** 401 repair hint that names where the rejected key came from. */
 export declare function rejectedKeyHint(source: ResolvedKey['source']): string | undefined;

package/dist/lib/auth.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import spawn from 'cross-spawn';
-import { err, errLine } from './output.js';
+import { err, errLine, handleApiError } from './output.js';
 import { TINYFISH_API_KEY_VAR } from './constants.js';
 const KEY_PREFIXES = ['sk-tinyfish-', 'sk-mino-'];
 const MIN_KEY_LENGTH = 20;
@@ -329,6 +329,15 @@ export function getResolvedApiKey() {
 export function getApiKey() {
     return getResolvedApiKey().key;
 }
+export async function withResolvedKey(call) {
+    const { key, source } = getResolvedApiKey();
+    try {
+        await call(key);
+    }
+    catch (error) {
+        handleApiError(error, rejectedKeyHint(source));
+    }
+}
 /** 401 repair hint that names where the rejected key came from. */
 export function rejectedKeyHint(source) {
     if (source === 'env') {

package/dist/lib/client.d.ts

@@ -1,5 +1,7 @@
 import { type AgentRunAsyncResponse, type AgentRunResponse, type AgentRunWithStreamingResponse, type BrowserSession, type FetchGetContentsParams, type FetchResponse, type Run, type RunListParams, type RunListResponse, type SearchQueryParams, type SearchQueryResponse, type WalletResponse } from '@tiny-fish/sdk';
+import type { PageParams } from './list-options.js';
 import type { BatchCancelResponse, BatchGetResponse, BatchRunRequest, BatchRunResponse, CancelRunResponse, CliAgentRunParams, CliBrowserSessionCreateParams, CookieRecord, ProfileCreateResponse, ProfileSummary, ProfileUploadResponse, RunStepsResponse, VaultConnectRequest, VaultConnectResponse, VaultConnectionsListResponse, VaultDisconnectResponse, VaultItemsListResponse, VaultItemsSyncResponse } from './types.js';
+import { z } from 'zod';
 type ConnectMap = Record<string, {
     attempt_id: string;
 }> | undefined;
@@ -15,14 +17,120 @@ export declare function getRunSteps(runId: string, apiKey: string): Promise<RunS
 export declare function searchQuery(params: SearchQueryParams, apiKey: string): Promise<SearchQueryResponse>;
 export declare function fetchContentGet(params: FetchGetContentsParams, apiKey: string): Promise<FetchResponse>;
 export declare function browserSessionCreate(params: CliBrowserSessionCreateParams, apiKey: string): Promise<BrowserSession>;
+declare const browserSessionPageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        session_id: z.ZodString;
+        status: z.ZodNullable<z.ZodString>;
+        start_time: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>>;
+    total: z.ZodNumber;
+    page: z.ZodNumber;
+    total_pages: z.ZodNumber;
+}, z.core.$loose>;
+declare const searchUsagePageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        query: z.ZodString;
+        status_code: z.ZodNumber;
+        result_count: z.ZodNullable<z.ZodNumber>;
+        created_at: z.ZodString;
+    }, z.core.$loose>>;
+    total: z.ZodNumber;
+    page: z.ZodNumber;
+    total_pages: z.ZodNumber;
+}, z.core.$loose>;
+declare const fetchUsagePageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        status: z.ZodString;
+        created_at: z.ZodString;
+    }, z.core.$loose>>;
+    total: z.ZodNumber;
+    page: z.ZodNumber;
+    total_pages: z.ZodNumber;
+}, z.core.$loose>;
+export type BrowserSessionPage = z.infer<typeof browserSessionPageSchema>;
+export type SearchUsagePage = z.infer<typeof searchUsagePageSchema>;
+export type FetchUsagePage = z.infer<typeof fetchUsagePageSchema>;
+export declare function browserSessionList(params: PageParams, apiKey: string): Promise<BrowserSessionPage>;
+export declare function browserSessionClose(sessionId: string, apiKey: string): Promise<void>;
+export declare function searchUsage(params: PageParams, apiKey: string): Promise<SearchUsagePage>;
+export declare function fetchUsage(params: PageParams, apiKey: string): Promise<FetchUsagePage>;
+declare const monitorSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    config: z.ZodObject<{
+        query: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    schedule_cron: z.ZodString;
+    status: z.ZodString;
+}, z.core.$loose>;
+declare const monitorRunSchema: z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    result_count: z.ZodOptional<z.ZodNumber>;
+    results: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$loose>;
+declare const monitorCreateResponseSchema: z.ZodObject<{
+    monitor: z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        config: z.ZodObject<{
+            query: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>;
+        schedule_cron: z.ZodString;
+        status: z.ZodString;
+    }, z.core.$loose>;
+    run: z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        result_count: z.ZodOptional<z.ZodNumber>;
+        results: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        errors: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type Monitor = z.infer<typeof monitorSchema>;
+export type MonitorRun = z.infer<typeof monitorRunSchema>;
+export type MonitorCreateResponse = z.infer<typeof monitorCreateResponseSchema>;
+export declare function monitorCreate(body: object, apiKey: string): Promise<MonitorCreateResponse>;
+export declare function monitorList(apiKey: string): Promise<{
+    monitors: Monitor[];
+}>;
+export declare function monitorGet(id: string, apiKey: string): Promise<Monitor>;
+export declare function monitorSetStatus(id: string, status: 'active' | 'paused', apiKey: string): Promise<Monitor>;
+export declare function monitorRun(id: string, apiKey: string): Promise<{
+    run: MonitorRun;
+}>;
+export declare function monitorDelete(id: string, apiKey: string): Promise<{
+    deleted: true;
+    id: string;
+}>;
 export declare function cancelRun(runId: string, apiKey: string): Promise<CancelRunResponse>;
 export declare function getWallet(apiKey: string): Promise<WalletResponse>;
 export declare function submitBatch(req: BatchRunRequest, apiKey: string): Promise<BatchRunResponse>;
 export declare function getBatchRuns(runIds: string[], apiKey: string): Promise<BatchGetResponse>;
 export declare function cancelBatchRuns(runIds: string[], apiKey: string): Promise<BatchCancelResponse>;
-export declare function profileCreate(name: string, apiKey: string): Promise<ProfileCreateResponse>;
+declare const profileListResponseSchema: z.ZodObject<{
+    profiles: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        proxy_country_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        signed_in_sites: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            site: z.ZodString;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ProfileListResponse = z.infer<typeof profileListResponseSchema>;
+export interface ProfileWriteParams {
+    name?: string;
+    proxy_country_code?: string | null;
+}
+export declare function profileCreate(params: ProfileWriteParams & {
+    name: string;
+}, apiKey: string): Promise<ProfileCreateResponse>;
+export declare function profileUpdate(profileId: string, params: ProfileWriteParams, apiKey: string): Promise<ProfileSummary>;
 export declare function profileGet(profileId: string, apiKey: string): Promise<ProfileSummary>;
-export declare function profileList(apiKey: string): Promise<ProfileSummary[]>;
+export declare function profileList(apiKey: string): Promise<ProfileListResponse>;
 export declare function profileUpload(profileId: string, cookies: CookieRecord[], apiKey: string): Promise<ProfileUploadResponse>;
 export declare function vaultConnections(apiKey: string): Promise<VaultConnectionsListResponse>;
 export declare function vaultConnect(req: VaultConnectRequest, apiKey: string): Promise<VaultConnectResponse>;

package/dist/lib/client.js

@@ -3,7 +3,7 @@ import { CONNECT_SOURCE, RUNTIME_ATTEMPT_ENV, loadConfig } from './auth.js';
 import { API_URL_OVERRIDE, CLI_AGENT_IDENTITY, CLI_VERSION } from './constants.js';
 import { detectHarness, detectHumanInitiated } from './harness.js';
 import { captureNotice } from './notice.js';
-import { ApiError } from './output.js';
+import { ApiError, parseJson } from './output.js';
 import { z } from 'zod';
 // Install-level connect context (PF-3169). A known caller is credited only to its own
 // install; under an unknown caller we credit a lone install, else send source only.
@@ -84,38 +84,30 @@ class TinyFishCliClient extends TinyFish {
         }
         return headers;
     }
-    // The SDK base client only exposes get/post/postStream; DELETE is needed for
-    // disconnecting a vault connection. ponytail: raw fetch, no retry/timeout —
-    // matches the CLI's maxRetries:0; reuse the SDK request helper if more DELETE
-    // routes appear.
-    async del(path) {
+    // SDK has no PATCH and its delete() throws on 204.
+    async send(method, path, json) {
         const response = await fetch(`${this.baseURL}${path}`, {
-            method: 'DELETE',
+            method,
             headers: this._buildHeaders(),
+            ...(json !== undefined ? { body: JSON.stringify(json) } : {}),
         });
         captureNotice(response.headers);
-        if (!response.ok) {
-            let message = response.statusText;
-            let code;
-            try {
-                const body = (await response.json());
-                if (typeof body?.error?.message === 'string')
-                    message = body.error.message;
-                else if (typeof body?.message === 'string')
-                    message = body.message;
-                if (typeof body?.error?.code === 'string')
-                    code = body.error.code;
-            }
-            catch {
-                // Non-JSON body — keep statusText
-            }
-            throw new ApiError(response.status, message, code);
-        }
+        if (!response.ok)
+            throw await apiErrorFrom(response);
         if (response.status === 204)
             return undefined;
         return (await response.json());
     }
 }
+// SDK order: JSON message, raw text, then status.
+async function apiErrorFrom(response) {
+    const text = await response.text().catch(() => '');
+    const body = parseJson(text);
+    const message = [body?.error?.message, body?.message].find((m) => typeof m === 'string') ??
+        (text || `HTTP ${response.status}`);
+    const code = typeof body?.error?.code === 'string' ? body.error.code : undefined;
+    return new ApiError(response.status, message, code);
+}
 function createSdkClient(apiKey, timeout, baseUrl) {
     // An explicit base outranks the env default.
     const resolvedBase = baseUrl ?? API_URL_OVERRIDE;
@@ -331,6 +323,103 @@ export function browserSessionCreate(params, apiKey) {
         return browserSessionSchema.parse(response);
     });
 }
+// New commands echo the full server body; looseObject keeps unknown keys.
+function pageSchema(item) {
+    return z.looseObject({
+        items: z.array(item),
+        total: z.number(),
+        page: z.number(),
+        total_pages: z.number(),
+    });
+}
+const browserSessionUsageSchema = z.looseObject({
+    session_id: z.string(),
+    status: z.string().nullable(),
+    start_time: z.string().nullable(),
+});
+const searchUsageItemSchema = z.looseObject({
+    query: z.string(),
+    status_code: z.number(),
+    result_count: z.number().nullable(),
+    created_at: z.string(),
+});
+const fetchUsageItemSchema = z.looseObject({
+    url: z.string(),
+    status: z.string(),
+    created_at: z.string(),
+});
+const browserSessionPageSchema = pageSchema(browserSessionUsageSchema);
+const searchUsagePageSchema = pageSchema(searchUsageItemSchema);
+const fetchUsagePageSchema = pageSchema(fetchUsageItemSchema);
+function getPage(path, schema, params, apiKey) {
+    return sdk(apiKey, async (client) => parseWithSchema(schema, await client.get(path, { params }), `Invalid ${path} response`));
+}
+export function browserSessionList(params, apiKey) {
+    return getPage('/v1/browser/usage', browserSessionPageSchema, params, apiKey);
+}
+export function browserSessionClose(sessionId, apiKey) {
+    return sdk(apiKey, (client) => client.send('DELETE', `/v1/browser/${encodeURIComponent(sessionId)}`));
+}
+export function searchUsage(params, apiKey) {
+    return getPage('/v1/search/usage', searchUsagePageSchema, params, apiKey);
+}
+export function fetchUsage(params, apiKey) {
+    return getPage('/v1/fetch/usage', fetchUsagePageSchema, params, apiKey);
+}
+const monitorSchema = z.looseObject({
+    id: z.string(),
+    type: z.string(),
+    config: z.looseObject({ query: z.string().optional(), url: z.string().optional() }),
+    schedule_cron: z.string(),
+    status: z.string(),
+});
+const monitorRunSchema = z.looseObject({
+    id: z.union([z.string(), z.number()]),
+    result_count: z.number().optional(),
+    results: z.array(z.unknown()).optional(),
+    errors: z.array(z.unknown()).optional(),
+});
+const monitorCreateResponseSchema = z.looseObject({
+    monitor: monitorSchema,
+    run: monitorRunSchema,
+});
+const monitorListResponseSchema = z.looseObject({ monitors: z.array(monitorSchema) });
+const monitorRunResponseSchema = z.looseObject({ run: monitorRunSchema });
+const monitorDeleteResponseSchema = z.looseObject({ deleted: z.literal(true), id: z.string() });
+const monitorPath = (id) => `/v1/monitors/${encodeURIComponent(id)}`;
+export function monitorCreate(body, apiKey) {
+    return sdk(apiKey, async (client) => {
+        const response = await client.post('/v1/monitors', { json: body });
+        return parseWithSchema(monitorCreateResponseSchema, response, 'Invalid monitor create response');
+    });
+}
+export function monitorList(apiKey) {
+    return sdk(apiKey, async (client) => {
+        const response = await client.get('/v1/monitors');
+        return parseWithSchema(monitorListResponseSchema, response, 'Invalid monitor list response');
+    });
+}
+export function monitorGet(id, apiKey) {
+    return sdk(apiKey, async (client) => parseWithSchema(monitorSchema, await client.get(monitorPath(id)), 'Invalid monitor response'));
+}
+export function monitorSetStatus(id, status, apiKey) {
+    return sdk(apiKey, async (client) => {
+        const response = await client.send('PATCH', monitorPath(id), { status });
+        return parseWithSchema(monitorSchema, response, 'Invalid monitor response');
+    });
+}
+export function monitorRun(id, apiKey) {
+    return sdk(apiKey, async (client) => {
+        const response = await client.post(`${monitorPath(id)}/runs`, { json: {} });
+        return parseWithSchema(monitorRunResponseSchema, response, 'Invalid monitor run response');
+    });
+}
+export function monitorDelete(id, apiKey) {
+    return sdk(apiKey, async (client) => {
+        const response = await client.send('DELETE', monitorPath(id));
+        return parseWithSchema(monitorDeleteResponseSchema, response, 'Invalid monitor delete response');
+    });
+}
 export function cancelRun(runId, apiKey) {
     return sdk(apiKey, async (client) => {
         const response = await client.post(`/v1/runs/${encodeURIComponent(runId)}/cancel`, {
@@ -367,27 +456,38 @@ export function cancelBatchRuns(runIds, apiKey) {
         return parseWithSchema(batchCancelResponseSchema, response, 'Invalid batch cancel response');
     });
 }
-const profileCreateResponseSchema = z.object({
+const profileCreateResponseSchema = z.looseObject({
     id: z.string(),
     name: z.string(),
     created_at: z.string(),
 });
 const profileSummarySchema = z.object({ id: z.string(), name: z.string() });
-const profileListResponseSchema = z.object({ profiles: z.array(profileSummarySchema) });
+const profileListResponseSchema = z.looseObject({
+    profiles: z.array(profileSummarySchema
+        .extend({
+        proxy_country_code: z.string().nullish(),
+        signed_in_sites: z.array(z.looseObject({ site: z.string() })).optional(),
+    })
+        .loose()),
+});
 const profileUploadResponseSchema = z.object({
     profile_id: z.string().optional(),
     cookie_count: z.number(),
     domains_updated: z.array(z.string()),
     domains_failed: z.array(z.string()).optional(),
 });
-export function profileCreate(name, apiKey) {
+export function profileCreate(params, apiKey) {
     return sdk(apiKey, async (client) => {
-        const response = await client.post('/v1/profiles', {
-            json: { name },
-        });
+        const response = await client.post('/v1/profiles', { json: params });
         return parseWithSchema(profileCreateResponseSchema, response, 'Invalid profile create response');
     });
 }
+export function profileUpdate(profileId, params, apiKey) {
+    return sdk(apiKey, async (client) => {
+        const response = await client.send('PATCH', `/v1/profiles/${encodeURIComponent(profileId)}`, params);
+        return parseWithSchema(profileSummarySchema.loose(), response, 'Invalid profile response');
+    });
+}
 export function profileGet(profileId, apiKey) {
     return sdk(apiKey, async (client) => {
         const response = await client.get(`/v1/profiles/${encodeURIComponent(profileId)}`);
@@ -397,8 +497,7 @@ export function profileGet(profileId, apiKey) {
 export function profileList(apiKey) {
     return sdk(apiKey, async (client) => {
         const response = await client.get('/v1/profiles');
-        return parseWithSchema(profileListResponseSchema, response, 'Invalid profile list response')
-            .profiles;
+        return parseWithSchema(profileListResponseSchema, response, 'Invalid profile list response');
     });
 }
 export function profileUpload(profileId, cookies, apiKey) {
@@ -470,7 +569,7 @@ export function vaultConnect(req, apiKey) {
 }
 export function vaultDisconnect(connectionId, apiKey) {
     return sdk(apiKey, async (client) => {
-        const response = await client.del(`/v1/vault/connections/${encodeURIComponent(connectionId)}`);
+        const response = await client.send('DELETE', `/v1/vault/connections/${encodeURIComponent(connectionId)}`);
         return parseWithSchema(vaultDisconnectResponseSchema, response, 'Invalid vault disconnect response');
     });
 }

package/dist/lib/connect-runtime.js

@@ -179,6 +179,18 @@ export async function runGuarded(state, telemetry, body) {
 function probeTimeoutMs(client) {
     return client.supportCheck.timeoutMs ?? NON_INTERACTIVE_TIMEOUT_MS;
 }
+// Flags go unseen for reasons besides age; state facts, not causes.
+function unavailableMessage(client, version) {
+    const { minVersion } = client.supportCheck;
+    const found = version ? ` (found ${version})` : '';
+    // Numeric collation orders dotted versions: 7.7.3 sorts after 7.4.13.
+    const belowMin = minVersion && (!version || version.localeCompare(minVersion, 'en', { numeric: true }) < 0);
+    const required = belowMin
+        ? ` ${client.displayName} ${minVersion} or newer is required${found}.`
+        : '';
+    return (`${client.supportCheck.unavailableMessage}${required}` +
+        ' Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.');
+}
 function throwProbeFailure(client, result) {
     throwIfInterrupted(result);
     // A hung probe is a timeout, not a missing capability.
@@ -188,10 +200,13 @@ function throwProbeFailure(client, result) {
             `${probeTimeoutMs(client) / 1000}s. Retry.`, 'timeout', { cause: result.error, failureDetail: spawnFailureDetail(result) });
     }
     // It ran and exited non-zero, so the version is still answerable.
-    throw new ConnectStepError(client.supportCheck.unavailableMessage, 'harness_command_unsupported', {
+    debugProbeOutput(client, sanitizeLine(`${result.stdout ?? ''}\n${result.stderr ?? ''}`));
+    const harnessVersion = probeHarnessVersion(client);
+    throw new ConnectStepError(unavailableMessage(client, harnessVersion), 'harness_command_unsupported', {
         cause: result.error,
-        harnessVersion: probeHarnessVersion(client),
-        failureDetail: spawnFailureDetail(result),
+        harnessVersion,
+        // A spawn error leaves stderr empty; its message is the diagnosis.
+        failureDetail: result.error?.message ?? spawnFailureDetail(result),
     });
 }
 function supportProbeOutput(client) {
@@ -220,8 +235,9 @@ function requireEssential(client, output) {
     if (client.supportCheck.patterns.every((pattern) => pattern.test(output)))
         return;
     debugProbeOutput(client, output);
-    throw new ConnectStepError(client.supportCheck.unavailableMessage, 'harness_too_old', {
-        harnessVersion: probeHarnessVersion(client),
+    const harnessVersion = probeHarnessVersion(client);
+    throw new ConnectStepError(unavailableMessage(client, harnessVersion), 'harness_too_old', {
+        harnessVersion,
     });
 }
 /** Absence is a fact; an unknown flag means an upstream rename. */

package/dist/lib/harness/harness-messages.js

@@ -1,9 +1,6 @@
 // User-facing copy for the harness specs; kept apart so the spec file stays structure.
-// An old install is only one reason a flag can go unseen, so no message asserts the cause.
-const SUPPORT_CHECK_DEBUG_HINT = ' Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.';
 export const MCP_ADD_UNAVAILABLE_MESSAGE = 'Could not confirm this Claude Code installation exposes `claude mcp add`: `claude mcp ' +
-    '--help` did not list it. Update Claude Code with `claude update` and retry.' +
-    SUPPORT_CHECK_DEBUG_HINT;
+    '--help` did not list it. Update Claude Code with `claude update` and retry.';
 // `claude mcp login` only exists upstream from Claude Code 2.1.186; older installs still register.
 export const CLAUDE_CODE_KEYED_FALLBACK_NOTE = 'Using your stored TinyFish API key: this Claude Code predates one-command sign-in ' +
     '(`claude mcp login`), so no browser sign-in is needed.';
@@ -13,8 +10,7 @@ export const CLAUDE_CODE_DEFERRED_AUTH_NOTE = 'TinyFish is registered in Claude
     'Run `tinyfish connect claude-code --api-key <key>` instead.';
 export const CODEX_MCP_URL_UNAVAILABLE_MESSAGE = 'Could not confirm this Codex installation supports remote MCP servers: `codex mcp add ' +
     '--help` did not list `--url`. Update Codex and retry, or add TinyFish manually with ' +
-    '`codex mcp add`.' +
-    SUPPORT_CHECK_DEBUG_HINT;
+    '`codex mcp add`.';
 export const CODEX_KEYED_FALLBACK_NOTE = 'Using your stored TinyFish API key: this Codex cannot report whether an OAuth sign-in ' +
     'finished, so no browser sign-in is attempted.';
 export const CODEX_DEFERRED_AUTH_NOTE = 'TinyFish is registered in Codex but not signed in: this Codex predates reliable sign-in ' +
@@ -22,24 +18,20 @@ export const CODEX_DEFERRED_AUTH_NOTE = 'TinyFish is registered in Codex but not
     '`npm install -g @openai/codex@latest` for one-command sign-in.';
 export const HERMES_OAUTH_UNAVAILABLE_MESSAGE = 'Could not confirm this Hermes installation supports one-command MCP authentication: `hermes ' +
     'mcp add --help` did not list `--auth oauth`. Update Hermes and retry, or add TinyFish ' +
-    'manually with `hermes mcp add`.' +
-    SUPPORT_CHECK_DEBUG_HINT;
+    'manually with `hermes mcp add`.';
 export const GROK_HTTP_UNAVAILABLE_MESSAGE = 'Could not confirm this Grok installation supports remote MCP servers: `grok mcp add --help` ' +
     'did not list `--transport`. Update Grok and retry, or add TinyFish manually with ' +
-    '`grok mcp add`.' +
-    SUPPORT_CHECK_DEBUG_HINT;
+    '`grok mcp add`.';
 // Grok has no `mcp login`; sign-in only happens inside the TUI. No key nudge here: a revoked
 // key leaves Grok with no OAuth fallback, and doctor cannot spot that yet (PF-3618).
 export const GROK_SIGN_IN_HINT = 'TinyFish is registered in Grok. Open Grok, run `/mcps`, select tinyfish, and press `i` to ' +
     'sign in.';
 export const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = 'Could not confirm this OpenClaw installation supports global skill installation: `openclaw ' +
     'skills install --help` did not list `--global`. Update OpenClaw and retry, or install ' +
-    'manually with `openclaw skills install @tinyfish/tinyfish --global`.' +
-    SUPPORT_CHECK_DEBUG_HINT;
+    'manually with `openclaw skills install @tinyfish/tinyfish --global`.';
 export const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = 'Could not confirm this OpenCode installation supports one-command MCP setup: `opencode mcp ' +
     'add --help` did not list `--url`. Update OpenCode and retry, or add TinyFish manually with ' +
-    '`opencode mcp add`.' +
-    SUPPORT_CHECK_DEBUG_HINT;
+    '`opencode mcp add`.';
 // OpenCode is model-agnostic (unlike Claude Code / Codex), so a fresh install can default to a
 // model with no tool support — TinyFish runs entirely on tool calls, so it would fail there.
 export const OPENCODE_MODEL_NOTE = 'Note: TinyFish runs on tool calls, so OpenCode needs a model that supports tool use. Image-only ' +
@@ -47,9 +39,8 @@ export const OPENCODE_MODEL_NOTE = 'Note: TinyFish runs on tool calls, so OpenCo
     "OpenCode's model if the walkthrough can't start.";
 export const KILO_MCP_ADD_UNAVAILABLE_MESSAGE = 'Could not confirm this Kilo Code installation supports remote MCP servers: `kilo mcp add ' +
     '--help` did not list `--url`. Update Kilo Code with `kilo upgrade` and retry, or add ' +
-    'TinyFish manually with `kilo mcp add`.' +
-    SUPPORT_CHECK_DEBUG_HINT;
+    'TinyFish manually with `kilo mcp add`.';
 export const HERMES_RESTART_NOTE = 'Restart your Hermes session to pick up TinyFish — Hermes discovers MCP servers at startup.';
 export const CLINE_MCP_ADD_UNAVAILABLE_MESSAGE = 'Could not confirm this Cline installation supports non-interactive MCP setup: `cline mcp add ' +
-    '--help` did not list `--transport` and `--yes`. Update Cline with `cline --update` and retry.' +
-    SUPPORT_CHECK_DEBUG_HINT;
+    '--help` did not list `--transport` and `--yes`. Update Cline with `npm i -g cline@latest` ' +
+    'or `cline --update` and retry.';

package/dist/lib/harness/harness-spec.d.ts

@@ -14,6 +14,8 @@ export interface HarnessSupportCheck {
     unknownVariant?: RegExp;
     /** Defaults to NON_INTERACTIVE_TIMEOUT_MS; raise for a slow cold start. */
     timeoutMs?: number;
+    /** First release with the probed flags; bisected upstream, not derivable. */
+    minVersion?: string;
     unavailableMessage: string;
 }
 /** One entry per harness: every per-harness fact, and no behaviour. */
@@ -124,6 +126,8 @@ export declare const HARNESS_SPECS: {
             args: string[];
             patterns: RegExp[];
             keyAuthPattern: RegExp;
+            timeoutMs: number;
+            minVersion: string;
             unavailableMessage: string;
         };
         urlStyle: "positional";
@@ -232,6 +236,7 @@ export declare const HARNESS_SPECS: {
             args: string[];
             patterns: RegExp[];
             keyAuthPattern: RegExp;
+            minVersion: string;
             unavailableMessage: string;
         };
         urlStyle: "flag";

package/dist/lib/harness/harness-spec.js

@@ -51,6 +51,9 @@ export const HARNESS_SPECS = {
             // Without `--yes` the add opens a wizard and exits non-zero off a TTY.
             patterns: [/--transport(?:[\s<=]|$)/m, /--yes(?:[\s<=]|$)/m],
             keyAuthPattern: HEADER_FLAG,
+            // Cold start on first run outlasts the 10s default.
+            timeoutMs: 30_000,
+            minVersion: '3.0.30',
             unavailableMessage: CLINE_MCP_ADD_UNAVAILABLE_MESSAGE,
         },
         urlStyle: 'positional',
@@ -162,6 +165,7 @@ export const HARNESS_SPECS = {
             args: ['mcp', 'add', '--help'],
             patterns: [/--url(?:\s|$)/m],
             keyAuthPattern: HEADER_FLAG,
+            minVersion: '7.4.13',
             unavailableMessage: KILO_MCP_ADD_UNAVAILABLE_MESSAGE,
         },
         urlStyle: 'flag',

package/dist/lib/list-options.d.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+export declare function integerInRange(min: number, max?: number): (value: string) => number;
+export interface PageOptions {
+    startAfter?: string;
+    endBefore?: string;
+    status?: string;
+    limit?: number;
+    page?: number;
+    pretty?: boolean;
+}
+export type PageParams = Record<string, string | number>;
+export declare function addPageOptions(cmd: Command, statuses: string): Command;
+export declare function pageParams(opts: PageOptions): PageParams;
+interface Page<T> {
+    items: T[];
+    total: number;
+    page: number;
+    total_pages: number;
+}
+export declare function printPage<T>(result: Page<T>, pretty: boolean | undefined, line: (item: T) => string): void;
+export {};

package/dist/lib/list-options.js

@@ -0,0 +1,46 @@
+import { InvalidArgumentError } from 'commander';
+import { out, outLine } from './output.js';
+const MAX_PAGE_SIZE = 1000;
+export function integerInRange(min, max) {
+    return (value) => {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < min || (max !== undefined && parsed > max)) {
+            throw new InvalidArgumentError(max === undefined
+                ? 'must be a positive integer'
+                : `must be an integer between ${min} and ${max}`);
+        }
+        return parsed;
+    };
+}
+export function addPageOptions(cmd, statuses) {
+    return cmd
+        .option('--start-after <iso>', 'Only items created after this ISO 8601 timestamp')
+        .option('--end-before <iso>', 'Only items created before this ISO 8601 timestamp')
+        .option('--status <status>', `Filter by status (${statuses})`)
+        .option('--limit <n>', `Items per page, 1-${MAX_PAGE_SIZE} (default 100)`, integerInRange(1, MAX_PAGE_SIZE))
+        .option('--page <n>', 'Page number, starting from 1', integerInRange(1))
+        .option('--pretty', 'Human-readable output');
+}
+export function pageParams(opts) {
+    const params = {};
+    if (opts.startAfter !== undefined)
+        params.start_after = opts.startAfter;
+    if (opts.endBefore !== undefined)
+        params.end_before = opts.endBefore;
+    if (opts.status !== undefined)
+        params.status = opts.status;
+    if (opts.limit !== undefined)
+        params.limit = opts.limit;
+    if (opts.page !== undefined)
+        params.page = opts.page;
+    return params;
+}
+export function printPage(result, pretty, line) {
+    if (!pretty)
+        return out(result);
+    if (result.items.length === 0)
+        outLine('No items.');
+    for (const item of result.items)
+        outLine(line(item));
+    outLine(`Page ${result.page} of ${result.total_pages} (${result.total} total)`);
+}

package/dist/program.js

@@ -26,6 +26,7 @@ const GROUPS = {
     },
     search: async (p) => (await import('./commands/search.js')).registerSearch(p),
     fetch: async (p) => (await import('./commands/fetch.js')).registerFetch(p),
+    monitor: async (p) => (await import('./commands/monitor.js')).registerMonitor(p),
 };
 /** Commander answers these before routing, so no command module is needed. */
 const VERSION_FLAGS = ['-V', '--version'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.48.3-next.389",
+  "version": "0.48.3-next.392",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {