semanticapi-cli 0.1.0__py3-none-any.whl

semanticapi_cli/__init__.py

@@ -0,0 +1,12 @@
+"""
+Semantic API CLI
+================
+
+A command-line interface for Semantic API - discover and query APIs with natural language.
+
+Usage:
+    python -m semanticapi_cli query "send an SMS"
+    semanticapi query "send an SMS" --key sapi_your_key
+"""
+
+__version__ = "0.1.0"

semanticapi_cli/__main__.py

@@ -0,0 +1,9 @@
+"""
+Entry point for python -m semanticapi_cli
+"""
+
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

semanticapi_cli/api.py

@@ -0,0 +1,129 @@
+"""
+API client for Semantic API CLI.
+
+Uses stdlib urllib only - no external dependencies.
+"""
+
+import json
+import urllib.request
+import urllib.error
+import urllib.parse
+from typing import Optional, Dict, Any, Tuple
+
+
+class APIError(Exception):
+    """Error from Semantic API."""
+    def __init__(self, message: str, status_code: int = 0, details: Optional[Dict] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.details = details or {}
+
+
+class APIClient:
+    """HTTP client for Semantic API."""
+    
+    def __init__(self, base_url: str, api_key: Optional[str] = None):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+    
+    def _request(
+        self, 
+        method: str, 
+        path: str, 
+        data: Optional[Dict] = None,
+        timeout: int = 60,
+    ) -> Tuple[int, Dict[str, Any]]:
+        """
+        Make HTTP request to API.
+        
+        Returns (status_code, response_json).
+        Raises APIError on failure.
+        """
+        url = f"{self.base_url}{path}"
+        
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "semanticapi-cli/0.1.0",
+        }
+        
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        
+        body = json.dumps(data).encode("utf-8") if data else None
+        
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+        
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as response:
+                response_body = response.read().decode("utf-8")
+                try:
+                    return response.status, json.loads(response_body)
+                except json.JSONDecodeError:
+                    return response.status, {"raw": response_body}
+                    
+        except urllib.error.HTTPError as e:
+            body = e.read().decode("utf-8") if e.fp else ""
+            try:
+                error_data = json.loads(body)
+                detail = error_data.get("detail", str(e))
+            except json.JSONDecodeError:
+                detail = body or str(e)
+            
+            raise APIError(detail, status_code=e.code, details={"body": body})
+            
+        except urllib.error.URLError as e:
+            raise APIError(f"Connection failed: {e.reason}")
+        except TimeoutError:
+            raise APIError("Request timed out")
+    
+    def query(self, query: str, auto_discover: bool = True) -> Dict[str, Any]:
+        """Execute a natural language query."""
+        status, data = self._request("POST", "/api/query", {
+            "query": query,
+            "auto_discover": auto_discover,
+        })
+        return data
+    
+    def query_batch(self, queries: list) -> Dict[str, Any]:
+        """Execute multiple queries in one call."""
+        status, data = self._request("POST", "/api/query/batch", {
+            "queries": queries,
+        })
+        return data
+    
+    def preflight(self, query: str) -> Dict[str, Any]:
+        """Pre-analyze a query to identify needed providers."""
+        status, data = self._request("POST", "/api/query/preflight", {
+            "query": query,
+        })
+        return data
+    
+    def agentic(self, query: str, execution_id: Optional[str] = None) -> Dict[str, Any]:
+        """Execute a query with agentic (execution) mode."""
+        payload = {"query": query}
+        if execution_id:
+            payload["execution_id"] = execution_id
+        status, data = self._request("POST", "/api/query/agentic", payload, timeout=120)
+        return data
+    
+    def discover(self, provider_name: str, user_intent: Optional[str] = None) -> Dict[str, Any]:
+        """Discover a provider by name."""
+        payload = {"provider_name": provider_name}
+        if user_intent:
+            payload["user_intent"] = user_intent
+        status, data = self._request("POST", "/api/discover/search", payload, timeout=60)
+        return data
+    
+    def discover_url(self, url: str, user_intent: Optional[str] = None) -> Dict[str, Any]:
+        """Discover a provider from documentation URL."""
+        payload = {"url": url}
+        if user_intent:
+            payload["user_intent"] = user_intent
+        status, data = self._request("POST", "/api/discover/from-url", payload, timeout=60)
+        return data
+    
+    def health(self) -> Dict[str, Any]:
+        """Get API health status."""
+        status, data = self._request("GET", "/api/health")
+        return data

semanticapi_cli/cli.py

@@ -0,0 +1,476 @@
+#!/usr/bin/env python3
+"""
+Semantic API CLI - Query APIs with natural language from your terminal.
+
+Usage:
+    semanticapi query "send an SMS"
+    semanticapi query "send an SMS" --key sapi_your_key
+    semanticapi query "send an SMS" --execute
+    semanticapi batch "send SMS" "process payment" "get weather"
+    semanticapi preflight "send an SMS"
+    semanticapi discover "twilio"
+    semanticapi discover-url "https://docs.stripe.com/api"
+    semanticapi config set-key sapi_your_key
+    semanticapi status
+"""
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .config import (
+    get_api_key, 
+    get_base_url, 
+    set_api_key, 
+    set_base_url, 
+    load_config,
+    clear_config,
+    CONFIG_FILE,
+)
+from .api import APIClient, APIError
+from .output import (
+    print_error,
+    print_result,
+    format_query_result,
+    format_preflight_result,
+    format_discover_result,
+    format_status_result,
+    format_agentic_result,
+    success,
+    warning,
+    dim,
+)
+
+
+# Exit codes
+EXIT_SUCCESS = 0
+EXIT_ERROR = 1
+EXIT_AUTH_REQUIRED = 2
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser with all subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="semanticapi",
+        description="Semantic API CLI - Query APIs with natural language",
+        epilog="Examples:\n"
+               "  semanticapi query \"send an SMS via twilio\"\n"
+               "  semanticapi preflight \"send an email\"\n"
+               "  semanticapi discover sendgrid\n"
+               "  semanticapi config set-key sapi_your_key",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    
+    parser.add_argument(
+        "--version", "-v",
+        action="version",
+        version=f"semanticapi-cli {__version__}",
+    )
+    
+    # Global options
+    parser.add_argument(
+        "--key", "-k",
+        metavar="KEY",
+        help="API key (overrides SEMANTICAPI_KEY env var and config file)",
+    )
+    parser.add_argument(
+        "--url", "-u",
+        metavar="URL",
+        help="Base URL (default: https://semanticapi.dev)",
+    )
+    parser.add_argument(
+        "--raw", "-r",
+        action="store_true",
+        help="Output compact JSON (no formatting)",
+    )
+    parser.add_argument(
+        "--quiet", "-q",
+        action="store_true",
+        help="Output minimal information",
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    
+    # ── query command ──────────────────────────────────────
+    query_parser = subparsers.add_parser(
+        "query",
+        help="Execute a natural language query",
+        description="Execute a natural language query against connected APIs.",
+    )
+    query_parser.add_argument(
+        "query",
+        help="Natural language query (e.g., 'send an SMS')",
+    )
+    query_parser.add_argument(
+        "--execute", "-x",
+        action="store_true",
+        help="Use agentic mode (actually execute API calls)",
+    )
+    query_parser.add_argument(
+        "--no-discover",
+        action="store_true",
+        help="Disable auto-discovery of unknown providers",
+    )
+    
+    # ── batch command ──────────────────────────────────────
+    batch_parser = subparsers.add_parser(
+        "batch",
+        help="Execute multiple queries at once",
+        description="Execute multiple queries in a single API call (max 10).",
+    )
+    batch_parser.add_argument(
+        "queries",
+        nargs="+",
+        help="Queries to execute",
+    )
+    
+    # ── preflight command ──────────────────────────────────
+    preflight_parser = subparsers.add_parser(
+        "preflight",
+        help="Pre-check a query (free, no LLM cost)",
+        description="Pre-analyze a query to identify required providers and their status.",
+    )
+    preflight_parser.add_argument(
+        "query",
+        help="Query to analyze",
+    )
+    
+    # ── discover command ──────────────────────────────────
+    discover_parser = subparsers.add_parser(
+        "discover",
+        help="Discover a provider by name",
+        description="Search for and auto-discover a provider configuration by name.",
+    )
+    discover_parser.add_argument(
+        "provider",
+        help="Provider name (e.g., 'twilio', 'sendgrid')",
+    )
+    discover_parser.add_argument(
+        "--intent", "-i",
+        metavar="TEXT",
+        help="What you want to do (helps discover relevant capabilities)",
+    )
+    
+    # ── discover-url command ───────────────────────────────
+    discover_url_parser = subparsers.add_parser(
+        "discover-url",
+        help="Discover a provider from documentation URL",
+        description="Generate a provider configuration from API documentation.",
+    )
+    discover_url_parser.add_argument(
+        "url",
+        help="API documentation URL",
+    )
+    discover_url_parser.add_argument(
+        "--intent", "-i",
+        metavar="TEXT",
+        help="What you want to do (guides capability extraction)",
+    )
+    
+    # ── status command ─────────────────────────────────────
+    subparsers.add_parser(
+        "status",
+        help="Check API status and show config",
+        description="Check Semantic API health and show current configuration.",
+    )
+    
+    # ── config command ─────────────────────────────────────
+    config_parser = subparsers.add_parser(
+        "config",
+        help="Manage configuration",
+        description="View and update CLI configuration.",
+    )
+    config_subparsers = config_parser.add_subparsers(dest="config_command", metavar="ACTION")
+    
+    # config set-key
+    set_key_parser = config_subparsers.add_parser(
+        "set-key",
+        help="Set default API key",
+    )
+    set_key_parser.add_argument("key", help="API key to save")
+    
+    # config set-url
+    set_url_parser = config_subparsers.add_parser(
+        "set-url",
+        help="Set default base URL",
+    )
+    set_url_parser.add_argument("url", help="Base URL to save")
+    
+    # config show
+    config_subparsers.add_parser(
+        "show",
+        help="Show current configuration",
+    )
+    
+    # config clear
+    config_subparsers.add_parser(
+        "clear",
+        help="Clear all configuration",
+    )
+    
+    return parser
+
+
+def cmd_query(args) -> int:
+    """Handle query command."""
+    api_key = get_api_key(args.key)
+    base_url = get_base_url(args.url)
+    
+    if not api_key:
+        print_error("API key required. Set with --key, SEMANTICAPI_KEY env var, or 'semanticapi config set-key'")
+        return EXIT_AUTH_REQUIRED
+    
+    client = APIClient(base_url, api_key)
+    
+    try:
+        if args.execute:
+            # Agentic mode
+            result = client.agentic(args.query)
+            print_result(result, raw=args.raw, quiet=args.quiet, formatter=format_agentic_result)
+        else:
+            # Regular query
+            result = client.query(args.query, auto_discover=not args.no_discover)
+            print_result(result, raw=args.raw, quiet=args.quiet, formatter=format_query_result)
+        
+        return EXIT_SUCCESS if result.get("success") else EXIT_ERROR
+        
+    except APIError as e:
+        if e.status_code == 401:
+            print_error("Invalid API key or authentication failed")
+            return EXIT_AUTH_REQUIRED
+        elif e.status_code == 429:
+            print_error("Rate limit exceeded. Try again later.")
+            return EXIT_ERROR
+        else:
+            print_error(str(e))
+            return EXIT_ERROR
+
+
+def cmd_batch(args) -> int:
+    """Handle batch command."""
+    api_key = get_api_key(args.key)
+    base_url = get_base_url(args.url)
+    
+    if not api_key:
+        print_error("API key required")
+        return EXIT_AUTH_REQUIRED
+    
+    if len(args.queries) > 10:
+        print_error("Maximum 10 queries per batch")
+        return EXIT_ERROR
+    
+    client = APIClient(base_url, api_key)
+    
+    try:
+        result = client.query_batch(args.queries)
+        print_result(result, raw=args.raw, quiet=args.quiet)
+        
+        # Check if all queries succeeded
+        results = result.get("results", [])
+        all_success = all(r.get("success") for r in results)
+        return EXIT_SUCCESS if all_success else EXIT_ERROR
+        
+    except APIError as e:
+        if e.status_code == 401:
+            print_error("Invalid API key")
+            return EXIT_AUTH_REQUIRED
+        print_error(str(e))
+        return EXIT_ERROR
+
+
+def cmd_preflight(args) -> int:
+    """Handle preflight command."""
+    api_key = get_api_key(args.key)
+    base_url = get_base_url(args.url)
+    
+    if not api_key:
+        print_error("API key required")
+        return EXIT_AUTH_REQUIRED
+    
+    client = APIClient(base_url, api_key)
+    
+    try:
+        result = client.preflight(args.query)
+        print_result(result, raw=args.raw, quiet=args.quiet, formatter=format_preflight_result)
+        return EXIT_SUCCESS
+        
+    except APIError as e:
+        if e.status_code == 401:
+            print_error("Invalid API key")
+            return EXIT_AUTH_REQUIRED
+        print_error(str(e))
+        return EXIT_ERROR
+
+
+def cmd_discover(args) -> int:
+    """Handle discover command."""
+    api_key = get_api_key(args.key)
+    base_url = get_base_url(args.url)
+    
+    if not api_key:
+        print_error("API key required")
+        return EXIT_AUTH_REQUIRED
+    
+    client = APIClient(base_url, api_key)
+    
+    try:
+        result = client.discover(args.provider, user_intent=args.intent)
+        print_result(result, raw=args.raw, quiet=args.quiet, formatter=format_discover_result)
+        return EXIT_SUCCESS if result.get("success") else EXIT_ERROR
+        
+    except APIError as e:
+        if e.status_code == 401:
+            print_error("Invalid API key")
+            return EXIT_AUTH_REQUIRED
+        print_error(str(e))
+        return EXIT_ERROR
+
+
+def cmd_discover_url(args) -> int:
+    """Handle discover-url command."""
+    api_key = get_api_key(args.key)
+    base_url = get_base_url(args.url)
+    
+    if not api_key:
+        print_error("API key required")
+        return EXIT_AUTH_REQUIRED
+    
+    client = APIClient(base_url, api_key)
+    
+    try:
+        result = client.discover_url(args.url, user_intent=args.intent)
+        print_result(result, raw=args.raw, quiet=args.quiet, formatter=format_discover_result)
+        return EXIT_SUCCESS if result.get("success") else EXIT_ERROR
+        
+    except APIError as e:
+        if e.status_code == 401:
+            print_error("Invalid API key")
+            return EXIT_AUTH_REQUIRED
+        print_error(str(e))
+        return EXIT_ERROR
+
+
+def cmd_status(args) -> int:
+    """Handle status command."""
+    base_url = get_base_url(args.url)
+    api_key = get_api_key(args.key)
+    
+    # Show config first
+    if not args.quiet and not args.raw:
+        print(f"  {dim('Config file:')} {CONFIG_FILE}")
+        print(f"  {dim('Base URL:')} {base_url}")
+        if api_key:
+            masked = api_key[:8] + "..." + api_key[-4:] if len(api_key) > 12 else "***"
+            print(f"  {dim('API key:')} {masked}")
+        else:
+            print(f"  {dim('API key:')} {warning('not set')}")
+        print()
+    
+    # Check API health (no auth required for health check)
+    client = APIClient(base_url, api_key)
+    
+    try:
+        result = client.health()
+        print_result(result, raw=args.raw, quiet=args.quiet, formatter=format_status_result)
+        return EXIT_SUCCESS
+        
+    except APIError as e:
+        print_error(f"Could not reach API: {e}")
+        return EXIT_ERROR
+
+
+def cmd_config(args) -> int:
+    """Handle config command."""
+    if args.config_command == "set-key":
+        set_api_key(args.key)
+        print(success(f"✓ API key saved to {CONFIG_FILE}"))
+        return EXIT_SUCCESS
+        
+    elif args.config_command == "set-url":
+        set_base_url(args.url)
+        print(success(f"✓ Base URL saved to {CONFIG_FILE}"))
+        return EXIT_SUCCESS
+        
+    elif args.config_command == "show":
+        config = load_config()
+        if not config:
+            print(dim("No configuration file found."))
+            print(dim(f"Create one with: semanticapi config set-key YOUR_KEY"))
+        else:
+            print(f"Config file: {CONFIG_FILE}")
+            print()
+            for key, value in config.items():
+                if key == "api_key" and value:
+                    # Mask API key
+                    masked = value[:8] + "..." + value[-4:] if len(value) > 12 else "***"
+                    print(f"  {key}: {masked}")
+                else:
+                    print(f"  {key}: {value}")
+        return EXIT_SUCCESS
+        
+    elif args.config_command == "clear":
+        clear_config()
+        print(success("✓ Configuration cleared"))
+        return EXIT_SUCCESS
+        
+    else:
+        # No subcommand - show current config
+        return cmd_config_show(args)
+
+
+def cmd_config_show(args) -> int:
+    """Show current configuration."""
+    config = load_config()
+    if not config:
+        print(dim("No configuration file found."))
+        print(dim(f"Create one with: semanticapi config set-key YOUR_KEY"))
+    else:
+        print(f"Config file: {CONFIG_FILE}")
+        print()
+        for key, value in config.items():
+            if key == "api_key" and value:
+                masked = value[:8] + "..." + value[-4:] if len(value) > 12 else "***"
+                print(f"  {key}: {masked}")
+            else:
+                print(f"  {key}: {value}")
+    return EXIT_SUCCESS
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Main entry point for CLI."""
+    parser = create_parser()
+    args = parser.parse_args(argv)
+    
+    if not args.command:
+        parser.print_help()
+        return EXIT_SUCCESS
+    
+    # Route to command handler
+    handlers = {
+        "query": cmd_query,
+        "batch": cmd_batch,
+        "preflight": cmd_preflight,
+        "discover": cmd_discover,
+        "discover-url": cmd_discover_url,
+        "status": cmd_status,
+        "config": cmd_config,
+    }
+    
+    handler = handlers.get(args.command)
+    if handler:
+        try:
+            return handler(args)
+        except KeyboardInterrupt:
+            print("\nInterrupted")
+            return EXIT_ERROR
+        except Exception as e:
+            print_error(f"Unexpected error: {e}")
+            return EXIT_ERROR
+    else:
+        parser.print_help()
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

semanticapi_cli/config.py

@@ -0,0 +1,101 @@
+"""
+Configuration management for Semantic API CLI.
+
+Config priority: CLI args > environment variables > config file
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+
+CONFIG_DIR = Path.home() / ".semanticapi"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+DEFAULT_BASE_URL = "https://semanticapi.dev"
+
+
+def ensure_config_dir() -> None:
+    """Create config directory if it doesn't exist."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def load_config() -> Dict[str, Any]:
+    """Load config from ~/.semanticapi/config.json."""
+    if not CONFIG_FILE.exists():
+        return {}
+    
+    try:
+        with open(CONFIG_FILE, "r") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def save_config(config: Dict[str, Any]) -> None:
+    """Save config to ~/.semanticapi/config.json."""
+    ensure_config_dir()
+    with open(CONFIG_FILE, "w") as f:
+        json.dump(config, f, indent=2)
+
+
+def get_api_key(cli_key: Optional[str] = None) -> Optional[str]:
+    """
+    Get API key with priority: CLI arg > env var > config file.
+    
+    Returns None if no key is found.
+    """
+    # 1. CLI argument (highest priority)
+    if cli_key:
+        return cli_key
+    
+    # 2. Environment variable
+    env_key = os.environ.get("SEMANTICAPI_KEY")
+    if env_key:
+        return env_key
+    
+    # 3. Config file
+    config = load_config()
+    return config.get("api_key")
+
+
+def get_base_url(cli_url: Optional[str] = None) -> str:
+    """
+    Get base URL with priority: CLI arg > env var > config file > default.
+    """
+    # 1. CLI argument
+    if cli_url:
+        return cli_url.rstrip("/")
+    
+    # 2. Environment variable
+    env_url = os.environ.get("SEMANTICAPI_URL")
+    if env_url:
+        return env_url.rstrip("/")
+    
+    # 3. Config file
+    config = load_config()
+    if config.get("base_url"):
+        return config["base_url"].rstrip("/")
+    
+    # 4. Default
+    return DEFAULT_BASE_URL
+
+
+def set_api_key(key: str) -> None:
+    """Save API key to config file."""
+    config = load_config()
+    config["api_key"] = key
+    save_config(config)
+
+
+def set_base_url(url: str) -> None:
+    """Save base URL to config file."""
+    config = load_config()
+    config["base_url"] = url.rstrip("/")
+    save_config(config)
+
+
+def clear_config() -> None:
+    """Clear all config."""
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()

semanticapi_cli/output.py

@@ -0,0 +1,355 @@
+"""
+Output formatting for Semantic API CLI.
+
+Handles pretty JSON, compact JSON, and quiet mode output.
+Uses ANSI colors when outputting to a TTY.
+"""
+
+import json
+import sys
+from typing import Any, Dict, Optional
+
+
+# ANSI color codes
+class Colors:
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    
+    # Foreground
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    WHITE = "\033[37m"
+    
+    # Bright
+    BRIGHT_GREEN = "\033[92m"
+    BRIGHT_YELLOW = "\033[93m"
+    BRIGHT_BLUE = "\033[94m"
+    BRIGHT_CYAN = "\033[96m"
+
+
+def is_tty() -> bool:
+    """Check if stdout is a TTY (supports colors)."""
+    return hasattr(sys.stdout, 'isatty') and sys.stdout.isatty()
+
+
+def colorize(text: str, color: str) -> str:
+    """Apply color to text if outputting to TTY."""
+    if is_tty():
+        return f"{color}{text}{Colors.RESET}"
+    return text
+
+
+def success(text: str) -> str:
+    """Green success text."""
+    return colorize(text, Colors.GREEN)
+
+
+def error(text: str) -> str:
+    """Red error text."""
+    return colorize(text, Colors.RED)
+
+
+def warning(text: str) -> str:
+    """Yellow warning text."""
+    return colorize(text, Colors.YELLOW)
+
+
+def info(text: str) -> str:
+    """Blue info text."""
+    return colorize(text, Colors.BLUE)
+
+
+def dim(text: str) -> str:
+    """Dimmed text."""
+    return colorize(text, Colors.DIM)
+
+
+def bold(text: str) -> str:
+    """Bold text."""
+    return colorize(text, Colors.BOLD)
+
+
+def format_json(data: Any, raw: bool = False) -> str:
+    """
+    Format data as JSON.
+    
+    Args:
+        data: Data to format
+        raw: If True, compact JSON. Otherwise, pretty-printed.
+    """
+    if raw:
+        return json.dumps(data, separators=(',', ':'))
+    return json.dumps(data, indent=2)
+
+
+def format_query_result(data: Dict[str, Any], quiet: bool = False) -> str:
+    """
+    Format a query result for display.
+    
+    Args:
+        data: Query response data
+        quiet: If True, show minimal output
+    """
+    lines = []
+    
+    if quiet:
+        # Minimal output: just the essential fields
+        if data.get("success"):
+            provider = data.get("provider", "?")
+            operation = data.get("operation", "?")
+            lines.append(f"{provider}.{operation}")
+            if data.get("data"):
+                # Show snippet or first key info
+                result_data = data["data"]
+                if isinstance(result_data, dict):
+                    if "endpoint" in result_data:
+                        lines.append(result_data["endpoint"])
+                    elif "url" in result_data:
+                        lines.append(result_data["url"])
+        else:
+            lines.append(error(data.get("error", "Unknown error")))
+    else:
+        # Full formatted output
+        if data.get("success"):
+            lines.append(success("✓ Query matched"))
+            lines.append("")
+            
+            provider = data.get("provider", "unknown")
+            operation = data.get("operation", "unknown")
+            lines.append(f"  {bold('Provider:')} {provider}")
+            lines.append(f"  {bold('Operation:')} {operation}")
+            
+            # Show parsed intent params if present
+            intent = data.get("parsed_intent", {})
+            params = intent.get("params", {})
+            if params:
+                lines.append(f"  {bold('Parameters:')}")
+                for k, v in params.items():
+                    lines.append(f"    {dim(k)}: {v}")
+            
+            # Show data/snippet if present
+            result_data = data.get("data", {})
+            if isinstance(result_data, dict):
+                if result_data.get("endpoint"):
+                    lines.append("")
+                    lines.append(f"  {bold('Endpoint:')} {result_data['endpoint']}")
+                if result_data.get("curl"):
+                    lines.append(f"  {bold('cURL:')}")
+                    lines.append(f"    {dim(result_data['curl'][:200])}")
+                if result_data.get("python"):
+                    lines.append(f"  {bold('Python:')}")
+                    for line in result_data['python'].split('\n')[:5]:
+                        lines.append(f"    {dim(line)}")
+        else:
+            lines.append(error("✗ Query failed"))
+            lines.append("")
+            lines.append(f"  {data.get('error', 'Unknown error')}")
+    
+    return "\n".join(lines)
+
+
+def format_preflight_result(data: Dict[str, Any], quiet: bool = False) -> str:
+    """Format a preflight result for display."""
+    lines = []
+    
+    if quiet:
+        providers = data.get("providers", [])
+        ready = data.get("ready", False)
+        status = "ready" if ready else "needs_setup"
+        provider_list = ", ".join(p.get("provider", "?") for p in providers)
+        return f"{status}: {provider_list}"
+    
+    lines.append(bold("Preflight Check"))
+    lines.append("")
+    lines.append(f"  {bold('Query:')} {data.get('query', '?')}")
+    lines.append("")
+    
+    providers = data.get("providers", [])
+    if providers:
+        lines.append(f"  {bold('Providers needed:')}")
+        for p in providers:
+            name = p.get("provider", "?")
+            status = p.get("status", "?")
+            
+            if status == "ready":
+                status_str = success("✓ ready")
+            elif status == "needs_auth":
+                status_str = warning("⚠ needs auth")
+            elif status == "needs_discovery":
+                status_str = info("? needs discovery")
+            else:
+                status_str = dim(status)
+            
+            lines.append(f"    • {name}: {status_str}")
+            if p.get("reason"):
+                lines.append(f"      {dim(p['reason'])}")
+    
+    lines.append("")
+    if data.get("ready"):
+        lines.append(success("  All providers ready! You can run this query."))
+    else:
+        lines.append(warning("  " + data.get("message", "Some setup required.")))
+    
+    return "\n".join(lines)
+
+
+def format_discover_result(data: Dict[str, Any], quiet: bool = False) -> str:
+    """Format a discover result for display."""
+    lines = []
+    
+    if quiet:
+        if data.get("success"):
+            provider = data.get("provider", {})
+            name = provider.get("name", "?")
+            caps = data.get("capabilities_found", 0)
+            return f"{name}: {caps} capabilities"
+        else:
+            return error(data.get("error", "Discovery failed"))
+    
+    if data.get("success"):
+        lines.append(success("✓ Provider discovered"))
+        lines.append("")
+        
+        provider = data.get("provider", {})
+        lines.append(f"  {bold('Name:')} {provider.get('name', '?')}")
+        lines.append(f"  {bold('ID:')} {provider.get('provider', '?')}")
+        lines.append(f"  {bold('Base URL:')} {provider.get('base_url', '?')}")
+        lines.append(f"  {bold('Capabilities:')} {data.get('capabilities_found', 0)}")
+        
+        if provider.get("description"):
+            lines.append(f"  {bold('Description:')} {provider['description'][:100]}")
+        
+        if data.get("source_url") and data["source_url"] != "(cached)":
+            lines.append(f"  {bold('Source:')} {data['source_url']}")
+        
+        if data.get("usage_note"):
+            lines.append("")
+            lines.append(f"  {dim(data['usage_note'])}")
+        
+        # Show capabilities
+        caps = provider.get("capabilities", [])
+        if caps:
+            lines.append("")
+            lines.append(f"  {bold('Capabilities:')}")
+            for cap in caps[:10]:  # Show first 10
+                lines.append(f"    • {cap.get('name', cap.get('id', '?'))}")
+            if len(caps) > 10:
+                lines.append(f"    {dim(f'... and {len(caps) - 10} more')}")
+    else:
+        lines.append(error("✗ Discovery failed"))
+        lines.append("")
+        lines.append(f"  {data.get('error', 'Unknown error')}")
+    
+    return "\n".join(lines)
+
+
+def format_status_result(data: Dict[str, Any], quiet: bool = False) -> str:
+    """Format health/status result for display."""
+    lines = []
+    
+    if quiet:
+        return data.get("status", "unknown")
+    
+    status = data.get("status", "unknown")
+    if status == "ok":
+        lines.append(success("✓ Semantic API is healthy"))
+    elif status == "degraded":
+        lines.append(warning("⚠ Semantic API is degraded"))
+    else:
+        lines.append(error(f"✗ Status: {status}"))
+    
+    lines.append("")
+    lines.append(f"  {bold('Version:')} {data.get('version', '?')}")
+    
+    if data.get("database"):
+        lines.append(f"  {bold('Database:')} {data['database']}")
+    
+    if data.get("cache"):
+        cache = data["cache"]
+        lines.append(f"  {bold('Cache:')}")
+        lines.append(f"    Memory size: {cache.get('memory_size', '?')}")
+        lines.append(f"    Hits: {cache.get('memory_hits', '?')}")
+    
+    return "\n".join(lines)
+
+
+def format_agentic_result(data: Dict[str, Any], quiet: bool = False) -> str:
+    """Format an agentic (execution) result for display."""
+    lines = []
+    
+    if quiet:
+        if data.get("success"):
+            return data.get("response", "")[:200]
+        else:
+            return error(data.get("error", "Execution failed"))
+    
+    if data.get("success"):
+        lines.append(success("✓ Execution complete"))
+        lines.append("")
+        
+        # Show the synthesized response
+        response = data.get("response", "")
+        if response:
+            lines.append(f"  {bold('Response:')}")
+            for line in response.split('\n'):
+                lines.append(f"    {line}")
+        
+        # Show steps taken
+        steps = data.get("steps", [])
+        if steps:
+            lines.append("")
+            lines.append(f"  {bold('Steps:')} ({len(steps)} API calls)")
+            for i, step in enumerate(steps[:5], 1):
+                tool = step.get("tool", "?")
+                lines.append(f"    {i}. {dim(tool)}")
+            if len(steps) > 5:
+                lines.append(f"    {dim(f'... and {len(steps) - 5} more')}")
+        
+        # Show status if not complete
+        status = data.get("status", "complete")
+        if status == "needs_input":
+            lines.append("")
+            lines.append(warning(f"  ⚠ {data.get('question', 'Input needed')}"))
+            if data.get("options"):
+                for opt in data["options"]:
+                    lines.append(f"    • {opt}")
+        elif status == "awaiting_auth":
+            lines.append("")
+            lines.append(warning("  ⚠ Authentication required"))
+            lines.append(f"    Execution ID: {data.get('execution_id', '?')}")
+    else:
+        lines.append(error("✗ Execution failed"))
+        lines.append("")
+        lines.append(f"  {data.get('error', 'Unknown error')}")
+    
+    return "\n".join(lines)
+
+
+def print_error(message: str) -> None:
+    """Print error message to stderr."""
+    print(error(f"Error: {message}"), file=sys.stderr)
+
+
+def print_result(data: Any, raw: bool = False, quiet: bool = False, formatter=None) -> None:
+    """
+    Print result to stdout.
+    
+    Args:
+        data: Data to print
+        raw: If True, output compact JSON
+        quiet: If True, output minimal info
+        formatter: Optional function to format non-JSON output
+    """
+    if raw:
+        print(format_json(data, raw=True))
+    elif formatter and not quiet:
+        print(formatter(data, quiet=quiet))
+    elif quiet and formatter:
+        print(formatter(data, quiet=True))
+    else:
+        print(format_json(data))

semanticapi_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: semanticapi-cli
+Version: 0.1.0
+Summary: CLI for Semantic API — discover and query 700+ APIs with natural language
+Author-email: Peter Thompson <peter@coveai.dev>
+License: MIT
+Project-URL: Homepage, https://semanticapi.dev
+Project-URL: Documentation, https://semanticapi.dev/docs
+Project-URL: Repository, https://github.com/peter-j-thompson/semanticapi-cli
+Project-URL: Issues, https://github.com/peter-j-thompson/semanticapi-cli/issues
+Keywords: api,cli,semantic,discovery,mcp,ai-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Semantic API CLI
+
+Query 700+ APIs with natural language from your terminal. Zero dependencies.
+
+```bash
+pip install semanticapi
+```
+
+## Quick Start
+
+```bash
+# Save your API key
+semanticapi config set-key sapi_your_key
+
+# Query any API
+semanticapi query "send an SMS via Twilio"
+
+# Pre-check what you'll need (free, no LLM cost)
+semanticapi preflight "send an email"
+
+# Discover a provider
+semanticapi discover stripe
+
+# Batch queries
+semanticapi batch "send email" "upload file" "translate text"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `query` | Natural language API query |
+| `batch` | Multiple queries in one call |
+| `preflight` | Pre-check (free, identifies needed auth) |
+| `discover` | Look up a provider by name |
+| `discover-url` | Discover provider from docs URL |
+| `status` | Show config and API health |
+| `config` | Manage API key and settings |
+
+## Authentication
+
+API key priority (first found wins):
+
+1. `--key sapi_xxx` flag
+2. `SEMANTICAPI_KEY` environment variable
+3. `~/.semanticapi/config.json` (saved via `config set-key`)
+
+Get your key at [semanticapi.dev](https://semanticapi.dev).
+
+## Output Modes
+
+```bash
+# Pretty-printed (default)
+semanticapi query "get weather"
+
+# Raw JSON (for piping)
+semanticapi --raw query "get weather"
+
+# Minimal output
+semanticapi --quiet query "get weather"
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error |
+| 2 | Auth required |
+
+## What You Get Back
+
+Every query returns:
+- **Provider** and endpoint details
+- **Code snippets** (curl + Python) ready to copy-paste
+- **Auth requirements** and setup instructions
+- **Alternative providers** ranked by relevance
+
+## Related
+
+- [Semantic API](https://semanticapi.dev) — The API
+- [MCP Server](https://pypi.org/project/semanticapi-mcp/) — For Claude Desktop / ChatGPT
+- [Agent Skill](https://pypi.org/project/semantic-api-skill/) — For autonomous agents
+- [Open Source Engine](https://github.com/peter-j-thompson/semanticapi-engine) — AGPL-3.0
+
+## License
+
+MIT

semanticapi_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+semanticapi_cli/__init__.py,sha256=ez-HFyWySAGAhL-56yFZOi6tQaEzi8VrvpAuslHO1EM,271
+semanticapi_cli/__main__.py,sha256=rNB4M8zxt72oLEyPXODI0h_0ZbBXCq7O9QeoGH5HE5Y,133
+semanticapi_cli/api.py,sha256=Hb70he3-bGiClbeIQtljf09WS2mxXcRukVWd_pAOfGs,4566
+semanticapi_cli/cli.py,sha256=ytTRq4uz1rl2GgCG2CezTvw_4GyTdqqHxqR76mszKF4,14979
+semanticapi_cli/config.py,sha256=__lObK74bxrSVYwzWDTvDRT9DAybuj8_0Ss3eqg16TQ,2431
+semanticapi_cli/output.py,sha256=POXCQBIMqjyJiTQmOwsrsvZfbzX3ZWfda_SgKmdkUOI,11640
+semanticapi_cli-0.1.0.dist-info/licenses/LICENSE,sha256=EzlU4nH4j0f_qGkSfmVtX1WuiAVu3p-cXgpo4LK7ePw,1081
+semanticapi_cli-0.1.0.dist-info/METADATA,sha256=X6t-RcvWHFZ8E130Y9ulsuiTU84ExkSucrMF4D4KcCk,3188
+semanticapi_cli-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+semanticapi_cli-0.1.0.dist-info/entry_points.txt,sha256=dryK67Wwwl2wRVxBGuFi-6WobL-vIKKee61DExBj7SE,57
+semanticapi_cli-0.1.0.dist-info/top_level.txt,sha256=WB902-mnUPAWXRpVC7qSnYXFjtIr02QzbCoygfes-xA,16
+semanticapi_cli-0.1.0.dist-info/RECORD,,

semanticapi_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

semanticapi_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+semanticapi = semanticapi_cli.cli:main

semanticapi_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Thompson / Cove AI
+
+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.

semanticapi_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+semanticapi_cli