irides-cli 0.1.0__tar.gz

irides_cli-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: irides-cli
+Version: 0.1.0
+Summary: A command-line interface for discovering, inspecting, and managing structured database context for AI systems.
+Author-email: Gian Andrea Sechi <me@gianandreasechi.com>
+License: Apache-2.0
+Project-URL: Source Code, https://github.com/GianAndreaSechi/irides/cli
+Project-URL: Homepage, https://www.gianandreasechi.com
+Keywords: database,introspection,cli,irides,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: irides-core>=0.1.0
+
+# Iride CLI
+
+Command-line interface for database introspection, built only on the `core` package and Python's standard library. It does not require FastAPI, MCP, or the Redis worker.
+
+## Structure
+
+The CLI is organized by responsibility:
+
+- `irides_cli/presentation/`: command definitions and `argparse` parsing;
+- `irides_cli/controllers/`: maps command-line arguments to use cases;
+- `irides_cli/dto/`: immutable, typed request DTOs;
+- `irides_cli/services/`: live introspection and metadata operations using only `core`;
+- `irides_cli/main.py`: composition root, JSON serialization, and process-level error handling.
+
+## Local installation
+
+```bash
+pip install -e ./core -e ./cli
+```
+
+## Quickstart & Configuration
+
+Irides supports two ways to configure database targets:
+
+### Option 1: Declarative Config File (`irides.yaml`) — Recommended
+Generate a template configuration with:
+```bash
+irides init
+```
+This creates an `irides.yaml` file in the current directory:
+```yaml
+targets:
+  my_postgres:
+    type: postgres
+    host: localhost
+    port: 5432
+    user: postgres
+    password: "${PG_PASSWORD:-secret}"
+    database: my_database
+
+  local_sqlite:
+    type: sqlite
+    database: ./app.db
+```
+You can pass a custom config file anytime using `-c` / `--config-file`:
+```bash
+irides -c /path/to/my_config.yaml configurations
+```
+
+### Option 2: Environment Variables (`.env`)
+You can initialize an environment template with:
+```bash
+irides init --format env
+```
+Or specify an explicit `.env` file via `-e` / `--env-file`:
+```bash
+irides -e /path/to/.env configurations
+```
+
+## Commands
+
+```bash
+# Initialize template configuration
+irides init
+
+# List configured database targets
+irides configurations
+
+# Test database connection
+irides connect my_postgres
+
+# List database instances
+irides instances --target my_postgres
+
+# List schemas in a database
+irides schemas --target my_postgres --instance localhost
+
+# List tables (supports --limit and --offset)
+irides tables --target my_postgres --instance localhost --schema public --limit 50
+
+# Introspect table schema
+irides describe --target my_postgres --instance localhost --schema public --table orders
+irides describe --target my_postgres --instance localhost --schema public --table orders --generate-ai-docs
+irides describe --target my_postgres --instance localhost --schema public --table orders --no-export-okf
+```
+
+> **Note**: `--target` and `--config` are interchangeable aliases.
+Omitting `--target`, `--instance`, `--schema`, or `--table` expands the scope, just like the corresponding API endpoints. Results are always written as JSON to stdout; errors are written to stderr. Add `--no-cache` to introspection commands to bypass Redis.
+
+`describe` saves canonical JSON metadata and generates both **Markdown** and **Open Knowledge Format (OKF v0.2)** exports by default.
+
+Available options for `describe`:
+- `--generate-ai-docs`: generate domain summary and column descriptions via LiteLLM.
+- `--no-save-metadata`: skip saving the canonical JSON metadata file (exports are still generated if enabled).
+- `--only-if-changed`: skip writing if the schema is identical to the stored version.
+- `--no-export-markdown`: disable the default Markdown export.
+- `--no-export-okf`: disable the default OKF catalog bundle generation.
+- `--no-preformat`: export full metadata instead of the essential deterministic record.
+- `--save-markdown`: legacy compatibility flag for Markdown export.
+
+Artifacts are persisted under `STORAGE_EXPORT_DIR` (default `storage/exports`):
+- `storage/exports/markdown/{config}/{instance}/{schema}/{table}.md`
+- `storage/exports/okf/catalog/{config}/{instance}/{schema}/{table}.md` (along with `storage/exports/okf/catalog/index.md`)
+
+## Metadata
+
+```bash
+irides metadata instances
+irides metadata databases db1.company.com
+irides metadata tables db1.company.com production
+irides metadata get db1.company.com production orders
+irides metadata update db1.company.com production orders '{"owner":"data-team","tags":["billing"]}'
+```
+
+The CLI does not include `scan` commands. They are asynchronous and explicitly require Redis Streams and the `worker` service.
+
+## Docker
+
+The CLI reads its configuration from `cli/.env` and uses the shared Redis network. Start by copying `.env.example` as shown above and configure at least one `DB_TARGETS` entry.
+
+```bash
+docker compose -f infra/docker-compose.infra.yml up -d
+docker compose -f cli/docker-compose.yml run --rm irides-cli configurations
+docker compose -f cli/docker-compose.yml run --rm irides-cli tables --config sales_mysql --schema public
+docker compose -f cli/docker-compose.yml run --rm irides-cli describe --config sales_mysql --schema public --table orders
+```

irides_cli-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Iride CLI
+
+Command-line interface for database introspection, built only on the `core` package and Python's standard library. It does not require FastAPI, MCP, or the Redis worker.
+
+## Structure
+
+The CLI is organized by responsibility:
+
+- `irides_cli/presentation/`: command definitions and `argparse` parsing;
+- `irides_cli/controllers/`: maps command-line arguments to use cases;
+- `irides_cli/dto/`: immutable, typed request DTOs;
+- `irides_cli/services/`: live introspection and metadata operations using only `core`;
+- `irides_cli/main.py`: composition root, JSON serialization, and process-level error handling.
+
+## Local installation
+
+```bash
+pip install -e ./core -e ./cli
+```
+
+## Quickstart & Configuration
+
+Irides supports two ways to configure database targets:
+
+### Option 1: Declarative Config File (`irides.yaml`) — Recommended
+Generate a template configuration with:
+```bash
+irides init
+```
+This creates an `irides.yaml` file in the current directory:
+```yaml
+targets:
+  my_postgres:
+    type: postgres
+    host: localhost
+    port: 5432
+    user: postgres
+    password: "${PG_PASSWORD:-secret}"
+    database: my_database
+
+  local_sqlite:
+    type: sqlite
+    database: ./app.db
+```
+You can pass a custom config file anytime using `-c` / `--config-file`:
+```bash
+irides -c /path/to/my_config.yaml configurations
+```
+
+### Option 2: Environment Variables (`.env`)
+You can initialize an environment template with:
+```bash
+irides init --format env
+```
+Or specify an explicit `.env` file via `-e` / `--env-file`:
+```bash
+irides -e /path/to/.env configurations
+```
+
+## Commands
+
+```bash
+# Initialize template configuration
+irides init
+
+# List configured database targets
+irides configurations
+
+# Test database connection
+irides connect my_postgres
+
+# List database instances
+irides instances --target my_postgres
+
+# List schemas in a database
+irides schemas --target my_postgres --instance localhost
+
+# List tables (supports --limit and --offset)
+irides tables --target my_postgres --instance localhost --schema public --limit 50
+
+# Introspect table schema
+irides describe --target my_postgres --instance localhost --schema public --table orders
+irides describe --target my_postgres --instance localhost --schema public --table orders --generate-ai-docs
+irides describe --target my_postgres --instance localhost --schema public --table orders --no-export-okf
+```
+
+> **Note**: `--target` and `--config` are interchangeable aliases.
+Omitting `--target`, `--instance`, `--schema`, or `--table` expands the scope, just like the corresponding API endpoints. Results are always written as JSON to stdout; errors are written to stderr. Add `--no-cache` to introspection commands to bypass Redis.
+
+`describe` saves canonical JSON metadata and generates both **Markdown** and **Open Knowledge Format (OKF v0.2)** exports by default.
+
+Available options for `describe`:
+- `--generate-ai-docs`: generate domain summary and column descriptions via LiteLLM.
+- `--no-save-metadata`: skip saving the canonical JSON metadata file (exports are still generated if enabled).
+- `--only-if-changed`: skip writing if the schema is identical to the stored version.
+- `--no-export-markdown`: disable the default Markdown export.
+- `--no-export-okf`: disable the default OKF catalog bundle generation.
+- `--no-preformat`: export full metadata instead of the essential deterministic record.
+- `--save-markdown`: legacy compatibility flag for Markdown export.
+
+Artifacts are persisted under `STORAGE_EXPORT_DIR` (default `storage/exports`):
+- `storage/exports/markdown/{config}/{instance}/{schema}/{table}.md`
+- `storage/exports/okf/catalog/{config}/{instance}/{schema}/{table}.md` (along with `storage/exports/okf/catalog/index.md`)
+
+## Metadata
+
+```bash
+irides metadata instances
+irides metadata databases db1.company.com
+irides metadata tables db1.company.com production
+irides metadata get db1.company.com production orders
+irides metadata update db1.company.com production orders '{"owner":"data-team","tags":["billing"]}'
+```
+
+The CLI does not include `scan` commands. They are asynchronous and explicitly require Redis Streams and the `worker` service.
+
+## Docker
+
+The CLI reads its configuration from `cli/.env` and uses the shared Redis network. Start by copying `.env.example` as shown above and configure at least one `DB_TARGETS` entry.
+
+```bash
+docker compose -f infra/docker-compose.infra.yml up -d
+docker compose -f cli/docker-compose.yml run --rm irides-cli configurations
+docker compose -f cli/docker-compose.yml run --rm irides-cli tables --config sales_mysql --schema public
+docker compose -f cli/docker-compose.yml run --rm irides-cli describe --config sales_mysql --schema public --table orders
+```

irides_cli-0.1.0/irides_cli/__init__.py

@@ -0,0 +1,2 @@
+"""Command-line interface for Iride's core introspection library."""
+

irides_cli-0.1.0/irides_cli/controllers/__init__.py

@@ -0,0 +1,2 @@
+"""Adapters between the command-line presentation layer and services."""
+

irides_cli-0.1.0/irides_cli/controllers/init_controller.py

@@ -0,0 +1,78 @@
+"""Controller for initializing configuration templates."""
+
+import os
+from pathlib import Path
+from typing import Any, Dict
+
+
+SAMPLE_YAML = """# irides.yaml - Irides database configuration file
+# Learn more: https://github.com/GianAndreaSechi/irides
+
+targets:
+  # SQLite example (no server needed)
+  # local_sqlite:
+  #   type: sqlite
+  #   database: ./data.db
+
+  # PostgreSQL example
+  # my_postgres:
+  #   type: postgres
+  #   host: localhost
+  #   port: 5432
+  #   user: postgres
+  #   password: "${PG_PASSWORD:-postgres}"
+  #   database: my_database
+
+  # MySQL example
+  # my_mysql:
+  #   type: mysql
+  #   host: localhost
+  #   port: 3306
+  #   user: root
+  #   password: "${MYSQL_PASSWORD}"
+
+  # MongoDB example
+  # my_mongo:
+  #   type: mongodb
+  #   host: localhost
+  #   port: 27017
+  #   username: admin
+  #   password: "${MONGO_PASSWORD}"
+  #   authSource: admin
+"""
+
+SAMPLE_ENV = """# .env - Irides environment configuration
+# Learn more: https://github.com/GianAndreaSechi/irides
+
+DB_TARGETS=sample_pg
+
+# PostgreSQL sample target
+DB_TARGET_SAMPLE_PG_TYPE=postgres
+DB_TARGET_SAMPLE_PG_HOST=localhost
+DB_TARGET_SAMPLE_PG_PORT=5432
+DB_TARGET_SAMPLE_PG_USER=postgres
+DB_TARGET_SAMPLE_PG_PASSWORD=secret
+DB_TARGET_SAMPLE_PG_DATABASE=my_database
+"""
+
+
+class InitController:
+    """Handles the 'init' CLI command."""
+
+    def execute(self, fmt: str = "yaml", force: bool = False) -> Dict[str, Any]:
+        target_filename = "irides.yaml" if fmt == "yaml" else ".env"
+        target_path = Path(target_filename)
+
+        if target_path.exists() and not force:
+            raise ValueError(
+                f"'{target_filename}' already exists. Use --force to overwrite."
+            )
+
+        content = SAMPLE_YAML if fmt == "yaml" else SAMPLE_ENV
+        target_path.write_text(content, encoding="utf-8")
+
+        return {
+            "status": "created",
+            "file": target_filename,
+            "message": f"Template created at '{target_filename}'. Edit your database credentials and run 'irides configurations'.",
+        }

irides_cli-0.1.0/irides_cli/controllers/introspection_controller.py

@@ -0,0 +1,34 @@
+"""Controller that maps parsed CLI arguments into introspection DTOs."""
+
+import argparse
+from typing import Any
+
+from irides_cli.dto.requests import DescribeRequest, ScopeRequest, TablesRequest
+from irides_cli.services.introspection_service import IntrospectionService
+
+
+class IntrospectionController:
+    def __init__(self, service: IntrospectionService | None = None, config_file: str | None = None) -> None:
+        self.service = service or IntrospectionService(config_file=config_file)
+
+    def execute(self, args: argparse.Namespace) -> Any:
+        if args.command == "configurations": return self.service.configurations()
+        if args.command == "connect": return self.service.connect(args.config_name)
+        if args.command == "instances": return self.service.instances(ScopeRequest(config_name=args.config_name, no_cache=args.no_cache))
+        if args.command == "schemas": return self.service.schemas(ScopeRequest(args.config_name, args.instance_name, args.no_cache))
+        if args.command == "tables": return self.service.tables(TablesRequest(args.config_name, args.instance_name, args.no_cache, args.schema_name, args.limit, args.offset))
+        return self.service.describe(
+            DescribeRequest(
+                config_name=args.config_name,
+                instance_name=args.instance_name,
+                no_cache=args.no_cache,
+                schema_name=args.schema_name,
+                table_name=args.table_name,
+                generate_ai_docs=args.generate_ai_docs,
+                save_metadata=args.save_metadata,
+                only_if_changed=args.only_if_changed,
+                export_markdown=args.export_markdown,
+                export_okf=args.export_okf,
+                preformat=args.preformat,
+            )
+        )

irides_cli-0.1.0/irides_cli/controllers/metadata_controller.py

@@ -0,0 +1,23 @@
+"""Controller for metadata commands and payload validation."""
+
+import argparse
+import json
+from typing import Any
+
+from irides_cli.dto.requests import MetadataUpdateRequest, PageRequest
+from irides_cli.services.metadata_service import MetadataService
+
+
+class MetadataController:
+    def __init__(self, service: MetadataService | None = None) -> None:
+        self.service = service or MetadataService()
+
+    def execute(self, args: argparse.Namespace) -> Any:
+        page = PageRequest(args.page, args.page_size) if hasattr(args, "page") else None
+        if args.metadata_command == "instances": return self.service.instances(page)
+        if args.metadata_command == "databases": return self.service.databases(args.instance, page)
+        if args.metadata_command == "tables": return self.service.tables(args.instance, args.database, page)
+        if args.metadata_command == "get": return self.service.get(args.instance, args.database, args.table)
+        payload = json.loads(args.payload)
+        if not isinstance(payload, dict): raise ValueError("Metadata payload must be a JSON object.")
+        return self.service.update(MetadataUpdateRequest(args.instance, args.database, args.table, payload))

irides_cli-0.1.0/irides_cli/dto/__init__.py

@@ -0,0 +1,2 @@
+"""Input DTOs used by CLI controllers and services."""
+

irides_cli-0.1.0/irides_cli/dto/requests.py

@@ -0,0 +1,43 @@
+"""Typed command inputs, independent from argparse and core models."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class ScopeRequest:
+    config_name: Optional[str] = None
+    instance_name: Optional[str] = None
+    no_cache: bool = False
+
+
+@dataclass(frozen=True)
+class TablesRequest(ScopeRequest):
+    schema_name: Optional[str] = None
+    limit: Optional[int] = None
+    offset: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class DescribeRequest(TablesRequest):
+    table_name: Optional[str] = None
+    generate_ai_docs: bool = False
+    save_metadata: bool = True
+    only_if_changed: bool = False
+    export_markdown: bool = True
+    export_okf: bool = True
+    preformat: bool = True
+
+
+@dataclass(frozen=True)
+class PageRequest:
+    page: int = 1
+    page_size: int = 20
+
+
+@dataclass(frozen=True)
+class MetadataUpdateRequest:
+    instance_name: str
+    database_name: str
+    table_name: str
+    payload: Dict[str, Any]

irides_cli-0.1.0/irides_cli/main.py

@@ -0,0 +1,62 @@
+"""CLI composition root and process-level error handling."""
+
+import json
+import sys
+from typing import Any, List, Optional
+from dotenv import load_dotenv
+
+from irides_cli.controllers.init_controller import InitController
+from irides_cli.controllers.introspection_controller import IntrospectionController
+from irides_cli.controllers.metadata_controller import MetadataController
+from irides_cli.presentation.parser import build_parser
+
+
+def _json_default(value: Any) -> Any:
+    if hasattr(value, "model_dump"): return value.model_dump(mode="json")
+    if hasattr(value, "dict"): return value.dict()
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def print_json(data: Any) -> None:
+    print(json.dumps(data, default=_json_default, ensure_ascii=False, indent=2))
+
+
+def run(args: Any) -> Any:
+    if args.command == "init":
+        return InitController().execute(fmt=args.format, force=args.force)
+    if args.command == "metadata":
+        return MetadataController().execute(args)
+
+    config_file = getattr(args, "config_file", None)
+    controller = IntrospectionController(config_file=config_file)
+    result = controller.execute(args)
+    if args.command == "configurations" and isinstance(result, list) and len(result) == 0:
+        print(
+            "irides: notice: no database targets configured. Run 'irides init' to generate a configuration template or check your .env.",
+            file=sys.stderr,
+        )
+    return result
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    env_file = getattr(args, "env_file", None)
+    if env_file:
+        load_dotenv(dotenv_path=env_file, override=True)
+
+    try:
+        result = run(args)
+        if result is None: raise ValueError("No metadata found.")
+        print_json(result)
+        return 0
+    except (ConnectionError, ValueError, json.JSONDecodeError) as error:
+        print(f"irides: {error}", file=sys.stderr)
+        return 1
+    except Exception as error:
+        print(f"irides: unexpected error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

irides_cli-0.1.0/irides_cli/presentation/__init__.py

@@ -0,0 +1,2 @@
+"""Command-line input and output adapters."""
+

irides_cli-0.1.0/irides_cli/presentation/parser.py

@@ -0,0 +1,47 @@
+"""Argparse command definitions; no business logic belongs here."""
+
+import argparse
+
+
+def _add_scope_arguments(parser: argparse.ArgumentParser, *, table: bool = False) -> None:
+    parser.add_argument("-t", "--target", "--config", dest="config_name", help="Configured database target name")
+    parser.add_argument("--instance", dest="instance_name", help="Database instance")
+    if table: parser.add_argument("--schema", dest="schema_name", help="Schema/database name")
+    parser.add_argument("--no-cache", action="store_true", help="Bypass the Redis cache")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="irides", description="Inspect databases through Irides core, without the API service.")
+    parser.add_argument("-e", "--env-file", dest="env_file", help="Path to .env file to load variables from")
+    parser.add_argument("-c", "--config-file", dest="config_file", help="Path to YAML/JSON configuration file (e.g. irides.yaml)")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_cmd = subparsers.add_parser("init", help="Initialize a template configuration file (irides.yaml or .env)")
+    init_cmd.add_argument("-f", "--format", choices=["yaml", "env"], default="yaml", help="Config format: yaml (default) or env")
+    init_cmd.add_argument("--force", action="store_true", help="Overwrite existing configuration file")
+
+    subparsers.add_parser("configurations", help="List active configurations")
+    connect = subparsers.add_parser("connect", help="Test a configuration")
+    connect.add_argument("config_name", metavar="TARGET", help="Database target name to connect to")
+    instances = subparsers.add_parser("instances", help="List instances")
+    instances.add_argument("-t", "--target", "--config", dest="config_name", help="Configured database target name")
+    instances.add_argument("--no-cache", action="store_true")
+    schemas = subparsers.add_parser("schemas", help="List schemas"); _add_scope_arguments(schemas)
+    tables = subparsers.add_parser("tables", help="List tables"); _add_scope_arguments(tables, table=True); tables.add_argument("--limit", type=int); tables.add_argument("--offset", type=int)
+    describe = subparsers.add_parser("describe", help="Describe tables and optionally save metadata")
+    _add_scope_arguments(describe, table=True); describe.add_argument("--table", dest="table_name")
+    describe.add_argument("--generate-ai-docs", action="store_true"); describe.add_argument("--no-save-metadata", dest="save_metadata", action="store_false", default=True); describe.add_argument("--only-if-changed", action="store_true")
+    describe.add_argument("--no-export-markdown", dest="export_markdown", action="store_false", default=True, help="Do not generate the default Markdown export")
+    describe.add_argument("--save-markdown", dest="export_markdown", action="store_true", help=argparse.SUPPRESS)
+    describe.add_argument("--no-export-okf", dest="export_okf", action="store_false", default=True, help="Do not generate the default OKF bundle")
+    describe.add_argument("--no-preformat", dest="preformat", action="store_false", default=True, help="Export the full metadata instead of the essential view")
+    metadata = subparsers.add_parser("metadata", help="Read or update stored metadata"); metadata_sub = metadata.add_subparsers(dest="metadata_command", required=True)
+    for name in ("instances", "databases", "tables"):
+        command = metadata_sub.add_parser(name)
+        if name != "instances": command.add_argument("instance")
+        if name == "tables": command.add_argument("database")
+        command.add_argument("--page", type=int, default=1); command.add_argument("--page-size", type=int, default=20)
+    get = metadata_sub.add_parser("get"); get.add_argument("instance"); get.add_argument("database"); get.add_argument("table")
+    update = metadata_sub.add_parser("update"); update.add_argument("instance"); update.add_argument("database"); update.add_argument("table"); update.add_argument("payload", help="JSON object to merge into the metadata")
+    return parser

irides_cli-0.1.0/irides_cli/services/__init__.py

@@ -0,0 +1,2 @@
+"""Application services for the CLI."""
+

irides_cli-0.1.0/irides_cli/services/introspection_service.py

@@ -0,0 +1,94 @@
+"""Core-backed synchronous database introspection use cases."""
+
+import os
+from typing import Any, Dict, Iterable, List
+
+from core.db_connector.ai_service import AIDocumentationService
+from core.db_connector.cache_manager import CacheManager
+from core.db_connector.config_service import ConfigService
+from core.db_connector.manager import ConnectorManager
+from core.db_connector.models import Schema, Table
+from core.db_connector.storage import get_metadata_store
+from core.db_connector.exporting import ExportFormat, ExportOptions
+
+from irides_cli.dto.requests import DescribeRequest, ScopeRequest, TablesRequest
+
+
+class IntrospectionService:
+    """Runs live introspection without any dependency on API-layer code."""
+
+    def __init__(self, config_service: ConfigService | None = None, config_file: str | None = None) -> None:
+        if config_service is None:
+            cache = CacheManager(
+                host=os.getenv("REDIS_HOST", "localhost"),
+                port=int(os.getenv("REDIS_PORT", "6379")),
+                db=int(os.getenv("REDIS_DB", "0")),
+                ttl_seconds=int(os.getenv("REDIS_TTL_SECONDS", "86400")),
+                socket_connect_timeout=float(os.getenv("REDIS_SOCKET_CONNECT_TIMEOUT_SECONDS", "2")),
+                socket_timeout=float(os.getenv("REDIS_CACHE_SOCKET_TIMEOUT_SECONDS", "2")),
+            )
+            config_service = ConfigService(ConnectorManager(cache), config_file=config_file)
+        self.config_service = config_service
+
+    def configurations(self) -> List[str]:
+        return self.config_service.get_available_configurations()
+
+    def connect(self, config_name: str) -> Dict[str, Any]:
+        return self.config_service.test_connection(config_name)
+
+    def instances(self, request: ScopeRequest) -> List[Any]:
+        names = [request.config_name] if request.config_name else self.configurations()
+        return [instance for name in names for instance in self.config_service.list_instances(name, no_cache=request.no_cache)]
+
+    def _scope(self, request: ScopeRequest) -> Iterable[tuple[str, str, Any]]:
+        configs = [request.config_name] if request.config_name else self.configurations()
+        for config in configs:
+            for instance in self.config_service.resolve_instance_names(config, request.instance_name, request.no_cache):
+                yield config, instance, self.config_service._get_connector_for_host(config, instance)
+
+    def schemas(self, request: ScopeRequest) -> List[Any]:
+        return [schema for _, instance, connector in self._scope(request) for schema in connector.list_schemas(instance_name=instance, no_cache=request.no_cache)]
+
+    def tables(self, request: TablesRequest) -> List[Any]:
+        found = []
+        for _, instance, connector in self._scope(request):
+            schemas = [Schema(name=request.schema_name)] if request.schema_name else connector.list_schemas(instance_name=instance, no_cache=request.no_cache)
+            for schema in schemas:
+                found.extend(connector.list_tables(instance_name=instance, schema_name=schema.name, limit=request.limit, offset=request.offset, no_cache=request.no_cache))
+        return found
+
+    def describe(self, request: DescribeRequest) -> List[Any]:
+        results = []
+        formats = []
+        if request.export_markdown:
+            formats.append(ExportFormat.MARKDOWN)
+        if request.export_okf:
+            formats.append(ExportFormat.OKF)
+        export_options = ExportOptions(formats=formats, preformat=request.preformat)
+        store = get_metadata_store() if request.save_metadata or formats else None
+        ai_service = AIDocumentationService() if request.generate_ai_docs else None
+        for config, instance, connector in self._scope(request):
+            schemas = [Schema(name=request.schema_name)] if request.schema_name else connector.list_schemas(instance_name=instance, no_cache=request.no_cache)
+            for schema in schemas:
+                tables = [Table(name=request.table_name, schema_name=schema.name)] if request.table_name else connector.list_tables(instance_name=instance, schema_name=schema.name, no_cache=request.no_cache)
+                for table in tables:
+                    description = connector.describe_table(instance_name=instance, schema_name=schema.name, table_name=table.name, no_cache=request.no_cache)
+                    schema_description = description.model_dump(exclude={"ai_documentation", "ai_generation_status", "ai_generation_error"})
+                    ai_documentation = None
+                    if ai_service:
+                        ai_documentation = ai_service.generate_table_documentation(schema_description)
+                        description = description.model_copy(update={"ai_documentation": ai_documentation, "ai_generation_status": "generated" if ai_documentation else "failed", "ai_generation_error": None if ai_documentation else ai_service.last_error})
+                    results.append(description)
+                    if store:
+                        store.save_table_metadata(
+                            config,
+                            instance,
+                            schema.name,
+                            table.name,
+                            schema_description,
+                            ai_documentation,
+                            only_if_changed=request.only_if_changed,
+                            export_options=export_options,
+                            save_metadata=request.save_metadata,
+                        )
+        return results

irides_cli-0.1.0/irides_cli/services/metadata_service.py

@@ -0,0 +1,27 @@
+"""Operations over metadata persisted by core."""
+
+from typing import Any, Dict, Optional
+
+from core.db_connector.storage import BaseMetadataStore, get_metadata_store
+
+from irides_cli.dto.requests import MetadataUpdateRequest, PageRequest
+
+
+class MetadataService:
+    def __init__(self, store: Optional[BaseMetadataStore] = None) -> None:
+        self.store = store or get_metadata_store()
+
+    def instances(self, page: PageRequest) -> Dict[str, Any]:
+        return self.store.list_instances(page.page, page.page_size)
+
+    def databases(self, instance_name: str, page: PageRequest) -> Dict[str, Any]:
+        return self.store.list_databases(instance_name, page.page, page.page_size)
+
+    def tables(self, instance_name: str, database_name: str, page: PageRequest) -> Dict[str, Any]:
+        return self.store.list_tables_metadata(instance_name, database_name, page.page, page.page_size)
+
+    def get(self, instance_name: str, database_name: str, table_name: str) -> Optional[Dict[str, Any]]:
+        return self.store.find_table_metadata(instance_name, database_name, table_name)
+
+    def update(self, request: MetadataUpdateRequest) -> Optional[Dict[str, Any]]:
+        return self.store.update_table_metadata(request.instance_name, request.database_name, request.table_name, request.payload)

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

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: irides-cli
+Version: 0.1.0
+Summary: A command-line interface for discovering, inspecting, and managing structured database context for AI systems.
+Author-email: Gian Andrea Sechi <me@gianandreasechi.com>
+License: Apache-2.0
+Project-URL: Source Code, https://github.com/GianAndreaSechi/irides/cli
+Project-URL: Homepage, https://www.gianandreasechi.com
+Keywords: database,introspection,cli,irides,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: irides-core>=0.1.0
+
+# Iride CLI
+
+Command-line interface for database introspection, built only on the `core` package and Python's standard library. It does not require FastAPI, MCP, or the Redis worker.
+
+## Structure
+
+The CLI is organized by responsibility:
+
+- `irides_cli/presentation/`: command definitions and `argparse` parsing;
+- `irides_cli/controllers/`: maps command-line arguments to use cases;
+- `irides_cli/dto/`: immutable, typed request DTOs;
+- `irides_cli/services/`: live introspection and metadata operations using only `core`;
+- `irides_cli/main.py`: composition root, JSON serialization, and process-level error handling.
+
+## Local installation
+
+```bash
+pip install -e ./core -e ./cli
+```
+
+## Quickstart & Configuration
+
+Irides supports two ways to configure database targets:
+
+### Option 1: Declarative Config File (`irides.yaml`) — Recommended
+Generate a template configuration with:
+```bash
+irides init
+```
+This creates an `irides.yaml` file in the current directory:
+```yaml
+targets:
+  my_postgres:
+    type: postgres
+    host: localhost
+    port: 5432
+    user: postgres
+    password: "${PG_PASSWORD:-secret}"
+    database: my_database
+
+  local_sqlite:
+    type: sqlite
+    database: ./app.db
+```
+You can pass a custom config file anytime using `-c` / `--config-file`:
+```bash
+irides -c /path/to/my_config.yaml configurations
+```
+
+### Option 2: Environment Variables (`.env`)
+You can initialize an environment template with:
+```bash
+irides init --format env
+```
+Or specify an explicit `.env` file via `-e` / `--env-file`:
+```bash
+irides -e /path/to/.env configurations
+```
+
+## Commands
+
+```bash
+# Initialize template configuration
+irides init
+
+# List configured database targets
+irides configurations
+
+# Test database connection
+irides connect my_postgres
+
+# List database instances
+irides instances --target my_postgres
+
+# List schemas in a database
+irides schemas --target my_postgres --instance localhost
+
+# List tables (supports --limit and --offset)
+irides tables --target my_postgres --instance localhost --schema public --limit 50
+
+# Introspect table schema
+irides describe --target my_postgres --instance localhost --schema public --table orders
+irides describe --target my_postgres --instance localhost --schema public --table orders --generate-ai-docs
+irides describe --target my_postgres --instance localhost --schema public --table orders --no-export-okf
+```
+
+> **Note**: `--target` and `--config` are interchangeable aliases.
+Omitting `--target`, `--instance`, `--schema`, or `--table` expands the scope, just like the corresponding API endpoints. Results are always written as JSON to stdout; errors are written to stderr. Add `--no-cache` to introspection commands to bypass Redis.
+
+`describe` saves canonical JSON metadata and generates both **Markdown** and **Open Knowledge Format (OKF v0.2)** exports by default.
+
+Available options for `describe`:
+- `--generate-ai-docs`: generate domain summary and column descriptions via LiteLLM.
+- `--no-save-metadata`: skip saving the canonical JSON metadata file (exports are still generated if enabled).
+- `--only-if-changed`: skip writing if the schema is identical to the stored version.
+- `--no-export-markdown`: disable the default Markdown export.
+- `--no-export-okf`: disable the default OKF catalog bundle generation.
+- `--no-preformat`: export full metadata instead of the essential deterministic record.
+- `--save-markdown`: legacy compatibility flag for Markdown export.
+
+Artifacts are persisted under `STORAGE_EXPORT_DIR` (default `storage/exports`):
+- `storage/exports/markdown/{config}/{instance}/{schema}/{table}.md`
+- `storage/exports/okf/catalog/{config}/{instance}/{schema}/{table}.md` (along with `storage/exports/okf/catalog/index.md`)
+
+## Metadata
+
+```bash
+irides metadata instances
+irides metadata databases db1.company.com
+irides metadata tables db1.company.com production
+irides metadata get db1.company.com production orders
+irides metadata update db1.company.com production orders '{"owner":"data-team","tags":["billing"]}'
+```
+
+The CLI does not include `scan` commands. They are asynchronous and explicitly require Redis Streams and the `worker` service.
+
+## Docker
+
+The CLI reads its configuration from `cli/.env` and uses the shared Redis network. Start by copying `.env.example` as shown above and configure at least one `DB_TARGETS` entry.
+
+```bash
+docker compose -f infra/docker-compose.infra.yml up -d
+docker compose -f cli/docker-compose.yml run --rm irides-cli configurations
+docker compose -f cli/docker-compose.yml run --rm irides-cli tables --config sales_mysql --schema public
+docker compose -f cli/docker-compose.yml run --rm irides-cli describe --config sales_mysql --schema public --table orders
+```

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

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+setup.py
+irides_cli/__init__.py
+irides_cli/main.py
+irides_cli.egg-info/PKG-INFO
+irides_cli.egg-info/SOURCES.txt
+irides_cli.egg-info/dependency_links.txt
+irides_cli.egg-info/entry_points.txt
+irides_cli.egg-info/requires.txt
+irides_cli.egg-info/top_level.txt
+irides_cli/controllers/__init__.py
+irides_cli/controllers/init_controller.py
+irides_cli/controllers/introspection_controller.py
+irides_cli/controllers/metadata_controller.py
+irides_cli/dto/__init__.py
+irides_cli/dto/requests.py
+irides_cli/presentation/__init__.py
+irides_cli/presentation/parser.py
+irides_cli/services/__init__.py
+irides_cli/services/introspection_service.py
+irides_cli/services/metadata_service.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[console_scripts]
+irides = irides_cli.main:main

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

@@ -0,0 +1 @@
+irides-core>=0.1.0

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

@@ -0,0 +1 @@
+irides_cli

irides_cli-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "irides-cli"
+version = "0.1.0"
+description = "A command-line interface for discovering, inspecting, and managing structured database context for AI systems."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "Gian Andrea Sechi", email = "me@gianandreasechi.com"}
+]
+keywords = ["database", "introspection", "cli", "irides", "schema"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+]
+dependencies = [
+    "irides-core>=0.1.0",
+]
+
+[project.scripts]
+irides = "irides_cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["irides_cli*"]
+
+[project.urls]
+"Source Code" = "https://github.com/GianAndreaSechi/irides/cli"
+"Homepage" = "https://www.gianandreasechi.com"

irides_cli-0.1.0/setup.cfg

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

irides_cli-0.1.0/setup.py

@@ -0,0 +1,10 @@
+from setuptools import find_packages, setup
+
+setup(
+    name="irides-cli",
+    version="0.1.0",
+    description="Command-line interface for Irides database introspection",
+    packages=find_packages(include=["irides_cli*"]),
+    install_requires=["irides-core>=0.1.0"],
+    entry_points={"console_scripts": ["irides=irides_cli.main:main"]},
+)