exemplar-cli 0.1.1__tar.gz → 0.1.3__tar.gz

exemplar_cli-0.1.3/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.1
+Name: exemplar-cli
+Version: 0.1.3
+Summary: Exemplar terminal CLI for skills, prompts, and memory
+License: LicenseRef-Proprietary
+Author: Exemplar Dev LLC
+Requires-Python: >=3.10,<4.0
+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
+Requires-Dist: exemplar-core (>=0.1.2,<0.2)
+Description-Content-Type: text/markdown
+
+# exemplar-cli
+
+Terminal CLI for Exemplar **skills** and **memory**.
+
+## Install
+
+**Recommended** — isolated install with automatic PATH setup:
+
+```bash
+pipx install exemplar-cli
+```
+
+Other options:
+
+```bash
+# System / python.org install (macOS, Linux)
+pip install exemplar-cli
+
+# User install (no sudo)
+pip install --user exemplar-cli
+```
+
+After install, verify everything:
+
+```bash
+exemplar doctor
+```
+
+If you see `command not found: exemplar`, the package is installed but its `bin/`
+directory is not on your `PATH`. `exemplar doctor` prints the exact fix for your
+machine. Common cases:
+
+| Install method | Scripts directory |
+|----------------|-------------------|
+| `pipx install` | `~/.local/bin` (pipx adds this automatically) |
+| python.org macOS | `/Library/Frameworks/Python.framework/Versions/3.x/bin` |
+| `pip install --user` | `~/Library/Python/3.x/bin` (macOS) or `~/.local/bin` (Linux) |
+
+Open a **new terminal** after changing shell profile files.
+
+## Quick start
+
+```bash
+export EXEMPLAR_API_KEY=eis_...
+
+exemplar doctor
+exemplar skills list
+exemplar memory add "User prefers bullet points" --user-id u1 --type preference
+exemplar memory search "formatting" --user-id u1
+```
+
+## Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `EXEMPLAR_API_KEY` | Org API key (required) |
+| `EXEMPLAR_BASE_URL` | API host override (optional) |
+| `EXEMPLAR_ORGANIZATION_ID` | Org override for JWT auth (optional) |
+| `EXEMPLAR_SKILLS_TARGET` | Default skill install preset: `cursor`, `cursor-global`, `claude`, `claude-global` |
+
+## Commands
+
+### Doctor
+
+`exemplar doctor` — check package install, `PATH`, and required environment variables.
+
+### Skills
+
+`list`, `get`, `search`, `pull`, `push`, `init`, `export-zip`
+
+**Skill install destinations** (`pull`, `init`):
+
+| Target | Path | Confirmation |
+|--------|------|----------------|
+| `cursor` (default) | `.cursor/skills` | No |
+| `cursor-global` | `~/.cursor/skills` | No |
+| `claude` | `.claude/skills` | Yes |
+| `claude-global` | `~/.claude/skills` | Yes |
+
+```bash
+# Default — Cursor project skills (no prompt)
+exemplar skills pull refund-policy
+
+# Global Cursor skills
+exemplar skills pull refund-policy --global
+
+# Claude Code — asks for confirmation (or use -y)
+exemplar skills pull refund-policy --target claude-global
+
+# Pick interactively when multiple agents are installed
+exemplar skills pull --all -i
+
+# Override with a custom directory
+exemplar skills pull refund-policy --dest ./my-skills
+```
+
+Set a default via `EXEMPLAR_SKILLS_TARGET=cursor-global`.
+
+### Prompts
+
+`list`, `get`, `search`, `create`, `run`, `publish`, `delete`
+
+### Memory
+
+`add`, `list`, `get`, `search`, `recall`, `update`, `delete`, `delete-bulk`
+
+Memory commands accept scope flags: `--user-id`, `--agent-id`, `--session-id`, `--app-id`.
+

exemplar_cli-0.1.3/README.md

@@ -0,0 +1,107 @@
+# exemplar-cli
+
+Terminal CLI for Exemplar **skills** and **memory**.
+
+## Install
+
+**Recommended** — isolated install with automatic PATH setup:
+
+```bash
+pipx install exemplar-cli
+```
+
+Other options:
+
+```bash
+# System / python.org install (macOS, Linux)
+pip install exemplar-cli
+
+# User install (no sudo)
+pip install --user exemplar-cli
+```
+
+After install, verify everything:
+
+```bash
+exemplar doctor
+```
+
+If you see `command not found: exemplar`, the package is installed but its `bin/`
+directory is not on your `PATH`. `exemplar doctor` prints the exact fix for your
+machine. Common cases:
+
+| Install method | Scripts directory |
+|----------------|-------------------|
+| `pipx install` | `~/.local/bin` (pipx adds this automatically) |
+| python.org macOS | `/Library/Frameworks/Python.framework/Versions/3.x/bin` |
+| `pip install --user` | `~/Library/Python/3.x/bin` (macOS) or `~/.local/bin` (Linux) |
+
+Open a **new terminal** after changing shell profile files.
+
+## Quick start
+
+```bash
+export EXEMPLAR_API_KEY=eis_...
+
+exemplar doctor
+exemplar skills list
+exemplar memory add "User prefers bullet points" --user-id u1 --type preference
+exemplar memory search "formatting" --user-id u1
+```
+
+## Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `EXEMPLAR_API_KEY` | Org API key (required) |
+| `EXEMPLAR_BASE_URL` | API host override (optional) |
+| `EXEMPLAR_ORGANIZATION_ID` | Org override for JWT auth (optional) |
+| `EXEMPLAR_SKILLS_TARGET` | Default skill install preset: `cursor`, `cursor-global`, `claude`, `claude-global` |
+
+## Commands
+
+### Doctor
+
+`exemplar doctor` — check package install, `PATH`, and required environment variables.
+
+### Skills
+
+`list`, `get`, `search`, `pull`, `push`, `init`, `export-zip`
+
+**Skill install destinations** (`pull`, `init`):
+
+| Target | Path | Confirmation |
+|--------|------|----------------|
+| `cursor` (default) | `.cursor/skills` | No |
+| `cursor-global` | `~/.cursor/skills` | No |
+| `claude` | `.claude/skills` | Yes |
+| `claude-global` | `~/.claude/skills` | Yes |
+
+```bash
+# Default — Cursor project skills (no prompt)
+exemplar skills pull refund-policy
+
+# Global Cursor skills
+exemplar skills pull refund-policy --global
+
+# Claude Code — asks for confirmation (or use -y)
+exemplar skills pull refund-policy --target claude-global
+
+# Pick interactively when multiple agents are installed
+exemplar skills pull --all -i
+
+# Override with a custom directory
+exemplar skills pull refund-policy --dest ./my-skills
+```
+
+Set a default via `EXEMPLAR_SKILLS_TARGET=cursor-global`.
+
+### Prompts
+
+`list`, `get`, `search`, `create`, `run`, `publish`, `delete`
+
+### Memory
+
+`add`, `list`, `get`, `search`, `recall`, `update`, `delete`, `delete-bulk`
+
+Memory commands accept scope flags: `--user-id`, `--agent-id`, `--session-id`, `--app-id`.

exemplar_cli-0.1.3/exemplar_cli/_scopes.py

@@ -0,0 +1,49 @@
+"""Shared CLI helpers."""
+
+from __future__ import annotations
+
+import argparse
+
+from exemplar_core.memory.models import MemoryScopes
+
+
+def add_scope_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add memory scope flags (at least one required for most memory commands)."""
+    scope = parser.add_argument_group(
+        "memory scope",
+        "Scope memories to a user, agent, session, or app. At least one scope flag is "
+        "required for add, list, search, recall, update, delete, and delete-bulk.",
+    )
+    scope.add_argument(
+        "--user-id",
+        dest="user_id",
+        metavar="ID",
+        help="End-user identifier (e.g. u123)",
+    )
+    scope.add_argument(
+        "--agent-id",
+        dest="agent_id",
+        metavar="ID",
+        help="Agent identifier within your org",
+    )
+    scope.add_argument(
+        "--session-id",
+        dest="session_id",
+        metavar="ID",
+        help="Conversation or eval session identifier",
+    )
+    scope.add_argument(
+        "--app-id",
+        dest="app_id",
+        metavar="ID",
+        help="Source application identifier",
+    )
+
+
+def scopes_from_args(args: argparse.Namespace) -> MemoryScopes:
+    return MemoryScopes(
+        user_id=args.user_id,
+        agent_id=args.agent_id,
+        session_id=args.session_id,
+        app_id=args.app_id,
+    )

exemplar_cli-0.1.3/exemplar_cli/_skill_targets.py

@@ -0,0 +1,205 @@
+"""Resolve local skill install destinations for Cursor, Claude, and custom paths."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+SkillTargetId = Literal["cursor", "cursor-global", "claude", "claude-global"]
+
+DEFAULT_TARGET_ID: SkillTargetId = "cursor"
+CONFIRM_TARGETS = frozenset({"claude", "claude-global"})
+
+
+@dataclass(frozen=True)
+class SkillTarget:
+    target_id: SkillTargetId
+    agent: str
+    scope: str
+    relative: bool
+
+    @property
+    def label(self) -> str:
+        return f"{self.agent} ({self.scope})"
+
+    def resolve_path(self) -> Path:
+        if self.target_id == "cursor":
+            return Path(".cursor") / "skills"
+        if self.target_id == "cursor-global":
+            return Path.home() / ".cursor" / "skills"
+        if self.target_id == "claude":
+            return Path(".claude") / "skills"
+        if self.target_id == "claude-global":
+            return Path.home() / ".claude" / "skills"
+        raise ValueError(f"unknown target: {self.target_id}")
+
+
+TARGETS: dict[SkillTargetId, SkillTarget] = {
+    "cursor": SkillTarget("cursor", "Cursor", "project", relative=True),
+    "cursor-global": SkillTarget("cursor-global", "Cursor", "global", relative=False),
+    "claude": SkillTarget("claude", "Claude Code", "project", relative=True),
+    "claude-global": SkillTarget("claude-global", "Claude Code", "global", relative=False),
+}
+
+
+def _env_target() -> SkillTargetId | None:
+    raw = (os.environ.get("EXEMPLAR_SKILLS_TARGET") or "").strip().lower()
+    if not raw:
+        return None
+    if raw in ("cursor", "cursor-global", "claude", "claude-global"):
+        return raw  # type: ignore[return-value]
+    if raw == "global":
+        return "cursor-global"
+    raise ValueError(
+        f"invalid EXEMPLAR_SKILLS_TARGET={raw!r}; "
+        "use cursor, cursor-global, claude, or claude-global"
+    )
+
+
+def _agent_hint_present(target_id: SkillTargetId) -> bool:
+    if target_id.startswith("cursor"):
+        home = Path.home() / ".cursor"
+        return home.is_dir() or (Path.cwd() / ".cursor").is_dir()
+    if target_id.startswith("claude"):
+        home = Path.home() / ".claude"
+        return home.is_dir() or (Path.cwd() / ".claude").is_dir()
+    return False
+
+
+def detect_available_targets() -> list[SkillTargetId]:
+    """Targets whose agent directories appear to exist on this machine."""
+    available: list[SkillTargetId] = []
+    for target_id in TARGETS:
+        if _agent_hint_present(target_id):
+            available.append(target_id)
+    return available or [DEFAULT_TARGET_ID]
+
+
+def _is_interactive() -> bool:
+    if os.environ.get("EXEMPLAR_SKILLS_INTERACTIVE", "").lower() in ("1", "true", "yes"):
+        return True
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _confirm(message: str) -> bool:
+    try:
+        answer = input(f"{message} [y/N]: ").strip().lower()
+    except EOFError:
+        return False
+    return answer in ("y", "yes")
+
+
+def _pick_target_interactively() -> SkillTargetId:
+    options = detect_available_targets()
+    if len(options) == 1:
+        return options[0]
+
+    print("Where should skills be installed?\n")
+    for index, target_id in enumerate(options, start=1):
+        target = TARGETS[target_id]
+        path = target.resolve_path()
+        print(f"  [{index}] {target.label:<22}  {path}")
+    print(f"  [0] {TARGETS[DEFAULT_TARGET_ID].label:<22}  {TARGETS[DEFAULT_TARGET_ID].resolve_path()} (default)")
+
+    default_choice = "0"
+    if DEFAULT_TARGET_ID in options:
+        default_choice = str(options.index(DEFAULT_TARGET_ID) + 1)
+
+    try:
+        raw = input(f"\nChoose destination [{default_choice}]: ").strip()
+    except EOFError:
+        return DEFAULT_TARGET_ID
+
+    if not raw:
+        if default_choice == "0":
+            return DEFAULT_TARGET_ID
+        return options[int(default_choice) - 1]
+
+    if raw == "0":
+        return DEFAULT_TARGET_ID
+    if raw.isdigit() and 1 <= int(raw) <= len(options):
+        return options[int(raw) - 1]
+
+    lowered = raw.lower()
+    if lowered in TARGETS:
+        return lowered  # type: ignore[return-value]
+    return DEFAULT_TARGET_ID
+
+
+def _normalize_legacy_global(
+    *,
+    target: SkillTargetId | None,
+    global_flag: bool,
+) -> SkillTargetId | None:
+    if target is not None:
+        return target
+    if global_flag:
+        return "cursor-global"
+    return None
+
+
+def resolve_skill_target(
+    *,
+    dest: str | None = None,
+    target: str | None = None,
+    global_flag: bool = False,
+    yes: bool = False,
+    no_input: bool = False,
+    interactive: bool = False,
+) -> tuple[Path, SkillTarget | None]:
+    """
+    Resolve pull/init destination.
+
+    Returns (path, target_meta). target_meta is None when `dest` is explicit.
+    """
+    if dest:
+        return Path(dest), None
+
+    target_id: SkillTargetId | None
+    try:
+        target_id = _env_target()
+    except ValueError as exc:
+        raise SystemExit(str(exc)) from exc
+
+    if target:
+        lowered = target.strip().lower()
+        if lowered == "global":
+            lowered = "cursor-global"
+        if lowered not in TARGETS:
+            raise SystemExit(
+                f"unknown --target {target!r}; choose from: cursor, cursor-global, claude, claude-global"
+            )
+        target_id = lowered  # type: ignore[assignment]
+
+    target_id = _normalize_legacy_global(target=target_id, global_flag=global_flag)
+
+    if target_id is None and interactive and _is_interactive() and not no_input:
+        target_id = _pick_target_interactively()
+    elif target_id is None:
+        target_id = DEFAULT_TARGET_ID
+
+    meta = TARGETS[target_id]
+    path = meta.resolve_path()
+
+    if target_id in CONFIRM_TARGETS and not yes:
+        if no_input:
+            raise SystemExit(
+                f"{meta.label} requires confirmation; re-run with --yes or use --target cursor"
+            )
+        if not _is_interactive():
+            raise SystemExit(
+                f"{meta.label} ({path}) requires confirmation; re-run with --yes in non-interactive mode"
+            )
+        if not _confirm(f"Install skills to {path} for {meta.agent}?"):
+            raise SystemExit("cancelled")
+
+    return path, meta
+
+
+def format_destination_banner(path: Path, meta: SkillTarget | None) -> str:
+    if meta is None:
+        return f"Destination: {path}"
+    return f"Destination: {meta.label}  →  {path}"

exemplar_cli-0.1.3/exemplar_cli/doctor.py

@@ -0,0 +1,166 @@
+"""exemplar doctor — diagnose CLI install, PATH, and environment."""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import site
+import sys
+from importlib.metadata import PackageNotFoundError, distribution
+from pathlib import Path
+
+
+def _path_entries() -> list[Path]:
+    entries: list[Path] = []
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        if not entry:
+            continue
+        try:
+            entries.append(Path(entry).resolve())
+        except OSError:
+            continue
+    return entries
+
+
+def _locate_installed_script() -> Path | None:
+    """Find the exemplar console script when it is not on PATH."""
+    candidates: list[Path] = [
+        Path(sys.prefix) / "bin" / "exemplar",
+        Path(sys.executable).resolve().parent / "exemplar",
+    ]
+
+    user_base = site.USER_BASE
+    if user_base:
+        candidates.append(Path(user_base) / "bin" / "exemplar")
+
+    if sys.platform == "darwin":
+        version = f"{sys.version_info.major}.{sys.version_info.minor}"
+        candidates.append(
+            Path(f"/Library/Frameworks/Python.framework/Versions/{version}/bin/exemplar")
+        )
+
+    try:
+        dist = distribution("exemplar-cli")
+        for path in dist.files or ():
+            normalized = str(path).replace("\\", "/")
+            if normalized.endswith("/bin/exemplar") or normalized == "../../../bin/exemplar":
+                root = Path(dist.locate_file(""))
+                candidates.append((root / path).resolve())
+    except PackageNotFoundError:
+        pass
+
+    seen: set[Path] = set()
+    for candidate in candidates:
+        try:
+            resolved = candidate.resolve()
+        except OSError:
+            continue
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        if resolved.is_file():
+            return resolved
+    return None
+
+
+def _script_dir_on_path(script_dir: Path) -> bool:
+    try:
+        resolved = script_dir.resolve()
+    except OSError:
+        return False
+    return resolved in _path_entries()
+
+
+def _path_fix_lines(script_dir: Path) -> list[str]:
+    export_line = f'export PATH="{script_dir}:$PATH"'
+    return [
+        "Add one of the following to ~/.zprofile (macOS login shells) or ~/.zshrc:",
+        f"  {export_line}",
+        "",
+        "Or symlink into a directory already on PATH:",
+        f"  ln -sf {script_dir / 'exemplar'} ~/.local/bin/exemplar",
+        "",
+        "Recommended for CLI tools:",
+        "  pipx install exemplar-cli",
+    ]
+
+
+def _check_api_key() -> tuple[bool, str]:
+    key = os.environ.get("EXEMPLAR_API_KEY", "").strip()
+    if key:
+        return True, "EXEMPLAR_API_KEY is set"
+    return False, "EXEMPLAR_API_KEY is not set (required for skills/memory commands)"
+
+
+def main(argv: list[str] | None = None) -> int:
+    del argv  # doctor accepts no subcommands yet
+    issues = 0
+
+    print("Exemplar doctor")
+    print("===============")
+
+    print(
+        f"Python: {platform.python_version()} "
+        f"({platform.machine()}, {sys.executable})"
+    )
+
+    try:
+        version = distribution("exemplar-cli").version
+        print(f"exemplar-cli package: installed ({version})")
+    except PackageNotFoundError:
+        issues += 1
+        print("exemplar-cli package: NOT INSTALLED")
+        print("  Install with: pipx install exemplar-cli")
+        print("            or: pip install exemplar-cli")
+        return 1
+
+    command = shutil.which("exemplar")
+    if command:
+        print(f"exemplar command: OK ({command})")
+    else:
+        issues += 1
+        script = _locate_installed_script()
+        print("exemplar command: NOT ON PATH")
+        if script:
+            print(f"  Script installed at: {script}")
+            if not _script_dir_on_path(script.parent):
+                print("  Fix:")
+                for line in _path_fix_lines(script.parent):
+                    print(f"    {line}" if line else "")
+            else:
+                print("  Script directory is on PATH; open a new terminal or run:")
+                print("    source ~/.zprofile")
+        else:
+            print("  Could not locate the exemplar script.")
+            print("  Reinstall with: pipx install exemplar-cli")
+
+    api_ok, api_msg = _check_api_key()
+    if api_ok:
+        print(f"API key: OK — {api_msg}")
+    else:
+        issues += 1
+        print(f"API key: MISSING — {api_msg}")
+        print("  Set with: export EXEMPLAR_API_KEY=eis_...")
+
+    base_url = os.environ.get("EXEMPLAR_BASE_URL", "").strip()
+    if base_url:
+        print(f"API base URL: {base_url}")
+    else:
+        print("API base URL: default (https://api.exemplar.dev)")
+
+    org_id = os.environ.get("EXEMPLAR_ORGANIZATION_ID", "").strip()
+    if org_id:
+        print(f"Organization override: {org_id}")
+
+    print()
+    if issues:
+        print(f"{issues} issue(s) found.")
+        return 1
+
+    print("All checks passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())