tavily-cli 0.1.0__py3-none-any.whl

tavily_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Tavily CLI — search, extract, crawl, map, and research from the command line."""
+
+__version__ = "0.1.0"

tavily_cli/cli.py

@@ -0,0 +1,161 @@
+"""Main CLI entry point — wires all commands into the `tvly` group."""
+
+from __future__ import annotations
+
+import click
+
+from tavily_cli import __version__
+from tavily_cli.commands.auth import auth_status, login, logout
+from tavily_cli.commands.crawl import crawl
+from tavily_cli.commands.extract import extract
+from tavily_cli.commands.map_cmd import map_urls
+from tavily_cli.commands.research import research
+from tavily_cli.commands.search import search
+
+
+@click.group(invoke_without_command=True)
+@click.option("--version", is_flag=True, default=False, help="Show version and exit.")
+@click.option("--status", "show_status", is_flag=True, default=False, help="Show version and auth status.")
+@click.option("--json", "json_output", is_flag=True, default=False, help="Output as JSON (for agents and scripts).")
+@click.pass_context
+def cli(ctx: click.Context, version: bool, show_status: bool, json_output: bool) -> None:
+    """Tavily CLI — search, extract, crawl, map, and research from the command line.
+
+    Authenticate with: tvly login --api-key tvly-YOUR_KEY
+    Or set TAVILY_API_KEY environment variable.
+    """
+    import sys
+
+    ctx.ensure_object(dict)
+    # Auto-enable JSON when stdout is piped (e.g. by Claude Code, scripts, jq)
+    if not json_output and not sys.stdout.isatty():
+        json_output = True
+    ctx.obj["json_output"] = json_output
+
+    if version:
+        if json_output:
+            import json
+            click.echo(json.dumps({"version": __version__}))
+        else:
+            click.echo(f"tavily-cli {__version__}")
+        ctx.exit(0)
+        return
+
+    if show_status:
+        _print_status(json_output)
+        ctx.exit(0)
+        return
+
+    if ctx.invoked_subcommand is None:
+        from tavily_cli.repl import run_repl
+        run_repl()
+        ctx.exit(0)
+
+
+def _print_welcome() -> None:
+    """Show a branded welcome screen with quick-start hints."""
+    from rich.console import Console
+    from rich.text import Text
+
+    from tavily_cli.config import get_api_key
+    from tavily_cli.theme import LOGO
+
+    console = Console(stderr=True)
+    key = get_api_key()
+
+    # Logo + version
+    console.print()
+    console.print(LOGO)
+    console.print(f"  [dim]v{__version__}[/dim]")
+    console.print()
+
+    # Auth status
+    if key:
+        source = _auth_source(key)
+        console.print(f"  [#9BC0AE]>[/#9BC0AE] Authenticated via {source}")
+    else:
+        console.print(f"  [#FAA2FB]>[/#FAA2FB] Not authenticated")
+        console.print(f"    [dim]Run:[/dim] tvly login")
+
+    console.print()
+
+    # Quick-start commands
+    commands = Text()
+    commands.append("  Commands\n\n", style="bold")
+    commands.append("    tvly search ", style="#9BC0AE")
+    commands.append('"your query"', style="dim")
+    commands.append("            Web search\n")
+    commands.append("    tvly extract ", style="#9BC0AE")
+    commands.append("<url>", style="dim")
+    commands.append("                  Extract content\n")
+    commands.append("    tvly crawl ", style="#9BC0AE")
+    commands.append("<url>", style="dim")
+    commands.append("                    Crawl a website\n")
+    commands.append("    tvly map ", style="#9BC0AE")
+    commands.append("<url>", style="dim")
+    commands.append("                      Discover URLs\n")
+    commands.append("    tvly research ", style="#9BC0AE")
+    commands.append('"your query"', style="dim")
+    commands.append("          Deep research\n")
+
+    console.print(commands)
+    console.print("  [dim]Add --json to any command for machine-readable output.[/dim]")
+    console.print("  [dim]Add --help to any command for full options.[/dim]")
+    console.print()
+
+
+def _auth_source(key: str) -> str:
+    """Describe how the user is authenticated."""
+    import os
+    from tavily_cli.config import is_oauth_token
+
+    if os.environ.get("TAVILY_API_KEY"):
+        return "TAVILY_API_KEY"
+    if is_oauth_token(key):
+        return "OAuth (tvly login)"
+    return "API key"
+
+
+def _print_status(json_output: bool) -> None:
+    """Show version + auth status."""
+    import json
+
+    from tavily_cli.config import get_api_key
+
+    key = get_api_key()
+    authenticated = key is not None
+
+    if json_output:
+        click.echo(json.dumps({
+            "version": __version__,
+            "authenticated": authenticated,
+        }))
+    else:
+        from rich.console import Console
+        console = Console()
+        console.print(f"  [bold #9BC0AE]tavily[/bold #9BC0AE] v{__version__}")
+        console.print()
+        if authenticated:
+            source = _auth_source(key)
+            console.print(f"  [#9BC0AE]>[/#9BC0AE] Authenticated via {source}")
+        else:
+            console.print("  [#FAA2FB]>[/#FAA2FB] Not authenticated")
+            console.print("    Run: tvly login")
+
+
+cli.add_command(login)
+cli.add_command(logout)
+cli.add_command(auth_status)
+cli.add_command(search)
+cli.add_command(extract)
+cli.add_command(crawl)
+cli.add_command(map_urls)
+cli.add_command(research)
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

tavily_cli/commands/auth.py

@@ -0,0 +1,174 @@
+"""Authentication commands: login, logout, auth status."""
+
+from __future__ import annotations
+
+import click
+
+from tavily_cli.config import (
+    CONFIG_FILE,
+    MCP_AUTH_DIR,
+    clear_credentials,
+    get_api_key,
+    save_api_key,
+)
+
+
+def _clear_stale_mcp_state() -> None:
+    """Remove stale mcp-remote client registrations so OAuth can re-register fresh."""
+    if not MCP_AUTH_DIR.is_dir():
+        return
+    for client_file in MCP_AUTH_DIR.rglob("*_client_info.json"):
+        try:
+            client_file.unlink()
+        except OSError:
+            pass
+    for token_file in MCP_AUTH_DIR.rglob("*_tokens.json"):
+        try:
+            token_file.unlink()
+        except OSError:
+            pass
+
+
+@click.command()
+@click.option("--api-key", default=None, help="Tavily API key (tvly-...). If omitted, opens browser for OAuth.")
+def login(api_key: str | None) -> None:
+    """Authenticate with Tavily. Stores credentials for future use."""
+    from tavily_cli.theme import console, err_console
+
+    if api_key:
+        save_api_key(api_key)
+        _print_login_success("API key", f"Saved to {CONFIG_FILE}")
+        return
+
+    # OAuth flow via mcp-remote
+    import subprocess
+    import time
+
+    from tavily_cli.config import _get_mcp_token
+
+    # Clear stale client registrations that cause "client ID not found" errors
+    _clear_stale_mcp_state()
+
+    token = None
+    with err_console.status("[#5CD9E6]Waiting for browser authentication...[/#5CD9E6]", spinner="dots") as live:
+        proc = subprocess.Popen(
+            ["npx", "-y", "mcp-remote", "https://mcp.tavily.com/mcp"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+        timeout = 120
+        elapsed = 0
+        try:
+            while elapsed < timeout:
+                time.sleep(3)
+                elapsed += 3
+                live.update(f"[#5CD9E6]Waiting for browser authentication... {elapsed}s[/#5CD9E6]")
+                token = _get_mcp_token()
+                if token:
+                    break
+        finally:
+            proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+
+    if token:
+        _print_login_success("OAuth", "Token stored in ~/.mcp-auth/")
+    else:
+        err_console.print()
+        err_console.print("  [#FAA2FB]> Authentication timed out.[/#FAA2FB]")
+        err_console.print()
+        err_console.print("  If you don't have an account, sign up at [link=https://tavily.com]tavily.com[/link]")
+        err_console.print("  Or use an API key:")
+        err_console.print("    [#9BC0AE]tvly login --api-key tvly-YOUR_KEY[/#9BC0AE]")
+        err_console.print()
+        raise SystemExit(3)
+
+
+def _print_login_success(method: str, detail: str) -> None:
+    """Print a branded success screen after login."""
+    from rich.text import Text
+
+    from tavily_cli.theme import LOGO, console
+
+    console.print()
+    console.print(LOGO)
+    console.print()
+    console.print(f"  [#9BC0AE]> Authenticated via {method}[/#9BC0AE]")
+    console.print(f"    [dim]{detail}[/dim]")
+    console.print()
+
+    hints = Text()
+    hints.append("  Get started\n\n", style="bold")
+    hints.append("    tvly search ", style="#9BC0AE")
+    hints.append('"your first query"', style="dim")
+    hints.append("\n")
+    hints.append("    tvly extract ", style="#9BC0AE")
+    hints.append("<url>", style="dim")
+    hints.append("\n")
+    hints.append("    tvly crawl ", style="#9BC0AE")
+    hints.append("<url>", style="dim")
+    hints.append("\n")
+    hints.append("    tvly map ", style="#9BC0AE")
+    hints.append("<url>", style="dim")
+    hints.append("\n")
+    hints.append("    tvly research ", style="#9BC0AE")
+    hints.append('"deep dive topic"', style="dim")
+    hints.append("\n")
+    console.print(hints)
+
+
+@click.command()
+def logout() -> None:
+    """Clear stored Tavily credentials."""
+    from tavily_cli.theme import err_console
+
+    clear_credentials()
+    err_console.print("  [dim]Credentials cleared.[/dim]")
+    err_console.print("  Run [#9BC0AE]tvly login[/#9BC0AE] to authenticate again.")
+
+
+@click.command("auth")
+@click.option("--json", "json_flag", is_flag=True, default=False, help="Output as JSON.")
+@click.pass_context
+def auth_status(ctx: click.Context, json_flag: bool) -> None:
+    """Check authentication status."""
+    import json as json_mod
+    import os
+
+    from tavily_cli.config import is_oauth_token
+    from tavily_cli.theme import console
+
+    json_mode = json_flag
+    if not json_mode and ctx.parent and ctx.parent.obj:
+        json_mode = ctx.parent.obj.get("json_output", False)
+
+    key = get_api_key()
+    source = None
+    if key:
+        if os.environ.get("TAVILY_API_KEY"):
+            source = "TAVILY_API_KEY environment variable"
+        elif is_oauth_token(key):
+            source = "OAuth (~/.mcp-auth/)"
+        elif CONFIG_FILE.exists():
+            source = f"config file ({CONFIG_FILE})"
+
+    if json_mode:
+        click.echo(json_mod.dumps({
+            "authenticated": key is not None,
+            "source": source,
+        }))
+    else:
+        console.print()
+        if key:
+            masked = key[:8] + "..." + key[-4:] if len(key) > 12 else "***"
+            console.print(f"  [#9BC0AE]>[/#9BC0AE] Authenticated via {source}")
+            console.print(f"    [dim]Key: {masked}[/dim]")
+        else:
+            console.print(f"  [#FAA2FB]>[/#FAA2FB] Not authenticated")
+            console.print()
+            console.print("  Run [#9BC0AE]tvly login[/#9BC0AE] to authenticate.")
+        console.print()

tavily_cli/commands/crawl.py

@@ -0,0 +1,96 @@
+"""tavily crawl — crawl a website via the Tavily API."""
+
+from __future__ import annotations
+
+import click
+
+from tavily_cli.common import handle_api_error, json_option
+
+
+@click.command()
+@click.argument("url")
+@click.option("--max-depth", type=int, default=None, help="Levels deep to crawl (1-5, default: 1).")
+@click.option("--max-breadth", type=int, default=None, help="Links per page (default: 20).")
+@click.option("--limit", type=int, default=None, help="Total pages cap (default: 50).")
+@click.option("--instructions", default=None, help="Natural language guidance for the crawler.")
+@click.option("--chunks-per-source", type=int, default=None, help="Chunks per page (1-5, requires --instructions).")
+@click.option("--extract-depth", type=click.Choice(["basic", "advanced"]), default=None, help="Extraction depth.")
+@click.option("--format", "fmt", type=click.Choice(["markdown", "text"]), default=None, help="Output format.")
+@click.option("--select-paths", default=None, help="Comma-separated regex patterns for paths to include.")
+@click.option("--exclude-paths", default=None, help="Comma-separated regex patterns for paths to exclude.")
+@click.option("--select-domains", default=None, help="Comma-separated regex patterns for domains to include.")
+@click.option("--exclude-domains", default=None, help="Comma-separated regex patterns for domains to exclude.")
+@click.option("--allow-external/--no-external", default=None, help="Include external domain links.")
+@click.option("--include-images", is_flag=True, default=False, help="Include images.")
+@click.option("--timeout", type=float, default=None, help="Max wait time in seconds (10-150).")
+@click.option("--output", "-o", "output_file", default=None, help="Save JSON output to file.")
+@click.option("--output-dir", default=None, help="Save each page as a .md file in this directory.")
+@json_option
+def crawl(
+    url: str,
+    max_depth: int | None,
+    max_breadth: int | None,
+    limit: int | None,
+    instructions: str | None,
+    chunks_per_source: int | None,
+    extract_depth: str | None,
+    fmt: str | None,
+    select_paths: str | None,
+    exclude_paths: str | None,
+    select_domains: str | None,
+    exclude_domains: str | None,
+    allow_external: bool | None,
+    include_images: bool,
+    timeout: float | None,
+    output_file: str | None,
+    output_dir: str | None,
+    json_output: bool,
+) -> None:
+    """Crawl a website starting from URL.
+
+    Returns full content for each discovered page.
+    """
+    from tavily_cli.config import get_client
+    from tavily_cli.output import print_crawl_results
+
+    client = get_client()
+
+    kwargs: dict = {"url": url}
+    if max_depth is not None:
+        kwargs["max_depth"] = max_depth
+    if max_breadth is not None:
+        kwargs["max_breadth"] = max_breadth
+    if limit is not None:
+        kwargs["limit"] = limit
+    if instructions is not None:
+        kwargs["instructions"] = instructions
+    if chunks_per_source is not None:
+        kwargs["chunks_per_source"] = chunks_per_source
+    if extract_depth is not None:
+        kwargs["extract_depth"] = extract_depth
+    if fmt is not None:
+        kwargs["format"] = fmt
+    if select_paths:
+        kwargs["select_paths"] = [p.strip() for p in select_paths.split(",")]
+    if exclude_paths:
+        kwargs["exclude_paths"] = [p.strip() for p in exclude_paths.split(",")]
+    if select_domains:
+        kwargs["select_domains"] = [d.strip() for d in select_domains.split(",")]
+    if exclude_domains:
+        kwargs["exclude_domains"] = [d.strip() for d in exclude_domains.split(",")]
+    if allow_external is not None:
+        kwargs["allow_external"] = allow_external
+    if include_images:
+        kwargs["include_images"] = True
+    if timeout is not None:
+        kwargs["timeout"] = timeout
+
+    from tavily_cli.theme import spinner
+
+    try:
+        with spinner(f"Crawling {url}...", json_mode=json_output):
+            response = client.crawl(**kwargs)
+    except Exception as e:
+        handle_api_error(e, json_output)
+
+    print_crawl_results(response, json_mode=json_output, output_file=output_file, output_dir=output_dir)

tavily_cli/commands/extract.py

@@ -0,0 +1,66 @@
+"""tavily extract — extract content from URLs via the Tavily API."""
+
+from __future__ import annotations
+
+import click
+
+from tavily_cli.common import handle_api_error, json_option
+
+
+@click.command()
+@click.argument("urls", nargs=-1, required=True)
+@click.option("--query", default=None, help="Rerank chunks by relevance to this query.")
+@click.option("--chunks-per-source", type=int, default=None, help="Chunks per source (1-5, requires --query).")
+@click.option("--extract-depth", type=click.Choice(["basic", "advanced"]), default=None, help="Extraction depth.")
+@click.option("--format", "fmt", type=click.Choice(["markdown", "text"]), default=None, help="Output format.")
+@click.option("--include-images", is_flag=True, default=False, help="Include image URLs.")
+@click.option("--timeout", type=float, default=None, help="Max wait time in seconds (1-60).")
+@click.option("--output", "-o", "output_file", default=None, help="Save output to file.")
+@json_option
+def extract(
+    urls: tuple[str, ...],
+    query: str | None,
+    chunks_per_source: int | None,
+    extract_depth: str | None,
+    fmt: str | None,
+    include_images: bool,
+    timeout: float | None,
+    output_file: str | None,
+    json_output: bool,
+) -> None:
+    """Extract content from one or more URLs.
+
+    Provide URLs as positional arguments (max 20).
+    """
+    from tavily_cli.config import get_client
+    from tavily_cli.output import print_extract_results
+
+    client = get_client()
+
+    url_list = list(urls)
+    if len(url_list) > 20:
+        raise click.UsageError("Maximum 20 URLs per request.")
+
+    kwargs: dict = {"urls": url_list}
+    if query is not None:
+        kwargs["query"] = query
+    if chunks_per_source is not None:
+        kwargs["chunks_per_source"] = chunks_per_source
+    if extract_depth is not None:
+        kwargs["extract_depth"] = extract_depth
+    if fmt is not None:
+        kwargs["format"] = fmt
+    if include_images:
+        kwargs["include_images"] = True
+    if timeout is not None:
+        kwargs["timeout"] = timeout
+
+    from tavily_cli.theme import spinner
+
+    try:
+        with spinner(f"Extracting {len(url_list)} URL{'s' if len(url_list) > 1 else ''}...", json_mode=json_output):
+            response = client.extract(**kwargs)
+    except Exception as e:
+        handle_api_error(e, json_output)
+
+    print_extract_results(response, json_mode=json_output, output_file=output_file)

tavily_cli/commands/map_cmd.py

@@ -0,0 +1,78 @@
+"""tavily map — discover URLs on a website via the Tavily API."""
+
+from __future__ import annotations
+
+import click
+
+from tavily_cli.common import handle_api_error, json_option
+
+
+@click.command("map")
+@click.argument("url")
+@click.option("--max-depth", type=int, default=None, help="Levels deep to map (1-5, default: 1).")
+@click.option("--max-breadth", type=int, default=None, help="Links per page (default: 20).")
+@click.option("--limit", type=int, default=None, help="Maximum URLs to discover (default: 50).")
+@click.option("--instructions", default=None, help="Natural language guidance for URL discovery.")
+@click.option("--select-paths", default=None, help="Comma-separated regex patterns for paths to include.")
+@click.option("--exclude-paths", default=None, help="Comma-separated regex patterns for paths to exclude.")
+@click.option("--select-domains", default=None, help="Comma-separated regex patterns for domains to include.")
+@click.option("--exclude-domains", default=None, help="Comma-separated regex patterns for domains to exclude.")
+@click.option("--allow-external/--no-external", default=None, help="Include external domain links.")
+@click.option("--timeout", type=float, default=None, help="Max wait time in seconds (10-150).")
+@click.option("--output", "-o", "output_file", default=None, help="Save output to file.")
+@json_option
+def map_urls(
+    url: str,
+    max_depth: int | None,
+    max_breadth: int | None,
+    limit: int | None,
+    instructions: str | None,
+    select_paths: str | None,
+    exclude_paths: str | None,
+    select_domains: str | None,
+    exclude_domains: str | None,
+    allow_external: bool | None,
+    timeout: float | None,
+    output_file: str | None,
+    json_output: bool,
+) -> None:
+    """Discover all URLs on a website (no content extraction).
+
+    Returns a list of URLs found starting from the given URL.
+    """
+    from tavily_cli.config import get_client
+    from tavily_cli.output import print_map_results
+
+    client = get_client()
+
+    kwargs: dict = {"url": url}
+    if max_depth is not None:
+        kwargs["max_depth"] = max_depth
+    if max_breadth is not None:
+        kwargs["max_breadth"] = max_breadth
+    if limit is not None:
+        kwargs["limit"] = limit
+    if instructions is not None:
+        kwargs["instructions"] = instructions
+    if select_paths:
+        kwargs["select_paths"] = [p.strip() for p in select_paths.split(",")]
+    if exclude_paths:
+        kwargs["exclude_paths"] = [p.strip() for p in exclude_paths.split(",")]
+    if select_domains:
+        kwargs["select_domains"] = [d.strip() for d in select_domains.split(",")]
+    if exclude_domains:
+        kwargs["exclude_domains"] = [d.strip() for d in exclude_domains.split(",")]
+    if allow_external is not None:
+        kwargs["allow_external"] = allow_external
+    if timeout is not None:
+        kwargs["timeout"] = timeout
+
+    from tavily_cli.theme import spinner
+
+    try:
+        with spinner(f"Mapping {url}...", json_mode=json_output):
+            response = client.map(**kwargs)
+    except Exception as e:
+        handle_api_error(e, json_output)
+
+    print_map_results(response, json_mode=json_output, output_file=output_file)