bmad-plus 0.1.0

package/osint-agent-package/skills/bmad-osint-investigate/osint/scripts/_http.py

@@ -0,0 +1,101 @@
+"""Shared HTTP utilities for OSINT scripts — stdlib only, zero dependencies."""
+
+import http.client
+import json
+import os
+import ssl
+import sys
+from urllib.parse import urlparse, urlencode, quote
+
+
+def https_request(method, url, headers=None, body=None, timeout=120):
+    """Make an HTTPS request and return (status, headers, body_str).
+    
+    Handles both http and https URLs.
+    """
+    parsed = urlparse(url)
+    scheme = parsed.scheme or "https"
+    host = parsed.hostname
+    port = parsed.port or (443 if scheme == "https" else 80)
+    path = parsed.path or "/"
+    if parsed.query:
+        path += "?" + parsed.query
+
+    if scheme == "https":
+        ctx = ssl.create_default_context()
+        conn = http.client.HTTPSConnection(host, port, timeout=timeout, context=ctx)
+    else:
+        conn = http.client.HTTPConnection(host, port, timeout=timeout)
+
+    hdrs = {"User-Agent": "osint-skill/3.2-python"}
+    if headers:
+        hdrs.update(headers)
+
+    conn.request(method, path, body=body, headers=hdrs)
+    resp = conn.getresponse()
+    data = resp.read().decode("utf-8", errors="replace")
+    status = resp.status
+    resp_headers = dict(resp.getheaders())
+    conn.close()
+    return status, resp_headers, data
+
+
+def api_post(url, payload, headers=None, timeout=120):
+    """POST JSON payload and return parsed JSON response."""
+    hdrs = {"Content-Type": "application/json"}
+    if headers:
+        hdrs.update(headers)
+    body = json.dumps(payload) if isinstance(payload, dict) else payload
+    status, _, data = https_request("POST", url, headers=hdrs, body=body, timeout=timeout)
+    if status >= 400:
+        print(f"ERROR: HTTP {status}: {data[:300]}", file=sys.stderr)
+        return None
+    try:
+        return json.loads(data)
+    except json.JSONDecodeError:
+        print(f"ERROR: Invalid JSON response: {data[:300]}", file=sys.stderr)
+        return None
+
+
+def api_get(url, headers=None, timeout=120):
+    """GET request and return parsed JSON response."""
+    status, _, data = https_request("GET", url, headers=headers, timeout=timeout)
+    if status >= 400:
+        print(f"ERROR: HTTP {status}: {data[:300]}", file=sys.stderr)
+        return None
+    try:
+        return json.loads(data)
+    except json.JSONDecodeError:
+        # Return raw text if not JSON
+        return {"raw": data[:5000]}
+
+
+def get_key(env_var, file_fallback=None, required=True, help_url=""):
+    """Load API key from environment or fallback file."""
+    val = os.environ.get(env_var, "")
+    if val:
+        return val
+    if file_fallback and os.path.isfile(file_fallback):
+        with open(file_fallback, "r") as f:
+            return f.readline().strip()
+    if required:
+        print(f"ERROR: {env_var} not set.", file=sys.stderr)
+        if help_url:
+            print(f"Get one at: {help_url}", file=sys.stderr)
+        sys.exit(1)
+    return ""
+
+
+def get_workspace():
+    """Get workspace root (2 levels up from scripts dir)."""
+    scripts_dir = os.path.dirname(os.path.abspath(__file__))
+    skill_dir = os.path.dirname(scripts_dir)
+    workspace = os.path.dirname(os.path.dirname(skill_dir))
+    return workspace, skill_dir, scripts_dir
+
+
+def truncate(text, max_len=200):
+    """Truncate text with ellipsis."""
+    if not text:
+        return ""
+    return text[:max_len] + "..." if len(text) > max_len else text

package/osint-agent-package/skills/bmad-osint-investigate/osint/scripts/apify.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Apify API — universal actor runner + LinkedIn/Instagram shortcuts.
+
+Replaces: apify.sh, run-actor.sh, run_actor.js
+Stdlib only, zero dependencies.
+
+Usage:
+  python apify.py run <actor_id> '<json_input>' [--output file] [--format csv|json]
+  python apify.py linkedin <profile_url>
+  python apify.py instagram <username>
+  python apify.py results <run_id>
+  python apify.py status <run_id>
+  python apify.py store-search <query>
+"""
+
+import json
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _http import api_post, api_get, get_key, get_workspace
+
+BASE = "https://api.apify.com/v2"
+USER_AGENT = "osint-skill/3.2-python"
+
+
+def init():
+    workspace, _, _ = get_workspace()
+    token = os.environ.get("APIFY_TOKEN") or os.environ.get("APIFY_API_TOKEN")
+    if not token:
+        fallback = os.path.join(workspace, "scripts", "apify-api-token.txt")
+        if os.path.isfile(fallback):
+            with open(fallback) as f:
+                token = f.readline().strip()
+    if not token:
+        print("ERROR: No Apify token found.", file=sys.stderr)
+        print("Set APIFY_API_TOKEN env var, or put token in scripts/apify-api-token.txt", file=sys.stderr)
+        print("Get one at: https://console.apify.com/account/integrations", file=sys.stderr)
+        sys.exit(1)
+    return token
+
+
+def start_actor(token, actor_id, input_json):
+    """Start an Apify actor and return (run_id, dataset_id)."""
+    api_actor = actor_id.replace("/", "~")
+    url = f"{BASE}/acts/{api_actor}/runs?token={token}"
+    try:
+        input_data = json.loads(input_json) if isinstance(input_json, str) else input_json
+    except json.JSONDecodeError as e:
+        print(f"ERROR: Invalid JSON input: {e}", file=sys.stderr)
+        sys.exit(1)
+    data = api_post(url, input_data)
+    if not data:
+        sys.exit(1)
+    run_data = data.get("data", data)
+    return run_data.get("id"), run_data.get("defaultDatasetId")
+
+
+def poll_until_complete(token, run_id, timeout=600, interval=5):
+    """Poll actor run until complete. Returns final status."""
+    url = f"{BASE}/actor-runs/{run_id}?token={token}"
+    start_time = time.time()
+    last_status = None
+
+    while True:
+        data = api_get(url)
+        if not data:
+            print("ERROR: Failed to get run status", file=sys.stderr)
+            sys.exit(1)
+        status = data.get("data", data).get("status", "UNKNOWN")
+        if status != last_status:
+            print(f"Status: {status}")
+            last_status = status
+        if status in ("SUCCEEDED", "FAILED", "ABORTED", "TIMED-OUT"):
+            return status
+        elapsed = time.time() - start_time
+        if elapsed > timeout:
+            print(f"WARNING: Timeout after {timeout}s, actor still running")
+            return "TIMED-OUT"
+        time.sleep(interval)
+
+
+def download_results(token, dataset_id, output_path=None, fmt="json"):
+    """Download actor results. If no output_path, display top 5."""
+    url = f"{BASE}/datasets/{dataset_id}/items?token={token}&format=json"
+    data = api_get(url)
+    if not data:
+        return
+    items = data if isinstance(data, list) else [data]
+
+    if output_path:
+        if fmt == "json":
+            with open(output_path, "w", encoding="utf-8") as f:
+                json.dump(items, f, indent=2, ensure_ascii=False)
+        else:
+            # CSV
+            if items:
+                fields = list(items[0].keys())
+                lines = [",".join(fields)]
+                for row in items:
+                    vals = []
+                    for k in fields:
+                        v = row.get(k, "")
+                        if isinstance(v, str) and len(v) > 200:
+                            v = v[:200] + "..."
+                        elif isinstance(v, (list, dict)):
+                            v = json.dumps(v, ensure_ascii=False)
+                        if v is None:
+                            v = ""
+                        v = str(v)
+                        if "," in v or '"' in v or "\n" in v:
+                            v = f'"{v.replace(chr(34), chr(34)+chr(34))}"'
+                        vals.append(v)
+                    lines.append(",".join(vals))
+                with open(output_path, "w", encoding="utf-8") as f:
+                    f.write("\n".join(lines))
+        print(f"Saved to: {output_path}")
+        print(f"Records: {len(items)}")
+    else:
+        # Display top 5
+        total = len(items)
+        if total == 0:
+            print("\nNo results found.")
+            return
+        print(f"\n{'='*60}")
+        print(f"TOP 5 RESULTS (of {total} total)")
+        print("=" * 60)
+        for i, item in enumerate(items[:5]):
+            print(f"\n--- Result {i+1} ---")
+            for key, value in item.items():
+                display = value
+                if isinstance(value, str) and len(value) > 100:
+                    display = value[:100] + "..."
+                elif isinstance(value, (list, dict)):
+                    s = json.dumps(value, ensure_ascii=False)
+                    display = s[:100] + "..." if len(s) > 100 else s
+                print(f"  {key}: {display}")
+        print(f"\n{'='*60}")
+        if total > 5:
+            print(f"Showing 5 of {total} results.")
+        print(f"Full data: https://console.apify.com/storage/datasets/{dataset_id}")
+
+
+def run_actor(token, actor_id, input_json, output=None, fmt="json", timeout=600):
+    """Full pipeline: start → poll → download."""
+    print(f"Starting actor: {actor_id}")
+    run_id, dataset_id = start_actor(token, actor_id, input_json)
+    print(f"Run ID: {run_id}")
+    print(f"Dataset ID: {dataset_id}")
+    status = poll_until_complete(token, run_id, timeout=timeout)
+    if status != "SUCCEEDED":
+        print(f"ERROR: Actor run {status}", file=sys.stderr)
+        print(f"Details: https://console.apify.com/actors/runs/{run_id}", file=sys.stderr)
+        sys.exit(1)
+    download_results(token, dataset_id, output, fmt)
+
+
+def get_results(token, run_id):
+    """Get results from a completed run."""
+    data = api_get(f"{BASE}/actor-runs/{run_id}/dataset/items?token={token}")
+    if data:
+        print(json.dumps(data, indent=2, ensure_ascii=False)[:5000])
+
+
+def get_status(token, run_id):
+    """Check run status."""
+    data = api_get(f"{BASE}/actor-runs/{run_id}?token={token}")
+    if data:
+        print(json.dumps(data, indent=2, ensure_ascii=False)[:2000])
+
+
+def store_search(token, query):
+    """Search the Apify actor store."""
+    from urllib.parse import quote
+    data = api_get(f"{BASE}/store?token={token}&limit=10&search={quote(query)}")
+    if data:
+        items = data.get("data", {}).get("items", data if isinstance(data, list) else [])
+        for item in items[:10]:
+            print(f'📦 {item.get("title", item.get("name", ""))}')
+            print(f'   ID: {item.get("id", item.get("actorId", ""))}')
+            desc = item.get("description", "")[:150]
+            if desc:
+                print(f"   {desc}")
+            print()
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+    token = init()
+    cmd = sys.argv[1]
+
+    if cmd == "run":
+        if len(sys.argv) < 4:
+            print("Usage: apify.py run <actor_id> '<json_input>' [--output file] [--format csv|json]")
+            sys.exit(1)
+        actor_id = sys.argv[2]
+        input_json = sys.argv[3]
+        # Parse optional args
+        output = None
+        fmt = "json"
+        i = 4
+        while i < len(sys.argv):
+            if sys.argv[i] == "--output" and i + 1 < len(sys.argv):
+                output = sys.argv[i + 1]
+                i += 2
+            elif sys.argv[i] == "--format" and i + 1 < len(sys.argv):
+                fmt = sys.argv[i + 1]
+                i += 2
+            else:
+                i += 1
+        run_actor(token, actor_id, input_json, output, fmt)
+
+    elif cmd == "linkedin":
+        url = sys.argv[2] if len(sys.argv) > 2 else ""
+        if not url:
+            print("Usage: apify.py linkedin <profile_url>", file=sys.stderr)
+            sys.exit(1)
+        run_actor(token, "supreme_coder/linkedin-profile-scraper",
+                  json.dumps({"urls": [{"url": url}]}))
+
+    elif cmd == "instagram":
+        username = sys.argv[2] if len(sys.argv) > 2 else ""
+        if not username:
+            print("Usage: apify.py instagram <username>", file=sys.stderr)
+            sys.exit(1)
+        run_actor(token, "apify/instagram-profile-scraper",
+                  json.dumps({"usernames": [username]}))
+
+    elif cmd == "results":
+        run_id = sys.argv[2] if len(sys.argv) > 2 else ""
+        if not run_id:
+            print("Usage: apify.py results <run_id>", file=sys.stderr)
+            sys.exit(1)
+        get_results(token, run_id)
+
+    elif cmd == "status":
+        run_id = sys.argv[2] if len(sys.argv) > 2 else ""
+        if not run_id:
+            print("Usage: apify.py status <run_id>", file=sys.stderr)
+            sys.exit(1)
+        get_status(token, run_id)
+
+    elif cmd == "store-search":
+        query = " ".join(sys.argv[2:])
+        if not query:
+            print("Usage: apify.py store-search <query>", file=sys.stderr)
+            sys.exit(1)
+        store_search(token, query)
+
+    else:
+        print(f"Unknown command: {cmd}", file=sys.stderr)
+        print(__doc__)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/osint-agent-package/skills/bmad-osint-investigate/osint/scripts/brightdata.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Bright Data MCP wrapper — scrape, search, search-geo, search-yandex. Stdlib only.
+
+Uses mcp-client.py for MCP JSON-RPC calls.
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _http import get_key, get_workspace
+
+
+def init():
+    workspace, _, _ = get_workspace()
+    return get_key("BRIGHTDATA_MCP_URL",
+                   file_fallback=os.path.join(workspace, "scripts", "brightdata-mcp-url.txt"),
+                   help_url="https://brightdata.com/products/web-scraper/mcp")
+
+
+def mcp_call(mcp_url, tool_name, arguments):
+    """Call MCP tool via mcp-client.py."""
+    scripts_dir = os.path.dirname(os.path.abspath(__file__))
+    mcp_client = os.path.join(scripts_dir, "mcp-client.py")
+    args_json = json.dumps(arguments)
+    result = subprocess.run(
+        [sys.executable, mcp_client, mcp_url, tool_name, args_json],
+        capture_output=True, text=True, timeout=120
+    )
+    if result.stdout:
+        print(result.stdout)
+    if result.stderr:
+        print(result.stderr, file=sys.stderr)
+    return result.returncode
+
+
+def list_tools(mcp_url):
+    """List available MCP tools."""
+    scripts_dir = os.path.dirname(os.path.abspath(__file__))
+    mcp_client = os.path.join(scripts_dir, "mcp-client.py")
+    result = subprocess.run(
+        [sys.executable, mcp_client, mcp_url, "--list-tools"],
+        capture_output=True, text=True, timeout=30
+    )
+    if result.stdout:
+        print(result.stdout)
+    if result.stderr:
+        print(result.stderr, file=sys.stderr)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: brightdata.py {tools|scrape|scrape-batch|search|search-geo|search-yandex} <args>")
+        print()
+        print("  tools                     - list available MCP tools")
+        print("  scrape <url>              - any URL → markdown (bypasses CAPTCHA)")
+        print("  scrape-batch <url1> <url2> - batch scrape up to 10 URLs")
+        print("  search <query>            - Google search via Bright Data")
+        print("  search-geo <cc> <query>   - geo-targeted search")
+        print("  search-yandex <query>     - Yandex search")
+        sys.exit(1)
+
+    mcp_url = init()
+    cmd = sys.argv[1]
+
+    if cmd == "tools":
+        list_tools(mcp_url)
+    elif cmd == "scrape":
+        url = sys.argv[2] if len(sys.argv) > 2 else ""
+        if not url:
+            print("Usage: brightdata.py scrape <url>", file=sys.stderr)
+            sys.exit(1)
+        mcp_call(mcp_url, "scrape_as_markdown", {"url": url})
+    elif cmd == "scrape-batch":
+        urls = sys.argv[2:]
+        if not urls:
+            print("Usage: brightdata.py scrape-batch <url1> <url2>...", file=sys.stderr)
+            sys.exit(1)
+        mcp_call(mcp_url, "scrape_as_markdown_batch", {"urls": urls})
+    elif cmd == "search":
+        query = " ".join(sys.argv[2:])
+        mcp_call(mcp_url, "web_data_search_engine", {"query": query})
+    elif cmd == "search-geo":
+        if len(sys.argv) < 4:
+            print("Usage: brightdata.py search-geo <country_code> <query>", file=sys.stderr)
+            sys.exit(1)
+        geo = sys.argv[2]
+        query = " ".join(sys.argv[3:])
+        mcp_call(mcp_url, "web_data_search_engine", {"query": query, "country": geo})
+    elif cmd == "search-yandex":
+        query = " ".join(sys.argv[2:])
+        mcp_call(mcp_url, "web_data_search_engine", {"query": query, "engine": "yandex"})
+    else:
+        print(f"Unknown: {cmd}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/osint-agent-package/skills/bmad-osint-investigate/osint/scripts/diagnose.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""OSINT Toolkit Diagnostic — checks available API keys, CLI tools, and capabilities."""
+
+import os
+import shutil
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _http import get_workspace
+
+
+def check_key(env_var, file_path=None):
+    """Check if API key is available via env or file."""
+    if os.environ.get(env_var):
+        return True, f"(env)"
+    if file_path and os.path.isfile(file_path):
+        return True, f"(file: {os.path.basename(file_path)})"
+    return False, ""
+
+
+def main():
+    workspace, skill_dir, scripts_dir = get_workspace()
+
+    print("=== OSINT TOOLKIT DIAGNOSTIC ===")
+    print()
+
+    # 1. API Tokens
+    print("📡 API Tokens:")
+    keys = [
+        ("APIFY_API_TOKEN", os.path.join(workspace, "scripts", "apify-api-token.txt"),
+         "https://console.apify.com/account/integrations"),
+        ("JINA_API_KEY", os.path.join(workspace, "scripts", "jina-api-key.txt"),
+         "https://jina.ai/api-key"),
+        ("PERPLEXITY_API_KEY", None, "https://perplexity.ai/settings/api"),
+        ("PARALLEL_API_KEY", os.path.join(workspace, "scripts", "parallel-api-key.txt"),
+         "https://platform.parallel.ai"),
+        ("EXA_API_KEY", None, "https://dashboard.exa.ai"),
+        ("TAVILY_API_KEY", None, "https://app.tavily.com/home"),
+        ("BRIGHTDATA_MCP_URL", os.path.join(workspace, "scripts", "brightdata-mcp-url.txt"),
+         "https://brightdata.com/products/web-scraper/mcp"),
+    ]
+    for env_var, file_path, url in keys:
+        found, source = check_key(env_var, file_path)
+        if found:
+            print(f"  ✅ {env_var} {source}")
+        else:
+            print(f"  ❌ {env_var} — get one at {url}")
+    print()
+
+    # 2. CLI Tools
+    print("🔧 CLI Tools:")
+    tools = [
+        ("python3", "python"),
+        ("node", None),
+        ("jq", None),
+        ("curl", None),
+        ("git", None),
+    ]
+    for tool_name, alt_name in tools:
+        path = shutil.which(tool_name) or (shutil.which(alt_name) if alt_name else None)
+        if path:
+            print(f"  ✅ {tool_name}")
+        else:
+            print(f"  ❌ {tool_name}")
+
+    # Check run_actor.js
+    run_actor_js = os.path.join(scripts_dir, "run_actor.js")
+    if os.path.isfile(run_actor_js):
+        print(f"  ✅ run_actor.js (embedded, 55+ actors)")
+    else:
+        print(f"  ❌ run_actor.js (missing)")
+
+    # Check Python scripts
+    py_scripts = ["perplexity.py", "tavily.py", "exa.py", "jina.py",
+                  "parallel.py", "apify.py", "brightdata.py", "volley.py"]
+    for script in py_scripts:
+        path = os.path.join(scripts_dir, script)
+        if os.path.isfile(path):
+            print(f"  ✅ {script}")
+        else:
+            print(f"  ⚠️  {script} (not found)")
+    print()
+
+    # 3. Internal Intelligence
+    print("📱 Internal Intelligence:")
+    tg_path = os.path.join(workspace, "skills", "telegram", "scripts", "tg.py")
+    if os.path.isfile(tg_path):
+        print("  ✅ tg.py (Telegram history/search)")
+    else:
+        print("  ❌ tg.py (no Telegram access)")
+
+    himalaya = shutil.which("himalaya")
+    himalaya_local = os.path.expanduser("~/.local/bin/himalaya")
+    if himalaya or os.path.isfile(himalaya_local):
+        print("  ✅ himalaya (email search)")
+    else:
+        print("  ❌ himalaya (no email access)")
+
+    vault_crm = os.path.join(workspace, "vault", "crm")
+    if os.path.isdir(vault_crm):
+        count = sum(1 for f in os.listdir(vault_crm) if f.endswith(".md"))
+        print(f"  ✅ vault/crm ({count} cards)")
+    else:
+        print("  ❌ vault/crm (no CRM vault)")
+    print()
+
+    # 4. Capability Summary
+    print("📊 Capabilities:")
+    apify_ok = check_key("APIFY_API_TOKEN", os.path.join(workspace, "scripts", "apify-api-token.txt"))[0]
+    bright_ok = check_key("BRIGHTDATA_MCP_URL", os.path.join(workspace, "scripts", "brightdata-mcp-url.txt"))[0]
+    jina_ok = check_key("JINA_API_KEY", os.path.join(workspace, "scripts", "jina-api-key.txt"))[0]
+    perp_ok = check_key("PERPLEXITY_API_KEY")[0]
+    tavily_ok = check_key("TAVILY_API_KEY")[0]
+    exa_ok = check_key("EXA_API_KEY")[0]
+    parallel_ok = check_key("PARALLEL_API_KEY", os.path.join(workspace, "scripts", "parallel-api-key.txt"))[0]
+
+    caps = [
+        (apify_ok, "LinkedIn scraping (Apify)"),
+        (apify_ok, "Instagram scraping (Apify)"),
+        (apify_ok, "TikTok scraping (Apify)"),
+        (apify_ok, "YouTube scraping (Apify)"),
+        (apify_ok, "Contact enrichment (Apify)"),
+        (apify_ok, "Google Maps (Apify)"),
+        (bright_ok, "Facebook scraping (Bright Data)"),
+        (bright_ok, "CAPTCHA bypass (Bright Data)"),
+        (jina_ok, "Deep search (Jina)"),
+        (perp_ok, "Quick answers (Perplexity Sonar)"),
+        (perp_ok, "Deep research (Perplexity Deep)"),
+        (tavily_ok, "Agent search (Tavily)"),
+        (exa_ok, "Semantic search (Exa)"),
+        (exa_ok, "People/Company search (Exa)"),
+        (parallel_ok, "AI search (Parallel)"),
+    ]
+    for available, name in caps:
+        print(f"  {'✅' if available else '❌'} {name}")
+    print()
+    print("=== END DIAGNOSTIC ===")
+
+
+if __name__ == "__main__":
+    main()

package/osint-agent-package/skills/bmad-osint-investigate/osint/scripts/exa.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Exa AI — semantic search, company research, people search, crawl. Stdlib only."""
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _http import api_post, get_key, truncate
+
+BASE = "https://api.exa.ai"
+
+
+def init():
+    return get_key("EXA_API_KEY", help_url="https://dashboard.exa.ai")
+
+
+def search(api_key, query, category=None, max_chars=500, icon="🔗"):
+    """Exa semantic search."""
+    payload = {
+        "query": query,
+        "type": "auto",
+        "numResults": 10,
+        "contents": {"text": {"maxCharacters": max_chars}},
+    }
+    if category:
+        payload["category"] = category
+    data = api_post(f"{BASE}/search", payload,
+                     headers={"x-api-key": api_key})
+    if not data:
+        return
+    for r in data.get("results", [])[:10]:
+        print(f'{icon} {r.get("title", "")}')
+        print(f'   {r.get("url", "")}')
+        txt = truncate(r.get("text", ""), max_chars)
+        if txt:
+            print(f"   {txt}")
+        print()
+
+
+def crawl(api_key, url):
+    """Crawl a URL and extract content."""
+    data = api_post(f"{BASE}/contents",
+                     {"urls": [url], "text": {"maxCharacters": 5000}},
+                     headers={"x-api-key": api_key})
+    if not data:
+        return
+    for r in data.get("results", []):
+        print(f'📄 {r.get("title", "")}')
+        print(f'   {r.get("url", "")}')
+        print(r.get("text", "")[:3000])
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: exa.py search|company|people|crawl|deep <query>")
+        sys.exit(1)
+    api_key = init()
+    cmd = sys.argv[1]
+    query = " ".join(sys.argv[2:])
+    if cmd == "search":
+        search(api_key, query)
+    elif cmd == "company":
+        search(api_key, f"{query} company information about",
+               category="company", max_chars=1000, icon="🏢")
+    elif cmd == "people":
+        search(api_key, query, category="personal site", icon="👤")
+    elif cmd == "crawl":
+        crawl(api_key, query)
+    elif cmd == "deep":
+        print("🔬 Exa Deep Research — use MCP or dashboard")
+        print("   MCP: https://mcp.exa.ai/mcp?tools=deep_researcher_start,deep_researcher_check")
+    else:
+        print(f"Unknown: {cmd} (use search|company|people|crawl|deep)", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()