lockthard-cli 0.1.0__tar.gz

lockthard_cli-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: lockthard-cli
+Version: 0.1.0
+Summary: Super efficient CLI for LOCKTHARD AI tools directory and agents
+Author-email: Lockthard Team <info@lockthard.es>
+License: MIT
+Project-URL: Homepage, https://lockthard.es
+Keywords: cli,ai-tools,agents,mcp,lockthard
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=13.0.0
+
+# LOCKTHARD CLI (`lockthard`)
+
+A super efficient, scriptable command-line interface and AI agent client for **LOCKTHARD** (https://lockthard.es).
+
+Allows both human developers and autonomous AI agents (Claude Code, Antigravity, Aider, Cursor, etc.) to query, search, and inspect 61+ tablets and 1200+ AI tools with minimum token usage and zero prompt overhead.
+
+## Installation
+
+```bash
+pip install lockthard-cli
+```
+
+Or run without installing:
+
+```bash
+pipx run lockthard-cli --help
+```
+
+## Quick Start
+
+### 1. Authentication
+Get your API key from [lockthard.es](https://lockthard.es).
+
+- **For AI Agents & CI/CD:**
+  ```bash
+  export LOCKTHARD_API_KEY="lk_your_token_here"
+  ```
+- **Interactive Browser Login (Humans):**
+  ```bash
+  lockthard login
+  ```
+- **Manual Login:**
+  ```bash
+  lockthard login --token "lk_your_token_here"
+  ```
+
+### 2. Commands
+
+```bash
+# Ping service
+lockthard ping
+
+# Search tools (returns concise ASCII table)
+lockthard search "ocr"
+
+# Search tools in raw JSON (for agents / jq)
+lockthard search "ocr" --json
+
+# List all tablets
+lockthard tablets list
+
+# Inspect a specific tablet
+lockthard tablets get ocr
+
+# Inspect tool details
+lockthard tools get "Chandra OCR"
+
+# Display CLI agent guide
+lockthard guide
+```
+
+## Options
+
+- `--json` / `-j`: Output raw JSON without Rich styling.
+- `--url` / `-u`: Override base server URL (default: `https://lockthard.es`).
+- `--token` / `-t`: Override API token.
+
+## License
+
+MIT License

lockthard_cli-0.1.0/README.md

@@ -0,0 +1,70 @@
+# LOCKTHARD CLI (`lockthard`)
+
+A super efficient, scriptable command-line interface and AI agent client for **LOCKTHARD** (https://lockthard.es).
+
+Allows both human developers and autonomous AI agents (Claude Code, Antigravity, Aider, Cursor, etc.) to query, search, and inspect 61+ tablets and 1200+ AI tools with minimum token usage and zero prompt overhead.
+
+## Installation
+
+```bash
+pip install lockthard-cli
+```
+
+Or run without installing:
+
+```bash
+pipx run lockthard-cli --help
+```
+
+## Quick Start
+
+### 1. Authentication
+Get your API key from [lockthard.es](https://lockthard.es).
+
+- **For AI Agents & CI/CD:**
+  ```bash
+  export LOCKTHARD_API_KEY="lk_your_token_here"
+  ```
+- **Interactive Browser Login (Humans):**
+  ```bash
+  lockthard login
+  ```
+- **Manual Login:**
+  ```bash
+  lockthard login --token "lk_your_token_here"
+  ```
+
+### 2. Commands
+
+```bash
+# Ping service
+lockthard ping
+
+# Search tools (returns concise ASCII table)
+lockthard search "ocr"
+
+# Search tools in raw JSON (for agents / jq)
+lockthard search "ocr" --json
+
+# List all tablets
+lockthard tablets list
+
+# Inspect a specific tablet
+lockthard tablets get ocr
+
+# Inspect tool details
+lockthard tools get "Chandra OCR"
+
+# Display CLI agent guide
+lockthard guide
+```
+
+## Options
+
+- `--json` / `-j`: Output raw JSON without Rich styling.
+- `--url` / `-u`: Override base server URL (default: `https://lockthard.es`).
+- `--token` / `-t`: Override API token.
+
+## License
+
+MIT License

lockthard_cli-0.1.0/lockthard_cli/__init__.py

@@ -0,0 +1,5 @@
+"""
+LOCKTHARD CLI - Command Line Interface and Agent Client for LOCKTHARD.
+"""
+
+__version__ = "0.1.0"

lockthard_cli-0.1.0/lockthard_cli/auth.py

@@ -0,0 +1,159 @@
+import http.server
+import socket
+import socketserver
+import urllib.parse
+import webbrowser
+from typing import Tuple, Optional, Dict, Any
+from .config import save_credentials, clear_credentials
+
+
+class OAuthCallbackHandler(http.server.BaseHTTPRequestHandler):
+    """Temporary HTTP handler to capture the token callback from browser authentication."""
+
+    received_token: Optional[str] = None
+    received_email: Optional[str] = None
+    error_message: Optional[str] = None
+
+    def log_message(self, format, *args):
+        # Silence default HTTP server logging
+        pass
+
+    def do_GET(self):
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path in ("/callback", "/"):
+            query = urllib.parse.parse_qs(parsed.query)
+            token = query.get("token", [None])[0]
+            email = query.get("email", [None])[0]
+            error = query.get("error", [None])[0]
+
+            if error:
+                OAuthCallbackHandler.error_message = error
+                self._send_response_html(
+                    status=400,
+                    title="Error de Autenticación",
+                    body=f"<p style='color: red;'>Error durante el inicio de sesión: {error}</p>"
+                )
+            elif token:
+                OAuthCallbackHandler.received_token = token
+                OAuthCallbackHandler.received_email = email
+                self._send_response_html(
+                    status=200,
+                    title="¡Autenticación Exitosa!",
+                    body="""
+                    <h2 style='color: #10B981;'>¡Autenticación Exitosa!</h2>
+                    <p>La CLI de <strong>LOCKTHARD</strong> ha sido conectada correctamente a tu cuenta.</p>
+                    <p>Ya puedes cerrar esta ventana y regresar a tu terminal.</p>
+                    """
+                )
+            else:
+                self._send_response_html(
+                    status=400,
+                    title="Falta Token",
+                    body="<p style='color: red;'>No se recibió ningún token de autenticación.</p>"
+                )
+        else:
+            self.send_error(404, "Not Found")
+
+    def _send_response_html(self, status: int, title: str, body: str):
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>{title}</title>
+    <style>
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+            background: #0d1117;
+            color: #c9d1d9;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            height: 100vh;
+            margin: 0;
+        }}
+        .card {{
+            background: #161b22;
+            border: 1px solid #30363d;
+            border-radius: 12px;
+            padding: 32px;
+            max-width: 420px;
+            text-align: center;
+            box-shadow: 0 10px 25px rgba(0,0,0,0.5);
+        }}
+    </style>
+</head>
+<body>
+    <div class="card">
+        {body}
+    </div>
+</body>
+</html>
+"""
+        self.wfile.write(html.encode("utf-8"))
+
+
+def find_free_port(start_port: int = 8989) -> int:
+    """Find an available port starting from start_port."""
+    for port in range(start_port, start_port + 20):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    return start_port
+
+
+def perform_browser_login(api_url: str, timeout_seconds: int = 120) -> Tuple[bool, str]:
+    """
+    Launch local server, open browser to lockthard.es/cli-auth, and capture token.
+    """
+    port = find_free_port(8989)
+    callback_url = f"http://127.0.0.1:{port}/callback"
+    auth_url = f"{api_url.rstrip('/')}/cli-auth?callback={urllib.parse.quote(callback_url)}"
+
+    OAuthCallbackHandler.received_token = None
+    OAuthCallbackHandler.received_email = None
+    OAuthCallbackHandler.error_message = None
+
+    class ReusableTCPServer(socketserver.TCPServer):
+        allow_reuse_address = True
+
+    try:
+        httpd = ReusableTCPServer(("127.0.0.1", port), OAuthCallbackHandler)
+        httpd.timeout = 1.0
+    except Exception as e:
+        return False, f"No se pudo iniciar el servidor local en el puerto {port}: {e}"
+
+    print(f"Abriendo el navegador para autenticar en LOCKTHARD...")
+    print(f"URL: {auth_url}\n")
+    try:
+        webbrowser.open(auth_url)
+    except Exception:
+        print("No se pudo abrir el navegador automáticamente. Por favor abre la URL manualmente.")
+
+    import time
+    start_time = time.time()
+
+    while time.time() - start_time < timeout_seconds:
+        httpd.handle_request()
+        if OAuthCallbackHandler.received_token:
+            token = OAuthCallbackHandler.received_token
+            email = OAuthCallbackHandler.received_email
+            httpd.server_close()
+
+            # Save credentials
+            save_credentials(api_key=token, email=email, api_url=api_url)
+            user_str = f" como {email}" if email else ""
+            return True, f"¡Autenticado correctamente{user_str}!"
+
+        if OAuthCallbackHandler.error_message:
+            httpd.server_close()
+            return False, f"Error devuelto por la autenticación: {OAuthCallbackHandler.error_message}"
+
+    httpd.server_close()
+    return False, "Tiempo de espera agotado (timeout) esperando la autorización en el navegador."

lockthard_cli-0.1.0/lockthard_cli/cli.py

@@ -0,0 +1,196 @@
+import sys
+from typing import Optional
+import click
+
+from . import __version__
+from .config import resolve_token, resolve_api_url, save_credentials, clear_credentials
+from .auth import perform_browser_login
+from .client import LockthardClient, LockthardError
+from .formatters import (
+    output_data,
+    print_ping_result,
+    print_tablets_list,
+    print_search_results,
+    print_tablet_content,
+    print_tool_details,
+    print_cli_tools,
+    print_agent_guide,
+    print_agent_skill
+)
+
+
+def _handle_error(err: Exception):
+    """Print clean error message without traceback."""
+    click.secho(f"Error: {err}", fg="red", err=True)
+    sys.exit(1)
+
+
+@click.group(invoke_without_command=False)
+@click.option("--url", "-u", default=None, help="Base URL del servidor LOCKTHARD (default: https://lockthard.es).")
+@click.option("--token", "-t", default=None, help="API Key / Token de autenticación (lk_...).")
+@click.option("--json", "-j", "as_json", is_flag=True, help="Salida en JSON bruto (ideal para scripts y agentes).")
+@click.version_option(version=__version__, prog_name="lockthard")
+@click.pass_context
+def cli(ctx: click.Context, url: Optional[str], token: Optional[str], as_json: bool):
+    """LOCKTHARD CLI - Cliente super eficiente de herramientas IA para humanos y agentes."""
+    resolved_url = resolve_api_url(url)
+    resolved_token = resolve_token(token)
+
+    ctx.ensure_object(dict)
+    ctx.obj["url"] = resolved_url
+    ctx.obj["token"] = resolved_token
+    ctx.obj["as_json"] = as_json
+    ctx.obj["client"] = LockthardClient(base_url=resolved_url, token=resolved_token)
+
+
+@cli.command()
+@click.pass_context
+def ping(ctx: click.Context):
+    """Verifica la conectividad con el servidor de LOCKTHARD y el estado del token."""
+    client: LockthardClient = ctx.obj["client"]
+    try:
+        res = client.ping()
+        print_ping_result(res, as_json=ctx.obj["as_json"])
+    except LockthardError as e:
+        _handle_error(e)
+
+
+@cli.command()
+@click.option("--token", "-t", help="API Key directa (lk_...) para guardar sin interacción.")
+@click.option("--manual", "-m", is_flag=True, help="Modo interactivo en consola (sin abrir navegador).")
+@click.pass_context
+def login(ctx: click.Context, token: Optional[str], manual: bool):
+    """Inicia sesión en LOCKTHARD (Browser OAuth, Token o Interactivo)."""
+    api_url = ctx.obj["url"]
+
+    # 1. Direct token via flag
+    if token and token.strip():
+        save_credentials(api_key=token.strip(), api_url=api_url)
+        click.secho("✓ API Key guardada correctamente en ~/.lockthard/credentials.json", fg="green")
+        return
+
+    # 2. Manual prompt via flag
+    if manual:
+        token_input = click.prompt("Pega tu API Key de LOCKTHARD (lk_...)", hide_input=True)
+        if not token_input or not token_input.strip():
+            _handle_error(LockthardError("Token vacío."))
+        save_credentials(api_key=token_input.strip(), api_url=api_url)
+        click.secho("✓ API Key guardada correctamente en ~/.lockthard/credentials.json", fg="green")
+        return
+
+    # 3. Interactive Browser Login
+    click.echo(f"Iniciando flujo de autenticación para {api_url}...")
+    success, msg = perform_browser_login(api_url)
+    if success:
+        click.secho(f"✓ {msg}", fg="green")
+    else:
+        click.secho(f"✗ {msg}", fg="yellow")
+        click.echo("Puedes autenticarte manualmente con: lockthard login --token lk_tu_token")
+
+
+@cli.command()
+def logout():
+    """Cierra la sesión y elimina las credenciales locales."""
+    if clear_credentials():
+        click.secho("✓ Sesión cerrada y credenciales eliminadas (~/.lockthard/credentials.json).", fg="green")
+    else:
+        click.echo("No había ninguna sesión activa guardada.")
+
+
+@cli.command()
+@click.argument("query")
+@click.option("--tablet", "-t", help="Filtrar por ID de tablet específica.")
+@click.option("--limit", "-l", default=20, type=int, help="Límite de resultados (default: 20).")
+@click.pass_context
+def search(ctx: click.Context, query: str, tablet: Optional[str], limit: int):
+    """Busca herramientas por palabra clave en LOCKTHARD."""
+    client: LockthardClient = ctx.obj["client"]
+    try:
+        results = client.search_tools(query=query, tablet_id=tablet, limit=limit)
+        print_search_results(query, results, as_json=ctx.obj["as_json"])
+    except LockthardError as e:
+        _handle_error(e)
+
+
+@cli.group()
+def tablets():
+    """Comandos para explorar las tablets de LOCKTHARD."""
+    pass
+
+
+@tablets.command(name="list")
+@click.option("--query", "-q", help="Filtrar tablets por título o categoría.")
+@click.pass_context
+def list_tablets_cmd(ctx: click.Context, query: Optional[str]):
+    """Lista los 61+ tablets y categorías disponibles."""
+    client: LockthardClient = ctx.obj["client"]
+    try:
+        res = client.list_tablets(query=query)
+        print_tablets_list(res, as_json=ctx.obj["as_json"])
+    except LockthardError as e:
+        _handle_error(e)
+
+
+@tablets.command(name="get")
+@click.argument("tablet_id")
+@click.option("--limit", "-l", type=int, help="Límite de herramientas a devolver.")
+@click.pass_context
+def get_tablet_cmd(ctx: click.Context, tablet_id: str, limit: Optional[int]):
+    """Obtiene el contenido completo de un tablet por su ID (ej. ocr, open-source)."""
+    client: LockthardClient = ctx.obj["client"]
+    try:
+        res = client.get_tablet(tablet_id=tablet_id, limit=limit)
+        print_tablet_content(res, as_json=ctx.obj["as_json"])
+    except LockthardError as e:
+        _handle_error(e)
+
+
+@cli.group()
+def tools():
+    """Comandos para inspeccionar herramientas individuales."""
+    pass
+
+
+@tools.command(name="get")
+@click.argument("tool_id")
+@click.pass_context
+def get_tool_cmd(ctx: click.Context, tool_id: str):
+    """Obtiene los detalles y comandos recomendados de una herramienta específica."""
+    client: LockthardClient = ctx.obj["client"]
+    try:
+        res = client.get_tool_details(tool_id=tool_id)
+        print_tool_details(res, as_json=ctx.obj["as_json"])
+    except LockthardError as e:
+        _handle_error(e)
+
+
+@cli.command(name="cli-tools")
+@click.pass_context
+def cli_tools_cmd(ctx: click.Context):
+    """Lista las herramientas especializadas de línea de comandos en LOCKTHARD."""
+    client: LockthardClient = ctx.obj["client"]
+    try:
+        res = client.get_cli_tools()
+        print_cli_tools(res, as_json=ctx.obj["as_json"])
+    except LockthardError as e:
+        _handle_error(e)
+
+
+@cli.command()
+def guide():
+    """Muestra la guía rápida de la CLI optimizada para Agentes de IA."""
+    print_agent_guide()
+
+
+@cli.command()
+def skill():
+    """Genera la especificación SKILL.md completa para que un Agente de IA la importe."""
+    print_agent_skill()
+
+
+def main():
+    cli(obj={})
+
+
+if __name__ == "__main__":
+    main()

lockthard_cli-0.1.0/lockthard_cli/client.py

@@ -0,0 +1,141 @@
+import json
+from typing import Any, Dict, List, Optional
+import requests
+
+
+class LockthardError(Exception):
+    """Base exception for LOCKTHARD CLI client errors."""
+    pass
+
+
+class LockthardClient:
+    """Pure data layer for communicating with the LOCKTHARD API backend."""
+
+    def __init__(self, base_url: str = "https://lockthard.es", token: Optional[str] = None, timeout: int = 15):
+        self.base_url = base_url.rstrip("/")
+        self.token = token.strip() if token else None
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({"Accept": "application/json"})
+        if self.token:
+            self._session.headers.update({"Authorization": f"Bearer {self.token}"})
+        self._jsonrpc_id = 0
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        try:
+            url = f"{self.base_url}{path}"
+            resp = self._session.get(url, params=params, timeout=self.timeout)
+            if resp.status_code == 401:
+                raise LockthardError("No autorizado: Token inválido o no proporcionado.")
+            resp.raise_for_status()
+            if not resp.content:
+                return {}
+            return resp.json()
+        except requests.ConnectionError:
+            raise LockthardError(f"No se pudo conectar con el servidor en {self.base_url}")
+        except requests.Timeout:
+            raise LockthardError(f"Tiempo de espera agotado ({self.timeout}s) conectando a {self.base_url}")
+        except requests.HTTPError as e:
+            raise LockthardError(f"Error HTTP del servidor: {e}")
+        except ValueError:
+            raise LockthardError("Respuesta de servidor no válida (JSON inválido).")
+
+    def _mcp_call(self, method: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        """Call LOCKTHARD JSON-RPC MCP endpoint at /api/mcp."""
+        self._jsonrpc_id += 1
+        payload = {
+            "jsonrpc": "2.0",
+            "id": self._jsonrpc_id,
+            "method": method,
+            "params": params or {}
+        }
+        try:
+            url = f"{self.base_url}/api/mcp"
+            resp = self._session.post(url, json=payload, timeout=self.timeout)
+            if resp.status_code == 401:
+                raise LockthardError("No autorizado: Token inválido. Inicia sesión con 'lockthard login'.")
+            resp.raise_for_status()
+            data = resp.json()
+            if "error" in data:
+                err = data["error"]
+                raise LockthardError(f"Error MCP ({err.get('code', 'unknown')}): {err.get('message', '')}")
+
+            result = data.get("result", {})
+            # Decode MCP text content if wrapped
+            if isinstance(result, dict) and "content" in result and isinstance(result["content"], list):
+                for item in result["content"]:
+                    if isinstance(item, dict) and item.get("type") == "text":
+                        text_val = item.get("text", "")
+                        try:
+                            return json.loads(text_val)
+                        except (ValueError, TypeError):
+                            return text_val
+            return result
+        except requests.ConnectionError:
+            raise LockthardError(f"No se pudo conectar con el servidor en {self.base_url}")
+        except requests.Timeout:
+            raise LockthardError(f"Tiempo de espera agotado ({self.timeout}s) conectando a {self.base_url}")
+        except requests.HTTPError as e:
+            raise LockthardError(f"Error HTTP del servidor: {e}")
+        except ValueError:
+            raise LockthardError("Respuesta de servidor no válida (JSON inválido).")
+
+    def ping(self) -> Dict[str, Any]:
+        """Check API connectivity and auth status."""
+        if self.token:
+            try:
+                data = self._get("/api/mcp/ping")
+                return {"status": "ok", "authenticated": True, "details": data}
+            except LockthardError as e:
+                if "No autorizado" in str(e):
+                    return {"status": "unauthorized", "authenticated": False, "error": str(e)}
+                raise
+        data = self._get("/api/health")
+        return {"status": "ok", "authenticated": False, "health": data}
+
+    def list_tablets(self, query: Optional[str] = None) -> List[Dict[str, Any]]:
+        """List all available tablets with counts and summaries."""
+        res = self._mcp_call("tools/call", {
+            "name": "list_tablets",
+            "arguments": {"query": query} if query else {}
+        })
+        if isinstance(res, list):
+            return res
+        if isinstance(res, dict) and "tablets" in res:
+            return res["tablets"]
+        return []
+
+    def get_tablet(self, tablet_id: str, limit: Optional[int] = None) -> Dict[str, Any]:
+        """Get full details and items of a specific tablet."""
+        args: Dict[str, Any] = {"tablet_id": tablet_id}
+        if limit is not None:
+            args["limit"] = limit
+        res = self._mcp_call("tools/call", {
+            "name": "get_tablet",
+            "arguments": args
+        })
+        return res if isinstance(res, dict) else {"items": res}
+
+    def search_tools(self, query: str, tablet_id: Optional[str] = None, limit: int = 20) -> List[Dict[str, Any]]:
+        """Search across all tools in LOCKTHARD directory."""
+        args: Dict[str, Any] = {"query": query, "limit": limit}
+        if tablet_id:
+            args["tablet_id"] = tablet_id
+        res = self._mcp_call("tools/call", {
+            "name": "search_tools",
+            "arguments": args
+        })
+        return res if isinstance(res, list) else []
+
+    def get_tool_details(self, tool_id: str) -> Dict[str, Any]:
+        """Get full details of a specific tool by ID or name."""
+        res = self._mcp_call("tools/call", {
+            "name": "get_tool_details",
+            "arguments": {"tool_id": tool_id}
+        })
+        return res if isinstance(res, dict) else {}
+
+    def get_cli_tools(self) -> List[Dict[str, Any]]:
+        """Fetch all CLI specific tools from LOCKTHARD."""
+        res = self._get("/api/cli-tools")
+        return res if isinstance(res, list) else []

lockthard_cli-0.1.0/lockthard_cli/config.py

@@ -0,0 +1,114 @@
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+DEFAULT_API_URL = "https://lockthard.es"
+CONFIG_DIR_NAME = ".lockthard"
+CREDENTIALS_FILE_NAME = "credentials.json"
+
+
+def get_config_dir() -> Path:
+    """Return the configuration directory path (~/.lockthard)."""
+    home = Path.home()
+    config_dir = home / CONFIG_DIR_NAME
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir
+
+
+def get_credentials_path() -> Path:
+    """Return the credentials file path (~/.lockthard/credentials.json)."""
+    return get_config_dir() / CREDENTIALS_FILE_NAME
+
+
+def load_credentials() -> Dict[str, Any]:
+    """Load credentials from ~/.lockthard/credentials.json if exists."""
+    path = get_credentials_path()
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def save_credentials(api_key: str, email: Optional[str] = None, api_url: Optional[str] = None) -> Path:
+    """Save credentials securely with restricted permissions (0600 on POSIX)."""
+    path = get_credentials_path()
+    data = load_credentials()
+    data["api_key"] = api_key.strip()
+    if email:
+        data["email"] = email
+    if api_url:
+        data["api_url"] = api_url.rstrip("/")
+
+    # Write json file
+    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    # Set 0600 permissions on POSIX
+    if os.name != "nt":
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+
+    return path
+
+
+def clear_credentials() -> bool:
+    """Remove the credentials file on logout."""
+    path = get_credentials_path()
+    if path.exists():
+        try:
+            path.unlink()
+            return True
+        except OSError:
+            return False
+    return False
+
+
+def resolve_token(token_flag: Optional[str] = None) -> Optional[str]:
+    """
+    Resolve API key token in precedence order:
+    1. Direct CLI argument / flag (--token)
+    2. Environment variable LOCKTHARD_API_KEY
+    3. Saved credentials (~/.lockthard/credentials.json)
+    """
+    if token_flag and token_flag.strip():
+        return token_flag.strip()
+
+    env_token = os.environ.get("LOCKTHARD_API_KEY")
+    if env_token and env_token.strip():
+        return env_token.strip()
+
+    creds = load_credentials()
+    saved_token = creds.get("api_key")
+    if saved_token and str(saved_token).strip():
+        return str(saved_token).strip()
+
+    return None
+
+
+def resolve_api_url(url_flag: Optional[str] = None) -> str:
+    """
+    Resolve API Base URL in precedence order:
+    1. Direct CLI argument / flag (--url)
+    2. Environment variable LOCKTHARD_API_URL
+    3. Saved credentials api_url
+    4. Default (https://lockthard.es)
+    """
+    if url_flag and url_flag.strip():
+        return url_flag.strip().rstrip("/")
+
+    env_url = os.environ.get("LOCKTHARD_API_URL")
+    if env_url and env_url.strip():
+        return env_url.strip().rstrip("/")
+
+    creds = load_credentials()
+    saved_url = creds.get("api_url")
+    if saved_url and str(saved_url).strip():
+        return str(saved_url).strip().rstrip("/")
+
+    return DEFAULT_API_URL

lockthard_cli-0.1.0/lockthard_cli/formatters.py

@@ -0,0 +1,269 @@
+import json
+import sys
+from typing import Any, List, Dict, Optional
+
+try:
+    from rich.console import Console
+    from rich.table import Table
+    from rich.panel import Panel
+    from rich.markdown import Markdown
+    from rich.text import Text
+    HAS_RICH = True
+except ImportError:
+    HAS_RICH = False
+
+console = Console() if HAS_RICH else None
+
+
+def output_data(data: Any, as_json: bool = False):
+    """Output raw JSON if requested or default printer."""
+    if as_json:
+        print(json.dumps(data, indent=2, default=str, ensure_ascii=False))
+    elif HAS_RICH and console:
+        if isinstance(data, (dict, list)):
+            console.print_json(json.dumps(data, default=str, ensure_ascii=False))
+        else:
+            console.print(data)
+    else:
+        print(data)
+
+
+def print_ping_result(data: Dict[str, Any], as_json: bool = False):
+    if as_json:
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    status = data.get("status")
+    auth = data.get("authenticated", False)
+
+    if HAS_RICH and console:
+        if status == "ok" and auth:
+            console.print("[bold green]✓ Servidor LOCKTHARD activo y token autenticado correctamente.[/bold green]")
+        elif status == "ok":
+            console.print("[bold yellow]! Servidor LOCKTHARD activo (Sesión no autenticada).[/bold yellow]")
+            console.print("[dim]Usa 'lockthard login' o exporta LOCKTHARD_API_KEY para autenticar.[/dim]")
+        else:
+            console.print(f"[bold red]✗ Error de conexión: {data.get('error', 'Desconocido')}[/bold red]")
+    else:
+        print(f"Status: {status} | Authenticated: {auth}")
+
+
+def print_tablets_list(tablets: List[Dict[str, Any]], as_json: bool = False):
+    if as_json:
+        print(json.dumps(tablets, indent=2, ensure_ascii=False))
+        return
+
+    if not tablets:
+        print("No se encontraron tablets.")
+        return
+
+    if HAS_RICH and console:
+        table = Table(title=f"LOCKTHARD Tablets ({len(tablets)})", show_header=True, header_style="bold magenta")
+        table.add_column("ID / Slug", style="cyan", no_wrap=True)
+        table.add_column("Título", style="bold white")
+        table.add_column("Categoría", style="yellow")
+        table.add_column("Herramientas", justify="right", style="green")
+
+        for t in tablets:
+            table.add_row(
+                str(t.get("id") or t.get("slug") or "-"),
+                str(t.get("title") or t.get("name") or "-"),
+                str(t.get("category") or "General"),
+                str(t.get("tool_count") or t.get("count") or len(t.get("items", [])))
+            )
+        console.print(table)
+    else:
+        for t in tablets:
+            print(f"[{t.get('id')}] {t.get('title')} ({t.get('tool_count', 0)} herramientas)")
+
+
+def print_search_results(query: str, results: List[Dict[str, Any]], as_json: bool = False):
+    if as_json:
+        print(json.dumps(results, indent=2, ensure_ascii=False))
+        return
+
+    if not results:
+        print(f"No se encontraron herramientas para '{query}'.")
+        return
+
+    if HAS_RICH and console:
+        table = Table(title=f"Resultados de búsqueda: '{query}' ({len(results)})", show_header=True, header_style="bold cyan")
+        table.add_column("Nombre", style="bold green")
+        table.add_column("Descripción", style="white")
+        table.add_column("URL / Repo", style="blue")
+        table.add_column("Tablet", style="dim magenta")
+
+        for r in results:
+            url = r.get("url") or r.get("href") or r.get("repo") or "-"
+            desc = r.get("description") or r.get("desc") or ""
+            if len(desc) > 80:
+                desc = desc[:77] + "..."
+            table.add_row(
+                str(r.get("name") or "-"),
+                desc,
+                str(url),
+                str(r.get("tablet_id") or r.get("category") or "-")
+            )
+        console.print(table)
+    else:
+        for r in results:
+            print(f"- {r.get('name')}: {r.get('description', '')} ({r.get('url', '')})")
+
+
+def print_tablet_content(tablet_data: Dict[str, Any], as_json: bool = False):
+    if as_json:
+        print(json.dumps(tablet_data, indent=2, ensure_ascii=False))
+        return
+
+    title = tablet_data.get("title") or tablet_data.get("name") or "Tablet"
+    items = tablet_data.get("items") or []
+
+    if HAS_RICH and console:
+        console.print(Panel(f"[bold white]{title}[/bold white]\n[dim]{tablet_data.get('description', '')}[/dim]", border_style="cyan"))
+        
+        if items:
+            table = Table(title=f"Herramientas en {title} ({len(items)})", show_header=True)
+            table.add_column("Nombre", style="bold green")
+            table.add_column("Descripción", style="white")
+            table.add_column("Enlace", style="blue")
+
+            for item in items:
+                desc = item.get("description") or item.get("desc") or ""
+                url = item.get("url") or item.get("href") or item.get("repo") or "-"
+                table.add_row(str(item.get("name") or "-"), desc, str(url))
+            console.print(table)
+        else:
+            console.print("[yellow]No hay herramientas registradas en esta tablet.[/yellow]")
+    else:
+        print(f"=== {title} ===")
+        for item in items:
+            print(f"- {item.get('name')}: {item.get('url')}")
+
+
+def print_tool_details(tool: Dict[str, Any], as_json: bool = False):
+    if as_json:
+        print(json.dumps(tool, indent=2, ensure_ascii=False))
+        return
+
+    if not tool:
+        print("Herramienta no encontrada.")
+        return
+
+    if HAS_RICH and console:
+        name = tool.get("name", "Desconocido")
+        desc = tool.get("description") or tool.get("desc") or ""
+        url = tool.get("url") or tool.get("href") or tool.get("repo") or ""
+        commands = tool.get("commands") or tool.get("command") or []
+
+        content = f"[bold green]{name}[/bold green]\n\n{desc}\n\n[bold blue]URL:[/bold blue] {url}"
+        if commands:
+            if isinstance(commands, list):
+                cmds_str = "\n".join([f"  $ {c}" for c in commands])
+            else:
+                cmds_str = f"  $ {commands}"
+            content += f"\n\n[bold yellow]Comandos recomendados:[/bold yellow]\n[cyan]{cmds_str}[/cyan]"
+
+        console.print(Panel(content, title="Detalles de Herramienta", border_style="green"))
+    else:
+        print(f"Nombre: {tool.get('name')}")
+        print(f"Descripción: {tool.get('description')}")
+        print(f"URL: {tool.get('url')}")
+
+
+def print_cli_tools(tools: List[Dict[str, Any]], as_json: bool = False):
+    if as_json:
+        print(json.dumps(tools, indent=2, ensure_ascii=False))
+        return
+
+    if HAS_RICH and console:
+        table = Table(title=f"Herramientas CLI ({len(tools)})", show_header=True, header_style="bold yellow")
+        table.add_column("Herramienta CLI", style="bold green")
+        table.add_column("Comando", style="cyan")
+        table.add_column("Descripción", style="white")
+
+        for t in tools:
+            cmd = t.get("command") or t.get("setup") or "-"
+            if isinstance(cmd, list):
+                cmd = " | ".join(cmd[:2])
+            table.add_row(str(t.get("name") or "-"), str(cmd), str(t.get("description") or "-"))
+        console.print(table)
+    else:
+        for t in tools:
+            print(f"[{t.get('name')}] {t.get('command')} - {t.get('description')}")
+
+
+def print_agent_guide():
+    guide_md = """
+# LOCKTHARD CLI - Guía para Agentes de IA
+
+Bienvenido a la CLI de **LOCKTHARD**. Esta interfaz permite a Agentes de IA (Claude Code, Antigravity, Aider, Cursor) consultar la base de datos de 1200+ herramientas IA con mínimo consumo de tokens.
+
+## Buenas Prácticas para Agentes
+
+1. **Usa el flag `--json` (o `-j`):** 
+   Devuelve datos limpios y estructurados en JSON en lugar de tablas formateadas con ANSI.
+   ```bash
+   lockthard search "ocr" --json
+   ```
+
+2. **Flujo de Trabajo Recomendado:**
+   - `lockthard ping`: Verificar conexión y autenticación.
+   - `lockthard tablets list`: Ver todos los tablets y categorías disponibles.
+   - `lockthard search "<termino>"`: Buscar herramientas por palabras clave.
+   - `lockthard tablets get <id>`: Obtener todas las herramientas de un tablet específico.
+   - `lockthard tools get "<nombre>"`: Ver detalles y comandos exactos de una herramienta.
+
+3. **Autenticación en Agentes:**
+   Define la variable de entorno `LOCKTHARD_API_KEY`:
+   ```bash
+   export LOCKTHARD_API_KEY="lk_tu_token_aqui"
+   ```
+"""
+    if HAS_RICH and console:
+        console.print(Markdown(guide_md))
+    else:
+        print(guide_md)
+
+
+def print_agent_skill():
+    skill_content = """---
+name: lockthard
+description: "Scriptable CLI and AI agent client for LOCKTHARD (lockthard.es). Allows searching 2100+ AI tools, exploring 81+ tablets, retrieving tool installation commands, and inspecting tool details with minimum token overhead."
+version: 0.1.0
+---
+
+# LOCKTHARD CLI - Agent Skill Guide
+
+Use this CLI to query the LOCKTHARD AI tools directory, find specific tools, get installation/setup commands, and browse tablets.
+
+## Authentication
+Set the environment variable `LOCKTHARD_API_KEY`:
+```bash
+export LOCKTHARD_API_KEY="lk_your_token"
+```
+
+## Recommended Workflow for AI Agents
+Always use the `--json` (`-j`) flag to receive clean JSON output.
+
+1. **Verify status:** `lockthard ping`
+2. **Search tools:** `lockthard search "ocr" --json`
+3. **List all tablets:** `lockthard tablets list --json`
+4. **Get tablet tools:** `lockthard tablets get ocr --json`
+5. **Get tool details:** `lockthard tools get "Chandra OCR" --json`
+6. **List CLI tools:** `lockthard cli-tools --json`
+
+## Commands Reference
+
+| Command | Description | Example |
+|---|---|---|
+| `lockthard ping` | Check connection & auth status | `lockthard ping` |
+| `lockthard search <query>` | Search 2100+ tools | `lockthard search "ocr" -j` |
+| `lockthard tablets list` | List 81+ tablets | `lockthard tablets list -j` |
+| `lockthard tablets get <id>` | Inspect tablet content | `lockthard tablets get open-source -j` |
+| `lockthard tools get <id>` | Detailed tool info & CLI commands | `lockthard tools get "copilotkit" -j` |
+| `lockthard cli-tools` | List dedicated CLI tools | `lockthard cli-tools -j` |
+| `lockthard guide` | Show agent guide | `lockthard guide` |
+| `lockthard skill` | Output this SKILL.md definition | `lockthard skill` |
+"""
+    print(skill_content)
+

lockthard_cli-0.1.0/lockthard_cli.egg-info/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: lockthard-cli
+Version: 0.1.0
+Summary: Super efficient CLI for LOCKTHARD AI tools directory and agents
+Author-email: Lockthard Team <info@lockthard.es>
+License: MIT
+Project-URL: Homepage, https://lockthard.es
+Keywords: cli,ai-tools,agents,mcp,lockthard
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=13.0.0
+
+# LOCKTHARD CLI (`lockthard`)
+
+A super efficient, scriptable command-line interface and AI agent client for **LOCKTHARD** (https://lockthard.es).
+
+Allows both human developers and autonomous AI agents (Claude Code, Antigravity, Aider, Cursor, etc.) to query, search, and inspect 61+ tablets and 1200+ AI tools with minimum token usage and zero prompt overhead.
+
+## Installation
+
+```bash
+pip install lockthard-cli
+```
+
+Or run without installing:
+
+```bash
+pipx run lockthard-cli --help
+```
+
+## Quick Start
+
+### 1. Authentication
+Get your API key from [lockthard.es](https://lockthard.es).
+
+- **For AI Agents & CI/CD:**
+  ```bash
+  export LOCKTHARD_API_KEY="lk_your_token_here"
+  ```
+- **Interactive Browser Login (Humans):**
+  ```bash
+  lockthard login
+  ```
+- **Manual Login:**
+  ```bash
+  lockthard login --token "lk_your_token_here"
+  ```
+
+### 2. Commands
+
+```bash
+# Ping service
+lockthard ping
+
+# Search tools (returns concise ASCII table)
+lockthard search "ocr"
+
+# Search tools in raw JSON (for agents / jq)
+lockthard search "ocr" --json
+
+# List all tablets
+lockthard tablets list
+
+# Inspect a specific tablet
+lockthard tablets get ocr
+
+# Inspect tool details
+lockthard tools get "Chandra OCR"
+
+# Display CLI agent guide
+lockthard guide
+```
+
+## Options
+
+- `--json` / `-j`: Output raw JSON without Rich styling.
+- `--url` / `-u`: Override base server URL (default: `https://lockthard.es`).
+- `--token` / `-t`: Override API token.
+
+## License
+
+MIT License

lockthard_cli-0.1.0/lockthard_cli.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+lockthard_cli/__init__.py
+lockthard_cli/auth.py
+lockthard_cli/cli.py
+lockthard_cli/client.py
+lockthard_cli/config.py
+lockthard_cli/formatters.py
+lockthard_cli.egg-info/PKG-INFO
+lockthard_cli.egg-info/SOURCES.txt
+lockthard_cli.egg-info/dependency_links.txt
+lockthard_cli.egg-info/entry_points.txt
+lockthard_cli.egg-info/requires.txt
+lockthard_cli.egg-info/top_level.txt
+tests/test_cli.py

lockthard_cli-0.1.0/lockthard_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lockthard_cli-0.1.0/lockthard_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lockthard = lockthard_cli.cli:main

lockthard_cli-0.1.0/lockthard_cli.egg-info/requires.txt

@@ -0,0 +1,3 @@
+click>=8.1.0
+requests>=2.28.0
+rich>=13.0.0

lockthard_cli-0.1.0/lockthard_cli.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+lockthard_cli
+tests

lockthard_cli-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lockthard-cli"
+version = "0.1.0"
+description = "Super efficient CLI for LOCKTHARD AI tools directory and agents"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Lockthard Team", email = "info@lockthard.es" }
+]
+keywords = ["cli", "ai-tools", "agents", "mcp", "lockthard"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities"
+]
+dependencies = [
+    "click>=8.1.0",
+    "requests>=2.28.0",
+    "rich>=13.0.0"
+]
+
+[project.urls]
+Homepage = "https://lockthard.es"
+
+[project.scripts]
+lockthard = "lockthard_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]

lockthard_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lockthard_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,18 @@
+import pytest
+from click.testing import CliRunner
+from lockthard_cli.cli import cli
+from lockthard_cli import __version__
+
+
+def test_cli_version():
+    runner = CliRunner()
+    result = runner.invoke(cli, ["--version"])
+    assert result.exit_code == 0
+    assert __version__ in result.output
+
+
+def test_cli_guide():
+    runner = CliRunner()
+    result = runner.invoke(cli, ["guide"])
+    assert result.exit_code == 0
+    assert "Guía para Agentes de IA" in result.output or "LOCKTHARD CLI" in result.output