loredocs-cli 0.1.0a1__tar.gz

loredocs_cli-0.1.0a1/LICENSE

@@ -0,0 +1,93 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Labyrinth Analytics Consulting
+Licensed Work:        LoreConvo v0.3.2
+                      The Licensed Work is (c) 2026 Labyrinth Analytics Consulting
+Additional Use Grant: You may make personal, non-commercial use of the Licensed Work,
+                      subject to the following limitation: you may store no more than
+                      50 sessions in total across all databases on your machine. Any
+                      use that exceeds this limit, or any commercial use, requires a
+                      paid license from the Licensor.
+Change Date:          2030-03-31
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: info@labyrinthanalyticsconsulting.com
+
+---
+
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive a copy of the Licensed Work in
+combination with other programs, as part of a larger work, or packaged by a
+third party, and you receive the Licensed Work under a different license from
+the one described in this License, you are required to comply with the license
+applicable to you.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided under this License:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

loredocs_cli-0.1.0a1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: loredocs-cli
+Version: 0.1.0a1
+Summary: Command-line interface for LoreDocs knowledge vault management
+Author: Labyrinth Analytics Consulting
+License: Business Source License 1.1
+        
+        Parameters
+        
+        Licensor:             Labyrinth Analytics Consulting
+        Licensed Work:        LoreConvo v0.3.2
+                              The Licensed Work is (c) 2026 Labyrinth Analytics Consulting
+        Additional Use Grant: You may make personal, non-commercial use of the Licensed Work,
+                              subject to the following limitation: you may store no more than
+                              50 sessions in total across all databases on your machine. Any
+                              use that exceeds this limit, or any commercial use, requires a
+                              paid license from the Licensor.
+        Change Date:          2030-03-31
+        Change License:       Apache License, Version 2.0
+        
+        For information about alternative licensing arrangements for the Licensed Work,
+        please contact: info@labyrinthanalyticsconsulting.com
+        
+        ---
+        
+        Business Source License 1.1
+        
+        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+        "Business Source License" is a trademark of MariaDB Corporation Ab.
+        
+        Terms
+        
+        The Licensor hereby grants you the right to copy, modify, create derivative
+        works, redistribute, and make non-production use of the Licensed Work. The
+        Licensor may make an Additional Use Grant, above, permitting limited production
+        use.
+        
+        Effective on the Change Date, or the fourth anniversary of the first publicly
+        available distribution of a specific version of the Licensed Work under this
+        License, whichever comes first, the Licensor hereby grants you rights under
+        the terms of the Change License, and the rights granted in the paragraph
+        above terminate.
+        
+        If your use of the Licensed Work does not comply with the requirements
+        currently in effect as described in this License, you must purchase a
+        commercial license from the Licensor, its affiliated entities, or authorized
+        resellers, or you must refrain from using the Licensed Work.
+        
+        All copies of the original and modified Licensed Work, and derivative works
+        of the Licensed Work, are subject to this License. This License applies
+        separately for each version of the Licensed Work and the Change Date may vary
+        for each version of the Licensed Work released by Licensor.
+        
+        You must conspicuously display this License on each original or modified copy
+        of the Licensed Work. If you receive a copy of the Licensed Work in
+        combination with other programs, as part of a larger work, or packaged by a
+        third party, and you receive the Licensed Work under a different license from
+        the one described in this License, you are required to comply with the license
+        applicable to you.
+        
+        Any use of the Licensed Work in violation of this License will automatically
+        terminate your rights under this License for the current and all other
+        versions of the Licensed Work.
+        
+        This License does not grant you any right in any trademark or logo of
+        Licensor or its affiliates (provided that you may use a trademark or logo of
+        Licensor as expressly required by this License).
+        
+        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+        TITLE.
+        
+        MariaDB hereby grants you permission to use this License's text to license
+        your works, and to refer to it using the trademark "Business Source License",
+        as long as you comply with the Covenants of Licensor below.
+        
+        Covenants of Licensor
+        
+        In consideration of the right to use this License's text and the "Business
+        Source License" name and trademark, Licensor covenants to MariaDB, and to all
+        other recipients of the licensed work to be provided under this License:
+        
+        1. To specify as the Change License the GPL Version 2.0 or any later version,
+           or a license that is compatible with GPL Version 2.0 or a later version,
+           where "compatible" means that software provided under the Change License can
+           be included in a program with software provided under GPL Version 2.0 or a
+           later version. Licensor may specify additional Change Licenses without
+           limitation.
+        
+        2. To either: (a) specify an additional grant of rights to use that does not
+           impose any additional restriction on the right granted in this License, as
+           the Additional Use Grant; or (b) insert the text "None".
+        
+        3. To specify a Change Date.
+        
+        4. Not to modify this License in any other way.
+        
+Project-URL: Homepage, https://github.com/labyrinth-analytics/loredocs-cli
+Project-URL: Repository, https://github.com/labyrinth-analytics/loredocs-cli
+Project-URL: Bug Tracker, https://github.com/labyrinth-analytics/loredocs-cli/issues
+Keywords: mcp,claude,knowledge-management,cli,ai-tools,claude-plugin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: Other/Proprietary License
+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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer==0.13.1
+Provides-Extra: server
+Requires-Dist: loredocs==0.1.7; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.4; extra == "dev"
+Dynamic: license-file
+
+# loredocs-cli v0.1.0
+
+Command-line interface for LoreDocs knowledge vaults.
+
+List, search, and read your LoreDocs vaults and documents from the terminal --
+no MCP server or Claude session required.
+
+```bash
+pip install loredocs-cli
+
+loredocs-cli list
+loredocs-cli info "my vault"
+loredocs-cli search "architecture decision"
+```
+
+## Commands
+
+| Command | Free tier | Description |
+|---------|-----------|-------------|
+| `list` | Yes | List all vaults |
+| `info <vault>` | Yes | Show vault details and document count |
+| `search <query>` | Yes | Search documents by keyword |
+| `add-doc <vault>` | [server] extra | Add a document to a vault |
+
+The `add-doc` command requires `pip install "loredocs-cli[server]"` (installs the
+`loredocs` package as a dependency).
+
+## Platform
+
+macOS (x86_64 + arm64) and Linux (x86_64). Windows is not supported.
+
+## Full Documentation
+
+See [INSTALL.md](INSTALL.md) for complete usage, flags, environment variables,
+and troubleshooting.
+
+## License
+
+Business Source License 1.1 -- Labyrinth Analytics Consulting

loredocs_cli-0.1.0a1/README.md

@@ -0,0 +1,39 @@
+# loredocs-cli v0.1.0
+
+Command-line interface for LoreDocs knowledge vaults.
+
+List, search, and read your LoreDocs vaults and documents from the terminal --
+no MCP server or Claude session required.
+
+```bash
+pip install loredocs-cli
+
+loredocs-cli list
+loredocs-cli info "my vault"
+loredocs-cli search "architecture decision"
+```
+
+## Commands
+
+| Command | Free tier | Description |
+|---------|-----------|-------------|
+| `list` | Yes | List all vaults |
+| `info <vault>` | Yes | Show vault details and document count |
+| `search <query>` | Yes | Search documents by keyword |
+| `add-doc <vault>` | [server] extra | Add a document to a vault |
+
+The `add-doc` command requires `pip install "loredocs-cli[server]"` (installs the
+`loredocs` package as a dependency).
+
+## Platform
+
+macOS (x86_64 + arm64) and Linux (x86_64). Windows is not supported.
+
+## Full Documentation
+
+See [INSTALL.md](INSTALL.md) for complete usage, flags, environment variables,
+and troubleshooting.
+
+## License
+
+Business Source License 1.1 -- Labyrinth Analytics Consulting

loredocs_cli-0.1.0a1/loredocs_cli/__init__.py

@@ -0,0 +1,3 @@
+"""LoreDocs CLI -- standalone command-line interface for LoreDocs knowledge vaults."""
+
+__version__ = "0.1.0"

loredocs_cli-0.1.0a1/loredocs_cli/_db_path.py

@@ -0,0 +1,106 @@
+import os
+import re
+import sqlite3
+import sys
+from pathlib import Path
+
+DEFAULT_LOREDOCS_DIR = Path.home() / ".loredocs"
+DEFAULT_DB_PATH = DEFAULT_LOREDOCS_DIR / "loredocs.db"
+
+_KNOWN_DB_DIRS = frozenset({
+    str(Path.home() / ".loreconvo"),
+    str(Path.home() / ".loredocs"),
+    str(Path.home() / ".lorecap"),
+})
+
+
+def _sanitize_fts5(query: str) -> str:
+    """Strip FTS5 special chars to prevent injection."""
+    sanitized = re.sub(r'["\*\^\(\)\[\]]', ' ', query).strip()
+    return sanitized if sanitized else '""'
+
+
+def validate_db_path(path_str: str) -> Path:
+    """Validate a --db-path argument."""
+    import typer
+
+    p = Path(path_str).expanduser().resolve()
+
+    if p.suffix != ".db":
+        raise typer.BadParameter(f"DB path must end in .db (got: {p.suffix!r})")
+
+    home = Path.home().resolve()
+    try:
+        p.relative_to(home)
+    except ValueError:
+        if not os.environ.get("LOREDOCS_ALLOW_EXTERNAL_DB"):
+            raise typer.BadParameter(
+                f"DB path must be under {home}. "
+                "Set LOREDOCS_ALLOW_EXTERNAL_DB=1 to override (CI/testing only)."
+            )
+
+    if str(p.parent) not in _KNOWN_DB_DIRS:
+        if not os.environ.get("LOREDOCS_ALLOW_EXTERNAL_DB"):
+            raise typer.BadParameter(
+                f"DB must be in one of: {sorted(_KNOWN_DB_DIRS)}.\n"
+                "Set LOREDOCS_ALLOW_EXTERNAL_DB=1 to use a custom directory."
+            )
+        print(f"[warn] external DB path in use: {p}", file=sys.stderr)
+
+    if os.environ.get("LOREDOCS_ALLOW_EXTERNAL_DB"):
+        print(
+            "[warn] LOREDOCS_ALLOW_EXTERNAL_DB is set; external DB path override is active.",
+            file=sys.stderr,
+        )
+
+    if p.exists() and hasattr(os, "getuid"):
+        if os.stat(p).st_uid != os.getuid():
+            raise typer.BadParameter(f"DB at {p} is not owned by current user.")
+
+    if p.exists() and not p.is_file():
+        raise typer.BadParameter(f"{p} exists but is not a file.")
+
+    return p
+
+
+def get_db_path(custom_path: str | None = None) -> Path:
+    """Resolve DB path: --db-path arg > LOREDOCS_ROOT env > default."""
+    if custom_path:
+        return validate_db_path(custom_path)
+    env_path = os.environ.get("LOREDOCS_ROOT")
+    if env_path:
+        return Path(env_path).expanduser() / "loredocs.db"
+    return DEFAULT_DB_PATH
+
+
+def open_db(db_path: Path) -> sqlite3.Connection:
+    """Open SQLite connection with WAL mode and permissions check."""
+    if not db_path.exists():
+        print(
+            f"\nError: LoreDocs database not found at {db_path}\n\n"
+            "The database is created automatically when you first use the LoreDocs MCP server.\n\n"
+            "Quick setup:\n"
+            "  1. pip install loredocs-cli[server]         # install CLI + server\n"
+            "  2. Add loredocs to your MCP client config   # (see: pip show loredocs)\n"
+            "  3. Start a session to initialize the DB     # MCP creates DB on first use\n"
+            "  4. Then run: loredocs-cli list\n\n"
+            "Set LOREDOCS_ROOT=/path/to/loredocs-dir to use a custom data location.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    if hasattr(os, "stat"):
+        mode = db_path.stat().st_mode & 0o777
+        if mode & 0o177:
+            print(
+                f"[warn] DB file permissions are broader than 0600: {db_path}  "
+                f"(current: {oct(mode)}). "
+                f"Fix with: chmod 600 {db_path}",
+                file=sys.stderr,
+            )
+
+    conn = sqlite3.connect(str(db_path), timeout=30)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=30000")
+    conn.row_factory = sqlite3.Row
+    return conn

loredocs_cli-0.1.0a1/loredocs_cli/_platform_check.py

@@ -0,0 +1,33 @@
+import platform
+import sys
+
+_SUPPORTED = {
+    ("darwin", "x86_64"),
+    ("darwin", "arm64"),
+    ("linux", "x86_64"),
+}
+
+
+def check_platform() -> None:
+    """Exit with a clear error on unsupported platforms. Called first in main()."""
+    plat = "darwin" if sys.platform == "darwin" else "linux"
+    key = (plat, platform.machine())
+    if key not in _SUPPORTED:
+        print(
+            f"ERROR: loredocs-cli is not supported on {sys.platform}/{platform.machine()}.\n"
+            "Supported: macOS (x86_64, arm64), Linux x86_64 (glibc).\n"
+            "Windows and musl/Alpine are not supported in v0.1.x.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    if sys.platform == "linux":
+        try:
+            proc_ver = open("/proc/version").read()
+            if "Microsoft" in proc_ver or "microsoft" in proc_ver:
+                print(
+                    "[warn] WSL detected. DB path defaults to WSL filesystem. "
+                    "Windows-host DB paths are not supported.",
+                    file=sys.stderr,
+                )
+        except OSError:
+            pass

loredocs_cli-0.1.0a1/loredocs_cli/_schema_compat.py

@@ -0,0 +1,38 @@
+import sqlite3
+import sys
+
+CLI_MIN_SCHEMA_VERSION = 0
+CLI_MAX_WRITE_VERSION = 8
+CLI_MAX_READ_VERSION = 10
+
+
+def check_schema_compatibility(conn: sqlite3.Connection) -> str:
+    """Check PRAGMA user_version against supported range.
+
+    Returns 'normal' or 'read_only'. Exits on incompatible schema.
+    """
+    try:
+        version = conn.execute("PRAGMA user_version").fetchone()[0]
+    except sqlite3.Error:
+        version = 0
+
+    if version > CLI_MAX_READ_VERSION:
+        print(
+            f"Error: DB schema v{version} is newer than loredocs-cli supports "
+            f"(max readable: {CLI_MAX_READ_VERSION}).\n"
+            "Upgrade loredocs-cli: pip install -U loredocs-cli",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+    if version > CLI_MAX_WRITE_VERSION:
+        print(
+            f"[warn] DB schema v{version} is newer than CLI write support "
+            f"(max writable: {CLI_MAX_WRITE_VERSION}). "
+            "Running in read-only mode. "
+            "Upgrade loredocs-cli[server] for full write support.",
+            file=sys.stderr,
+        )
+        return "read_only"
+
+    return "normal"

loredocs_cli-0.1.0a1/loredocs_cli/_write_guard.py

@@ -0,0 +1,21 @@
+import importlib.util
+import sys
+
+
+def _has_server_package() -> bool:
+    """Check if the loredocs server package is installed."""
+    return importlib.util.find_spec("loredocs") is not None
+
+
+def require_write_capability(operation: str) -> None:
+    """Exit with a clear error if loredocs server package is not installed.
+
+    Call this as the first line of every write command handler before any DB access.
+    """
+    if not _has_server_package():
+        print(
+            f"Error: '{operation}' requires write access.\n"
+            "Install the server package: pip install loredocs-cli[server]",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)

loredocs_cli-0.1.0a1/loredocs_cli/main.py

@@ -0,0 +1,194 @@
+"""LoreDocs CLI -- knowledge vault command line interface.
+
+Free-tier operations only. Pro features require the LoreDocs MCP server.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ._db_path import get_db_path, open_db, _sanitize_fts5
+from ._platform_check import check_platform
+from ._schema_compat import check_schema_compatibility
+from ._write_guard import require_write_capability
+
+app = typer.Typer(
+    name="loredocs-cli",
+    help=(
+        "LoreDocs -- knowledge vault management.\n\n"
+        "Free-tier CLI (read operations).\n"
+        "Write operations require the MCP server: pip install loredocs-cli[server]"
+    ),
+    no_args_is_help=True,
+)
+
+_DB_PATH_OPTION = typer.Option(
+    None, "--db-path", help="Path to loredocs.db (overrides LOREDOCS_ROOT)"
+)
+
+
+@app.command(name="list")
+def list_vaults(
+    db_path: Optional[str] = _DB_PATH_OPTION,
+) -> None:
+    """List all vaults."""
+    path = get_db_path(db_path)
+    conn = open_db(path)
+    check_schema_compatibility(conn)
+
+    try:
+        rows = conn.execute(
+            "SELECT id, name, description, created_at FROM vaults "
+            "WHERE archived = 0 ORDER BY name"
+        ).fetchall()
+    finally:
+        conn.close()
+
+    if not rows:
+        typer.echo("No vaults found.")
+        return
+    for row in rows:
+        typer.echo(f"  {row['name']}")
+        if row["description"]:
+            typer.echo(f"    {row['description'][:80]}")
+        typer.echo(f"    id: {row['id']}")
+    typer.echo(f"\n{len(rows)} vault(s)")
+
+
+@app.command()
+def info(
+    vault: str = typer.Argument(..., help="Vault name"),
+    db_path: Optional[str] = _DB_PATH_OPTION,
+) -> None:
+    """Show vault details and document count."""
+    if not re.fullmatch(r"[a-zA-Z0-9_\- ]{1,128}", vault):
+        typer.echo("Error: vault name contains invalid characters.", err=True)
+        raise typer.Exit(1)
+
+    path = get_db_path(db_path)
+    conn = open_db(path)
+    check_schema_compatibility(conn)
+
+    try:
+        row = conn.execute(
+            "SELECT id, name, description, created_at, updated_at, tags FROM vaults "
+            "WHERE name = ? AND archived = 0",
+            (vault,),
+        ).fetchone()
+        if not row:
+            typer.echo(f"Vault not found: {vault!r}", err=True)
+            raise typer.Exit(1)
+        doc_count = conn.execute(
+            "SELECT COUNT(*) FROM documents WHERE vault_id = ? AND deleted = 0",
+            (row["id"],),
+        ).fetchone()[0]
+    finally:
+        conn.close()
+
+    typer.echo(f"\n--- {row['name']} ---")
+    typer.echo(f"  id:          {row['id']}")
+    typer.echo(f"  documents:   {doc_count}")
+    typer.echo(f"  created:     {str(row['created_at'])[:10]}")
+    typer.echo(f"  updated:     {str(row['updated_at'])[:10]}")
+    if row["description"]:
+        typer.echo(f"  description: {row['description']}")
+    if row["tags"] and row["tags"] != "[]":
+        try:
+            tags = json.loads(row["tags"])
+            if tags:
+                typer.echo(f"  tags:        {', '.join(tags)}")
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query"),
+    vault: Optional[str] = typer.Option(None, "--vault", "-v", help="Restrict to vault name"),
+    limit: int = typer.Option(20, "--limit", "-n", help="Max results"),
+    db_path: Optional[str] = _DB_PATH_OPTION,
+) -> None:
+    """Search documents by keyword."""
+    path = get_db_path(db_path)
+    conn = open_db(path)
+    check_schema_compatibility(conn)
+
+    like_q = f"%{query}%"
+    try:
+        if vault:
+            if not re.fullmatch(r"[a-zA-Z0-9_\- ]{1,128}", vault):
+                typer.echo("Error: vault name contains invalid characters.", err=True)
+                raise typer.Exit(1)
+            vault_row = conn.execute(
+                "SELECT id FROM vaults WHERE name = ? AND archived = 0", (vault,)
+            ).fetchone()
+            if not vault_row:
+                typer.echo(f"Vault not found: {vault!r}", err=True)
+                raise typer.Exit(1)
+            vault_id = vault_row["id"]
+            rows = conn.execute(
+                "SELECT d.id, d.name, d.vault_id, d.category, d.updated_at "
+                "FROM documents d "
+                "WHERE d.vault_id = ? AND d.deleted = 0 "
+                "AND (d.name LIKE ? OR d.notes LIKE ?) "
+                "ORDER BY d.updated_at DESC LIMIT ?",
+                (vault_id, like_q, like_q, limit),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT d.id, d.name, d.vault_id, d.category, d.updated_at "
+                "FROM documents d WHERE d.deleted = 0 "
+                "AND (d.name LIKE ? OR d.notes LIKE ? OR d.tags LIKE ?) "
+                "ORDER BY d.updated_at DESC LIMIT ?",
+                (like_q, like_q, like_q, limit),
+            ).fetchall()
+    finally:
+        conn.close()
+
+    if not rows:
+        typer.echo(f"No documents found for: {query!r}")
+        return
+    for row in rows:
+        typer.echo(f"  [{row['category']:10s}] {row['name']}")
+        typer.echo(f"    id: {row['id']}")
+    typer.echo(f"\n{len(rows)} result(s)")
+
+
+@app.command(name="add-doc")
+def add_doc(
+    vault: str = typer.Argument(..., help="Vault name"),
+    title: str = typer.Option(..., "--title", "-t", help="Document title"),
+    body: str = typer.Option(..., "--body", "-b", help="Document content"),
+    category: str = typer.Option("general", "--category", "-c", help="Category"),
+    db_path: Optional[str] = _DB_PATH_OPTION,
+) -> None:
+    """Add a document to a vault. Requires loredocs-cli[server]."""
+    require_write_capability("add-doc")
+
+    from loredocs.storage import VaultStorage
+
+    path = get_db_path(db_path)
+    import os
+    if db_path:
+        os.environ["LOREDOCS_ROOT"] = str(path.parent)
+
+    storage = VaultStorage()
+    result = storage.vault_add_note(vault_name=vault, title=title, body=body, category=category)
+    if result.get("error"):
+        typer.echo(f"Error: {result['error']}", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"[OK] Added document: {title}")
+    typer.echo(f"  vault: {vault}")
+
+
+def main() -> None:
+    check_platform()
+    app()
+
+
+if __name__ == "__main__":
+    main()

loredocs_cli-0.1.0a1/loredocs_cli.egg-info/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: loredocs-cli
+Version: 0.1.0a1
+Summary: Command-line interface for LoreDocs knowledge vault management
+Author: Labyrinth Analytics Consulting
+License: Business Source License 1.1
+        
+        Parameters
+        
+        Licensor:             Labyrinth Analytics Consulting
+        Licensed Work:        LoreConvo v0.3.2
+                              The Licensed Work is (c) 2026 Labyrinth Analytics Consulting
+        Additional Use Grant: You may make personal, non-commercial use of the Licensed Work,
+                              subject to the following limitation: you may store no more than
+                              50 sessions in total across all databases on your machine. Any
+                              use that exceeds this limit, or any commercial use, requires a
+                              paid license from the Licensor.
+        Change Date:          2030-03-31
+        Change License:       Apache License, Version 2.0
+        
+        For information about alternative licensing arrangements for the Licensed Work,
+        please contact: info@labyrinthanalyticsconsulting.com
+        
+        ---
+        
+        Business Source License 1.1
+        
+        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+        "Business Source License" is a trademark of MariaDB Corporation Ab.
+        
+        Terms
+        
+        The Licensor hereby grants you the right to copy, modify, create derivative
+        works, redistribute, and make non-production use of the Licensed Work. The
+        Licensor may make an Additional Use Grant, above, permitting limited production
+        use.
+        
+        Effective on the Change Date, or the fourth anniversary of the first publicly
+        available distribution of a specific version of the Licensed Work under this
+        License, whichever comes first, the Licensor hereby grants you rights under
+        the terms of the Change License, and the rights granted in the paragraph
+        above terminate.
+        
+        If your use of the Licensed Work does not comply with the requirements
+        currently in effect as described in this License, you must purchase a
+        commercial license from the Licensor, its affiliated entities, or authorized
+        resellers, or you must refrain from using the Licensed Work.
+        
+        All copies of the original and modified Licensed Work, and derivative works
+        of the Licensed Work, are subject to this License. This License applies
+        separately for each version of the Licensed Work and the Change Date may vary
+        for each version of the Licensed Work released by Licensor.
+        
+        You must conspicuously display this License on each original or modified copy
+        of the Licensed Work. If you receive a copy of the Licensed Work in
+        combination with other programs, as part of a larger work, or packaged by a
+        third party, and you receive the Licensed Work under a different license from
+        the one described in this License, you are required to comply with the license
+        applicable to you.
+        
+        Any use of the Licensed Work in violation of this License will automatically
+        terminate your rights under this License for the current and all other
+        versions of the Licensed Work.
+        
+        This License does not grant you any right in any trademark or logo of
+        Licensor or its affiliates (provided that you may use a trademark or logo of
+        Licensor as expressly required by this License).
+        
+        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+        TITLE.
+        
+        MariaDB hereby grants you permission to use this License's text to license
+        your works, and to refer to it using the trademark "Business Source License",
+        as long as you comply with the Covenants of Licensor below.
+        
+        Covenants of Licensor
+        
+        In consideration of the right to use this License's text and the "Business
+        Source License" name and trademark, Licensor covenants to MariaDB, and to all
+        other recipients of the licensed work to be provided under this License:
+        
+        1. To specify as the Change License the GPL Version 2.0 or any later version,
+           or a license that is compatible with GPL Version 2.0 or a later version,
+           where "compatible" means that software provided under the Change License can
+           be included in a program with software provided under GPL Version 2.0 or a
+           later version. Licensor may specify additional Change Licenses without
+           limitation.
+        
+        2. To either: (a) specify an additional grant of rights to use that does not
+           impose any additional restriction on the right granted in this License, as
+           the Additional Use Grant; or (b) insert the text "None".
+        
+        3. To specify a Change Date.
+        
+        4. Not to modify this License in any other way.
+        
+Project-URL: Homepage, https://github.com/labyrinth-analytics/loredocs-cli
+Project-URL: Repository, https://github.com/labyrinth-analytics/loredocs-cli
+Project-URL: Bug Tracker, https://github.com/labyrinth-analytics/loredocs-cli/issues
+Keywords: mcp,claude,knowledge-management,cli,ai-tools,claude-plugin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: Other/Proprietary License
+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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer==0.13.1
+Provides-Extra: server
+Requires-Dist: loredocs==0.1.7; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.4; extra == "dev"
+Dynamic: license-file
+
+# loredocs-cli v0.1.0
+
+Command-line interface for LoreDocs knowledge vaults.
+
+List, search, and read your LoreDocs vaults and documents from the terminal --
+no MCP server or Claude session required.
+
+```bash
+pip install loredocs-cli
+
+loredocs-cli list
+loredocs-cli info "my vault"
+loredocs-cli search "architecture decision"
+```
+
+## Commands
+
+| Command | Free tier | Description |
+|---------|-----------|-------------|
+| `list` | Yes | List all vaults |
+| `info <vault>` | Yes | Show vault details and document count |
+| `search <query>` | Yes | Search documents by keyword |
+| `add-doc <vault>` | [server] extra | Add a document to a vault |
+
+The `add-doc` command requires `pip install "loredocs-cli[server]"` (installs the
+`loredocs` package as a dependency).
+
+## Platform
+
+macOS (x86_64 + arm64) and Linux (x86_64). Windows is not supported.
+
+## Full Documentation
+
+See [INSTALL.md](INSTALL.md) for complete usage, flags, environment variables,
+and troubleshooting.
+
+## License
+
+Business Source License 1.1 -- Labyrinth Analytics Consulting

loredocs_cli-0.1.0a1/loredocs_cli.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+loredocs_cli/__init__.py
+loredocs_cli/_db_path.py
+loredocs_cli/_platform_check.py
+loredocs_cli/_schema_compat.py
+loredocs_cli/_write_guard.py
+loredocs_cli/main.py
+loredocs_cli.egg-info/PKG-INFO
+loredocs_cli.egg-info/SOURCES.txt
+loredocs_cli.egg-info/dependency_links.txt
+loredocs_cli.egg-info/entry_points.txt
+loredocs_cli.egg-info/requires.txt
+loredocs_cli.egg-info/top_level.txt
+tests/test_cli.py

loredocs_cli-0.1.0a1/loredocs_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

loredocs_cli-0.1.0a1/loredocs_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+loredocs-cli = loredocs_cli.main:main

loredocs_cli-0.1.0a1/loredocs_cli.egg-info/requires.txt

@@ -0,0 +1,7 @@
+typer==0.13.1
+
+[dev]
+pytest==8.3.4
+
+[server]
+loredocs==0.1.7

loredocs_cli-0.1.0a1/loredocs_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+loredocs_cli

loredocs_cli-0.1.0a1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "loredocs-cli"
+version = "0.1.0a1"
+description = "Command-line interface for LoreDocs knowledge vault management"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Labyrinth Analytics Consulting" }
+]
+keywords = ["mcp", "claude", "knowledge-management", "cli", "ai-tools", "claude-plugin"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+]
+
+dependencies = [
+    "typer==0.13.1",
+]
+
+[project.optional-dependencies]
+server = [
+    "loredocs==0.1.7",  # allow-range: loredocs -- CLI depends on server for write ops
+]
+dev = [
+    "pytest==8.3.4",
+]
+
+[project.scripts]
+loredocs-cli = "loredocs_cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/labyrinth-analytics/loredocs-cli"
+Repository = "https://github.com/labyrinth-analytics/loredocs-cli"
+"Bug Tracker" = "https://github.com/labyrinth-analytics/loredocs-cli/issues"
+
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"

loredocs_cli-0.1.0a1/setup.cfg

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

loredocs_cli-0.1.0a1/tests/test_cli.py

@@ -0,0 +1,179 @@
+"""Tests for loredocs-cli."""
+
+import json
+import os
+import sqlite3
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+@pytest.fixture
+def tmp_db(tmp_path):
+    """Create a minimal loredocs.db fixture."""
+    db_path = tmp_path / "loredocs.db"
+    conn = sqlite3.connect(str(db_path))
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.executescript("""
+        CREATE TABLE vaults (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            description TEXT DEFAULT '',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            archived INTEGER DEFAULT 0,
+            tags TEXT DEFAULT '[]',
+            linked_projects TEXT DEFAULT '[]'
+        );
+        CREATE TABLE documents (
+            id TEXT PRIMARY KEY,
+            vault_id TEXT NOT NULL,
+            name TEXT NOT NULL,
+            original_filename TEXT NOT NULL,
+            file_extension TEXT DEFAULT '',
+            category TEXT DEFAULT 'general',
+            priority TEXT DEFAULT 'normal',
+            tags TEXT DEFAULT '[]',
+            notes TEXT DEFAULT '',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            file_size_bytes INTEGER DEFAULT 0,
+            version_count INTEGER DEFAULT 1,
+            deleted INTEGER DEFAULT 0
+        );
+        CREATE VIRTUAL TABLE doc_fts USING fts5(
+            doc_id,
+            vault_id,
+            name,
+            content,
+            tags,
+            notes
+        );
+        INSERT INTO vaults VALUES
+            ('vault-1', 'side_hustle', 'Side hustle project vault',
+             '2026-05-01T00:00:00Z', '2026-05-30T00:00:00Z', 0, '[]', '[]'),
+            ('vault-2', 'job_skills', 'Job skills vault',
+             '2026-05-01T00:00:00Z', '2026-05-30T00:00:00Z', 0, '["jobs"]', '[]');
+        INSERT INTO documents VALUES
+            ('doc-1', 'vault-1', 'LoreCap spec', 'lorecap_spec.md', '.md',
+             'reference', 'authoritative', '["spec","lorecap"]', '',
+             '2026-05-20T00:00:00Z', '2026-05-28T00:00:00Z', 1024, 1, 0),
+            ('doc-2', 'vault-2', 'Python skills gap analysis', 'gap.md', '.md',
+             'report', 'normal', '["python"]', '',
+             '2026-05-25T00:00:00Z', '2026-05-29T00:00:00Z', 512, 1, 0);
+    """)
+    conn.commit()
+    conn.close()
+    return db_path
+
+
+def test_list_vaults(tmp_db, monkeypatch):
+    """list command shows all non-archived vaults."""
+    from typer.testing import CliRunner
+    from loredocs_cli.main import app
+
+    monkeypatch.setenv("LOREDOCS_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loredocs_cli.main.check_platform", lambda: None)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["list", "--db-path", str(tmp_db)])
+    assert result.exit_code == 0
+    assert "side_hustle" in result.output
+    assert "job_skills" in result.output
+    assert "2 vault(s)" in result.output
+
+
+def test_info_vault(tmp_db, monkeypatch):
+    """info command shows vault details and doc count."""
+    from typer.testing import CliRunner
+    from loredocs_cli.main import app
+
+    monkeypatch.setenv("LOREDOCS_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loredocs_cli.main.check_platform", lambda: None)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["info", "side_hustle", "--db-path", str(tmp_db)])
+    assert result.exit_code == 0
+    assert "side_hustle" in result.output
+    assert "documents:   1" in result.output
+
+
+def test_info_missing_vault(tmp_db, monkeypatch):
+    """info command exits 1 for unknown vault."""
+    from typer.testing import CliRunner
+    from loredocs_cli.main import app
+
+    monkeypatch.setenv("LOREDOCS_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loredocs_cli.main.check_platform", lambda: None)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["info", "nonexistent", "--db-path", str(tmp_db)])
+    assert result.exit_code == 1
+
+
+def test_search_fallback(tmp_db, monkeypatch):
+    """search falls back to LIKE when FTS fails."""
+    from typer.testing import CliRunner
+    from loredocs_cli.main import app
+
+    monkeypatch.setenv("LOREDOCS_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loredocs_cli.main.check_platform", lambda: None)
+
+    runner = CliRunner()
+    result = runner.invoke(app, ["search", "LoreCap", "--db-path", str(tmp_db)])
+    assert result.exit_code == 0
+    assert "LoreCap spec" in result.output
+
+
+def test_write_guard_blocks_add_doc(tmp_db, monkeypatch):
+    """add-doc exits 1 without server package."""
+    from typer.testing import CliRunner
+    from loredocs_cli.main import app
+
+    monkeypatch.setenv("LOREDOCS_ALLOW_EXTERNAL_DB", "1")
+    monkeypatch.setattr("loredocs_cli.main.check_platform", lambda: None)
+    monkeypatch.setattr(
+        "loredocs_cli._write_guard._has_server_package", lambda: False
+    )
+
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        ["add-doc", "side_hustle", "--title", "t", "--body", "b", "--db-path", str(tmp_db)],
+        catch_exceptions=False,
+    )
+    assert result.exit_code == 1
+
+
+def test_sanitize_fts5():
+    """FTS5 injection chars are stripped."""
+    from loredocs_cli._db_path import _sanitize_fts5
+
+    assert '"' not in _sanitize_fts5('find "this"')
+    assert "*" not in _sanitize_fts5("wildcard*")
+    assert _sanitize_fts5("  ") == '""'
+
+
+def test_open_db_missing(tmp_path, capsys):
+    """open_db exits with code 1 when DB not found."""
+    from loredocs_cli._db_path import open_db
+
+    missing = tmp_path / "missing.db"
+    with pytest.raises(SystemExit) as exc:
+        open_db(missing)
+    assert exc.value.code == 1
+    assert "not found" in capsys.readouterr().err
+
+
+def test_schema_compat_normal(tmp_db):
+    """schema compat returns 'normal' for user_version=0."""
+    from loredocs_cli._db_path import open_db
+    from loredocs_cli._schema_compat import check_schema_compatibility
+
+    conn = open_db(tmp_db)
+    result = check_schema_compatibility(conn)
+    assert result == "normal"
+    conn.close()