browserlessapi 0.0.0-stage → 1.0.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# browserlessapi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The command-line tool for [BrowserlessAPI](https://browserlessapi.com/): turn any web
+page into Markdown, take screenshots, run browser steps, solve captchas, and connect
+BrowserlessAPI to AI apps such as Claude, ChatGPT, Cursor and VS Code.
+
+Pages are fetched by a real browser when needed, including JavaScript-heavy and
+Cloudflare-protected sites.
+
+## Install
+
+```bash
+npm install -g browserlessapi
+# or run without installing:
+npx browserlessapi --help
+```
+
+Node.js 18 or later. No other dependencies.
+
+## Sign in
+
+Get an API key at [browserlessapi.com](https://browserlessapi.com/register/), then:
+
+```bash
+browserlessapi auth                      # paste your key when asked
+browserlessapi auth --api-key YOUR_KEY   # or non-interactive
+```
+
+The key is checked, then saved to `~/.config/browserlessapi/config.json` (readable only
+by you). You can also set `BROWSERLESSAPI_API_KEY`, or pass `--api-key` to any command.
+`browserlessapi logout` removes the saved key.
+
+## Commands
+
+```bash
+# A page as Markdown
+browserlessapi scrape https://example.com
+
+# Several formats at once (prints JSON)
+browserlessapi scrape https://example.com -f markdown,links,metadata
+
+# Save to a file; always use a browser; keep headers and footers
+browserlessapi scrape https://example.com --render true --full -o page.md
+
+# Many pages: one URL per line, 5 at a time, a file per page plus manifest.json
+browserlessapi scrape --input-file urls.txt --output-dir pages -c 5
+
+# Screenshot
+browserlessapi screenshot https://example.com -o example.png --wait-for h1
+
+# Browser steps in one session (click, type, extract, screenshot)
+browserlessapi steps '[{"action":"goto","url":"https://example.com"},{"action":"extract","selector":"h1","as":"title"}]'
+
+# Solve a captcha
+browserlessapi captcha --task '{"type":"RecaptchaV2Task","websiteURL":"https://site/page","websiteKey":"SITE_KEY"}'
+
+# Plan, credits and features
+browserlessapi account
+```
+
+Scrape options: `--format`, `--render auto|true|false`, `--captcha auto|always|off`,
+`--full`, `--engine puppeteer|playwright`, `--json`, `--output-file`.
+Status lines go to stderr, content to stdout, so output can be piped.
+
+## Use BrowserlessAPI in AI apps (MCP)
+
+BrowserlessAPI runs a remote MCP server at `https://browserlessapi.com/mcp/v2`.
+Print the setup for your app, with your key filled in:
+
+```bash
+browserlessapi mcp claude        # claude.ai and Claude desktop
+browserlessapi mcp claude-code   # Claude Code
+browserlessapi mcp chatgpt       # ChatGPT
+browserlessapi mcp cursor        # Cursor
+browserlessapi mcp vscode        # VS Code
+browserlessapi mcp codex         # OpenAI Codex
+browserlessapi mcp neoncodex     # NeonCodex
+```
+
+Tools available to the AI: `scrape_page`, `take_screenshot`, `run_browser_steps`,
+`solve_captcha`, `check_account` and `fetch`. Needs a plan that includes the MCP server.
+
+## Credits
+
+Every request uses credits from your BrowserlessAPI account, the same as calling the API
+directly. `browserlessapi account` shows your balance.
+
+## Safety
+
+This tool never runs shell commands based on page content, so text on a scraped page
+cannot make it execute anything. Keep your API key out of shared files and repositories.
+
+## Exit codes
+
+`0` success, `1` request failed, `2` usage error.
+
+## License
+
+MIT

package/bin/browserlessapi.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+/**
+ * BrowserlessAPI command-line tool.
+ * Docs: https://browserlessapi.com/api-docs/
+ *
+ * Scrape pages, take screenshots, run browser steps, solve captchas and
+ * connect BrowserlessAPI to AI apps (Claude, ChatGPT, Cursor, VS Code,
+ * Codex, NeonCodex) from your terminal. No dependencies; Node 18 or later.
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+
+const VERSION = '1.0.0';
+const BASE = (process.env.BROWSERLESSAPI_BASE_URL || 'https://browserlessapi.com').replace(/\/+$/, '');
+const API = BASE + '/wp-json/browserless';
+const MCP_URL = BASE + '/mcp/v2';
+const CONFIG_DIR = process.env.BROWSERLESSAPI_CONFIG_DIR || path.join(os.homedir(), '.config', 'browserlessapi');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const FORMATS = ['markdown', 'text', 'links', 'metadata', 'html'];
+
+// ------------------------------------------------------------------- output
+const out = (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n');
+const err = (s) => process.stderr.write(s.endsWith('\n') ? s : s + '\n');
+class UsageError extends Error {}
+class ApiError extends Error {}
+
+// ------------------------------------------------------------------ args
+// Flags that never take a value (so "--json URL" doesn't eat the URL).
+const BOOL_FLAGS = new Set(['json', 'full', 'show', 'help', 'version', 'no-key']);
+function parseArgs(argv) {
+    const pos = [];
+    const opt = {};
+    const short = { o: 'output-file', f: 'format', h: 'help', v: 'version', k: 'api-key', c: 'concurrency' };
+    for (let i = 0; i < argv.length; i++) {
+        let a = argv[i];
+        if (a === '--') { pos.push(...argv.slice(i + 1)); break; }
+        if (/^-[a-z]$/.test(a)) a = '--' + short[a[1]];
+        if (a && a.startsWith('--')) {
+            let [k, v] = a.slice(2).split(/=(.*)/s);
+            if (v === undefined) {
+                const next = argv[i + 1];
+                if (!BOOL_FLAGS.has(k) && next !== undefined && (next === '-' || !next.startsWith('-'))) { v = next; i++; } else v = true;
+            }
+            opt[k] = v;
+        } else pos.push(a);
+    }
+    return { pos, opt };
+}
+
+// ------------------------------------------------------------------ config
+function readConfig() {
+    try { return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch { return {}; }
+}
+function writeConfig(cfg) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+    try { fs.chmodSync(CONFIG_FILE, 0o600); } catch {}
+}
+function apiKey(opt, required = true) {
+    const k = (typeof opt['api-key'] === 'string' && opt['api-key']) || process.env.BROWSERLESSAPI_API_KEY || readConfig().api_key || '';
+    if (!k && required) throw new UsageError('No API key. Run "browserlessapi auth", set BROWSERLESSAPI_API_KEY, or pass --api-key. Get a key at https://browserlessapi.com/register/');
+    return k;
+}
+const mask = (k) => (k.length > 8 ? k.slice(0, 4) + '...' + k.slice(-4) : '****');
+
+// --------------------------------------------------------------------- http
+async function call(method, p, key, body, timeoutMs = 200000) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(API + p, {
+            method,
+            headers: { 'Content-Type': 'application/json', 'X-API-Key': key, 'User-Agent': `browserlessapi-cli/${VERSION}` },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: ctrl.signal,
+        });
+    } catch (e) {
+        throw new ApiError(e.name === 'AbortError' ? 'The request timed out.' : `Could not reach ${BASE}: ${e.message}`);
+    } finally {
+        clearTimeout(t);
+    }
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { data = { raw: text.slice(0, 300) }; }
+    if (!res.ok || data.status === 'error') {
+        const e = data.error;
+        const msg = e && typeof e === 'object' ? `${e.message || e.code}${e.code ? ` (${e.code})` : ''}` : (e || data.message || `HTTP ${res.status}`);
+        throw new ApiError(msg);
+    }
+    return data;
+}
+
+function save(file, content) {
+    fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+    fs.writeFileSync(file, content);
+}
+function readJsonArg(v, label) {
+    if (v === undefined || v === true) throw new UsageError(`${label} is required.`);
+    const src = v === '-' ? fs.readFileSync(0, 'utf8') : (fs.existsSync(v) ? fs.readFileSync(v, 'utf8') : v);
+    try { return JSON.parse(src); } catch { throw new UsageError(`${label} is not valid JSON (give JSON, a file path, or - for stdin).`); }
+}
+
+// ---------------------------------------------------------------- commands
+async function cmdAuth(opt) {
+    if (opt.show) {
+        const k = apiKey(opt, false);
+        const src = opt['api-key'] ? 'flag' : process.env.BROWSERLESSAPI_API_KEY ? 'BROWSERLESSAPI_API_KEY' : readConfig().api_key ? CONFIG_FILE : null;
+        out(k ? `API key ${mask(k)} (from ${src})` : 'No API key saved.');
+        return;
+    }
+    let key = typeof opt['api-key'] === 'string' ? opt['api-key'] : '';
+    if (!key) {
+        if (!process.stdin.isTTY) key = fs.readFileSync(0, 'utf8').trim();
+        else {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+            key = (await new Promise((r) => rl.question('BrowserlessAPI API key (from https://browserlessapi.com/portal/ > API Keys): ', r))).trim();
+            rl.close();
+        }
+    }
+    if (!key) throw new UsageError('No key entered.');
+    const acct = await call('GET', '/v2/account', key, undefined, 20000);
+    writeConfig({ ...readConfig(), api_key: key });
+    out(`Saved. Plan: ${acct.plan}, credits: ${acct.credits}. Key stored in ${CONFIG_FILE}`);
+}
+
+function cmdLogout() {
+    const cfg = readConfig();
+    delete cfg.api_key;
+    if (fs.existsSync(CONFIG_FILE)) writeConfig(cfg);
+    out('API key removed from ' + CONFIG_FILE);
+}
+
+async function cmdAccount(opt) {
+    const d = await call('GET', '/v2/account', apiKey(opt), undefined, 20000);
+    if (opt.json) return out(JSON.stringify(d, null, 2));
+    const on = Object.entries(d.features || {}).filter(([, v]) => v).map(([k]) => k);
+    out(`Plan:         ${d.plan}\nCredits:      ${d.credits}\nConcurrency:  ${d.max_concurrency}\nFeatures:     ${on.join(', ') || 'none'}`);
+}
+
+function scrapeBody(url, opt) {
+    let formats = typeof opt.format === 'string' ? opt.format.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean) : ['markdown'];
+    const bad = formats.filter((f) => !FORMATS.includes(f));
+    if (bad.length) throw new UsageError(`Unknown format: ${bad.join(', ')}. Use: ${FORMATS.join(', ')}`);
+    const body = { url, formats };
+    if (opt.render !== undefined) {
+        const r = String(opt.render);
+        if (!['auto', 'true', 'false'].includes(r)) throw new UsageError('--render must be auto, true or false.');
+        body.render = r === 'auto' ? 'auto' : r === 'true';
+    }
+    if (opt.captcha !== undefined) {
+        if (!['auto', 'always', 'off'].includes(String(opt.captcha))) throw new UsageError('--captcha must be auto, always or off.');
+        body.captcha = String(opt.captcha);
+    }
+    if (opt.full) body.only_main_content = false;
+    if (typeof opt.engine === 'string') body.engine = opt.engine;
+    return body;
+}
+function renderScrape(d, body) {
+    const f = d.formats || {};
+    if (body.formats.length === 1) {
+        const v = f[body.formats[0]];
+        return typeof v === 'string' ? v : JSON.stringify(v, null, 2);
+    }
+    return JSON.stringify(f, null, 2);
+}
+function reportScrape(d) {
+    let s = `[${d.status_code}] ${d.final_url}  rendered_with=${d.rendered_with}  credits=${d.credits_charged}  ${d.timing_ms}ms`;
+    if (d.captcha) s += `  captcha=${d.captcha.type}:${d.captcha.solved ? 'solved' : d.captcha.reason}`;
+    err(s);
+}
+
+async function cmdScrape(pos, opt) {
+    const key = apiKey(opt);
+    if (opt['input-file']) return scrapeBatch(key, opt);
+    if (!pos.length) throw new UsageError('Give a URL: browserlessapi scrape https://example.com');
+    const body = scrapeBody(pos[0], opt);
+    const d = await call('POST', '/v2/scrape', key, body);
+    reportScrape(d);
+    const content = opt.json ? JSON.stringify(d, null, 2) : renderScrape(d, body);
+    if (typeof opt['output-file'] === 'string') { save(opt['output-file'], content); err('Saved ' + opt['output-file']); }
+    else out(content);
+}
+
+async function scrapeBatch(key, opt) {
+    const src = opt['input-file'] === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(String(opt['input-file']), 'utf8');
+    const urls = [...new Set(src.split(/\r?\n/).map((l) => l.split(',')[0].trim()).filter((l) => /^https?:\/\//i.test(l)))];
+    if (!urls.length) throw new UsageError('No http(s) URLs found in the input file (one per line).');
+    const dir = typeof opt['output-dir'] === 'string' ? opt['output-dir'] : 'browserlessapi-' + new Date().toISOString().slice(0, 19).replace(/[:T]/g, '');
+    fs.mkdirSync(dir, { recursive: true });
+    const conc = Math.max(1, Math.min(20, parseInt(opt.concurrency, 10) || 3));
+    const probe = scrapeBody(urls[0], opt);
+    const ext = probe.formats.length === 1 && ['markdown', 'text', 'html'].includes(probe.formats[0])
+        ? { markdown: '.md', text: '.txt', html: '.html' }[probe.formats[0]] : '.json';
+    const manifest = [];
+    let next = 0, done = 0, failed = 0, credits = 0;
+    err(`Scraping ${urls.length} URLs, ${conc} at a time, into ${dir}/`);
+    async function worker() {
+        while (next < urls.length) {
+            const i = next++;
+            const url = urls[i];
+            const file = path.join(dir, String(i + 1).padStart(4, '0') + ext);
+            try {
+                const body = scrapeBody(url, opt);
+                const d = await call('POST', '/v2/scrape', key, body);
+                save(file, opt.json ? JSON.stringify(d, null, 2) : renderScrape(d, body));
+                credits += d.credits_charged || 0;
+                manifest.push({ n: i + 1, url, file: path.basename(file), status: 'ok', final_url: d.final_url, credits: d.credits_charged, captcha: d.captcha || null });
+            } catch (e) {
+                failed++;
+                manifest.push({ n: i + 1, url, file: null, status: 'error', error: e.message });
+            }
+            done++;
+            err(`  ${done}/${urls.length} ${manifest[manifest.length - 1].status === 'ok' ? 'ok   ' : 'error'} ${url}`);
+        }
+    }
+    await Promise.all(Array.from({ length: conc }, worker));
+    manifest.sort((a, b) => a.n - b.n);
+    save(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+    err(`Done: ${done - failed} ok, ${failed} failed, ${credits} credits. Manifest: ${path.join(dir, 'manifest.json')}`);
+    if (failed) process.exitCode = 1;
+}
+
+function bqlResult(d) {
+    for (const c of [d, d && d.result, d && d.data]) if (c && (Array.isArray(c.extracted) || Array.isArray(c.screenshots) || 'success' in c)) return c;
+    return d || {};
+}
+
+async function cmdScreenshot(pos, opt) {
+    if (!pos.length) throw new UsageError('Give a URL: browserlessapi screenshot https://example.com -o page.png');
+    const steps = [{ action: 'goto', url: pos[0] }];
+    if (typeof opt['wait-for'] === 'string') steps.push({ action: 'waitForSelector', selector: opt['wait-for'] });
+    steps.push({ action: 'screenshot', as: 'page' });
+    const key = apiKey(opt);
+    const res = bqlResult(await call('POST', '/v1/bql', key, { key, steps }));
+    const shot = (res.screenshots || [])[0];
+    if (!shot || !shot.base64) throw new ApiError(res.error || 'No screenshot returned.');
+    const file = typeof opt['output-file'] === 'string' ? opt['output-file'] : 'screenshot.png';
+    save(file, Buffer.from(String(shot.base64).replace(/^data:image\/\w+;base64,/, ''), 'base64'));
+    out('Saved ' + file);
+}
+
+async function cmdSteps(pos, opt) {
+    let steps = readJsonArg(pos[0], 'A steps file (or JSON, or - for stdin)');
+    if (steps && Array.isArray(steps.steps)) steps = steps.steps;
+    if (!Array.isArray(steps) || !steps.length || steps[0].action !== 'goto') throw new UsageError('Steps must be a JSON array whose first step is {"action":"goto","url":"..."}.');
+    const key = apiKey(opt);
+    const res = bqlResult(await call('POST', '/v1/bql', key, { key, steps }));
+    if (res.success === false) throw new ApiError(res.error || 'The steps failed.');
+    const dir = typeof opt['output-dir'] === 'string' ? opt['output-dir'] : '.';
+    const shots = [];
+    (res.screenshots || []).forEach((s, i) => {
+        if (!s || !s.base64) return;
+        const f = path.join(dir, (s.as || 'screenshot-' + (i + 1)).replace(/[^\w.-]/g, '_') + '.png');
+        save(f, Buffer.from(String(s.base64).replace(/^data:image\/\w+;base64,/, ''), 'base64'));
+        shots.push(f);
+    });
+    const summary = { finalUrl: res.finalUrl, extracted: res.extracted || [], screenshots: shots };
+    if (res.evaluated !== undefined) summary.evaluated = res.evaluated;
+    const content = JSON.stringify(summary, null, 2);
+    if (typeof opt['output-file'] === 'string') { save(opt['output-file'], content); err('Saved ' + opt['output-file']); } else out(content);
+}
+
+async function cmdCaptcha(opt) {
+    const task = opt['task-file'] ? readJsonArg(String(opt['task-file']), '--task-file') : readJsonArg(opt.task, '--task');
+    if (!task || typeof task.type !== 'string') throw new UsageError('The task needs a "type", e.g. {"type":"RecaptchaV2Task","websiteURL":"...","websiteKey":"..."}');
+    const body = { task };
+    if (opt.timeout) body.timeout = parseInt(opt.timeout, 10);
+    const d = await call('POST', '/v2/captcha', apiKey(opt), body);
+    if (d.status === 'pending') { err(`Still solving. Task ${d.task_id}; try again with a longer --timeout.`); process.exitCode = 1; return; }
+    out(opt.json ? JSON.stringify(d, null, 2) : JSON.stringify(d.solution, null, 2));
+    err(`task ${d.task_id}, credits ${d.credits_charged}`);
+}
+
+function cmdMcp(pos, opt) {
+    const real = opt['no-key'] ? '' : apiKey(opt, false);
+    const key = real || 'YOUR_API_KEY';
+    const urlKey = `${MCP_URL}?api_key=${key}`;
+    const client = (pos[0] || '').toLowerCase();
+    const guides = {
+        'claude-code': () => `Run in a terminal:\n\n  claude mcp add --transport http browserlessapi ${MCP_URL} --header "Authorization: Bearer ${key}"\n\nThen run /mcp inside Claude Code to check it is connected.`,
+        'claude': () => `claude.ai and the Claude desktop app (Settings > Connectors > Add custom connector):\n\n  Name: BrowserlessAPI\n  URL:  ${urlKey}\n\nOr, in claude_desktop_config.json (Settings > Developer > Edit Config), then restart Claude:\n\n${JSON.stringify({ mcpServers: { browserlessapi: { command: 'npx', args: ['-y', 'mcp-remote', MCP_URL, '--header', `Authorization: Bearer ${key}`] } } }, null, 2)}`,
+        'chatgpt': () => `ChatGPT (chatgpt.com, plan with developer mode):\n\n  1. Settings > Apps > Advanced settings > turn on Developer mode\n  2. Settings > Apps > Create\n  3. Name: BrowserlessAPI\n  4. MCP server URL: ${urlKey}\n  5. Authentication: No authentication\n  6. Tick the confirmation box, click Create, then Connect\n\nUse it with @BrowserlessAPI in a chat.`,
+        'cursor': () => `Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):\n\n${JSON.stringify({ mcpServers: { browserlessapi: { url: MCP_URL, headers: { Authorization: `Bearer ${key}` } } } }, null, 2)}\n\nThen Cursor Settings > MCP: turn browserlessapi on.`,
+        'vscode': () => `Add to .vscode/mcp.json (or your user mcp.json):\n\n${JSON.stringify({ servers: { browserlessapi: { type: 'http', url: MCP_URL, headers: { Authorization: `Bearer ${key}` } } } }, null, 2)}`,
+        'codex': () => `Add to ~/.codex/config.toml (needs Node.js 18+ for npx):\n\n[mcp_servers.browserlessapi]\ncommand = "npx"\nargs = ["-y", "mcp-remote", "${urlKey}"]\n\nRestart Codex, then run "codex mcp list" to check it.`,
+        'neoncodex': () => `In NeonCodex, add a custom MCP server:\n\n  Name:   BrowserlessAPI\n  URL:    ${MCP_URL}\n  Header: Authorization: Bearer ${key}\n\n(or use the URL ${urlKey} if only a URL can be entered)`,
+        'url': () => urlKey,
+    };
+    if (!guides[client]) {
+        out(`Connect BrowserlessAPI to an AI app. Pick one:\n\n  browserlessapi mcp claude        claude.ai and Claude desktop\n  browserlessapi mcp claude-code   Claude Code\n  browserlessapi mcp chatgpt       ChatGPT\n  browserlessapi mcp cursor        Cursor\n  browserlessapi mcp vscode        VS Code (Copilot)\n  browserlessapi mcp codex         OpenAI Codex\n  browserlessapi mcp neoncodex     NeonCodex\n  browserlessapi mcp url           just the server URL\n\nAny other MCP client: ${MCP_URL} with "Authorization: Bearer YOUR_API_KEY",\nor ${MCP_URL}?api_key=YOUR_API_KEY. Add --no-key to print a placeholder instead of your key.`);
+        return;
+    }
+    out(guides[client]());
+    if (real) err('\nThis contains your API key. Do not commit it to a repository or share it.');
+}
+
+const HELP = `browserlessapi ${VERSION}: web scraping, screenshots, browser automation and captcha solving.
+
+Usage: browserlessapi <command> [options]
+
+Commands
+  auth [--api-key KEY]        Save your API key (checks it first). --show shows the saved key.
+  logout                      Remove the saved key.
+  account                     Plan, credits and features.
+  scrape <url>                Page as Markdown (default) or other formats.
+      -f, --format LIST         markdown,text,links,metadata,html (comma-separated)
+      --render auto|true|false  Use a browser: when needed (default), always, never
+      --captcha auto|always|off What to do when a captcha blocks the page (default auto)
+      --full                    Keep navigation, headers and footers in markdown/text
+      --engine NAME             puppeteer or playwright
+      --json                    Print the full API response
+      -o, --output-file FILE    Save instead of printing
+      --input-file FILE|-       Batch: one URL per line (- reads stdin)
+      --output-dir DIR          Batch output folder (default browserlessapi-<time>)
+      -c, --concurrency N       Batch: pages at once (default 3)
+  screenshot <url>            Save a PNG screenshot. -o FILE, --wait-for SELECTOR
+  steps <file|json|->         Run browser steps (BrowserQL). --output-dir for screenshots
+  captcha --task JSON         Solve a captcha (CapMonster task). --task-file FILE, --timeout SEC
+  mcp [client]                Setup for Claude, ChatGPT, Cursor, VS Code, Codex, NeonCodex
+
+Global
+  -k, --api-key KEY           Use this key (else BROWSERLESSAPI_API_KEY, else the saved key)
+  -h, --help                  This help
+  -v, --version               Version
+
+Examples
+  browserlessapi scrape https://example.com
+  browserlessapi scrape https://example.com -f markdown,links,metadata
+  browserlessapi scrape --input-file urls.txt --output-dir pages -c 5
+  browserlessapi screenshot https://example.com -o example.png
+  browserlessapi steps '[{"action":"goto","url":"https://example.com"},{"action":"extract","selector":"h1","as":"title"}]'
+  browserlessapi captcha --task '{"type":"RecaptchaV2Task","websiteURL":"https://site/page","websiteKey":"SITE_KEY"}'
+  browserlessapi mcp claude-code
+
+Each request uses credits from your account. Docs: ${BASE}/api-docs/`;
+
+async function main() {
+    const { pos, opt } = parseArgs(process.argv.slice(2));
+    if (opt.version) return out(VERSION);
+    const cmd = pos.shift();
+    if (!cmd || opt.help || cmd === 'help') return out(HELP);
+    switch (cmd) {
+        case 'auth': return cmdAuth(opt);
+        case 'logout': return cmdLogout();
+        case 'account': case 'usage': case 'credits': return cmdAccount(opt);
+        case 'scrape': return cmdScrape(pos, opt);
+        case 'screenshot': return cmdScreenshot(pos, opt);
+        case 'steps': return cmdSteps(pos, opt);
+        case 'captcha': return cmdCaptcha(opt);
+        case 'mcp': return cmdMcp(pos, opt);
+        default: throw new UsageError(`Unknown command "${cmd}". Run "browserlessapi --help".`);
+    }
+}
+
+main().catch((e) => {
+    if (e instanceof UsageError) { err('Error: ' + e.message); process.exit(2); }
+    if (e instanceof ApiError) { err('Error: ' + e.message); process.exit(1); }
+    err('Error: ' + (e && e.message ? e.message : String(e)));
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "browserlessapi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "BrowserlessAPI command-line tool: scrape any page to Markdown, take screenshots, run browser steps, solve captchas, and connect BrowserlessAPI to Claude, ChatGPT, Cursor and other AI apps over MCP.",
+  "bin": { "browserlessapi": "bin/browserlessapi.js" },
+  "files": ["bin/", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "keywords": ["web scraping", "scraper", "headless browser", "cloudflare", "captcha", "markdown", "mcp", "ai agents", "cli"],
+  "homepage": "https://browserlessapi.com/",
+  "author": "BrowserlessAPI (Nero Softwares & IT Services Pvt. Ltd.)",
+  "license": "MIT"
+}