exemplar-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{exemplar_cli-0.1.2 → exemplar_cli-0.1.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: exemplar-cli
-Version: 0.1.2
-Summary: Exemplar terminal CLI for skills, prompts, and memory
+Version: 0.1.4
+Summary: Exemplar terminal CLI for skills, prompts, gateway catalog, and memory
 License: LicenseRef-Proprietary
 Author: Exemplar Dev LLC
 Requires-Python: >=3.10,<4.0
@@ -10,7 +10,7 @@ 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)
+Requires-Dist: exemplar-core (>=0.1.3,<0.2)
 Description-Content-Type: text/markdown
 
 # exemplar-cli
@@ -71,6 +71,7 @@ exemplar memory search "formatting" --user-id u1
 | `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
 
@@ -82,6 +83,34 @@ exemplar memory search "formatting" --user-id u1
 
 `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`

{exemplar_cli-0.1.2 → exemplar_cli-0.1.4}/README.md

@@ -56,6 +56,7 @@ exemplar memory search "formatting" --user-id u1
 | `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
 
@@ -67,6 +68,34 @@ exemplar memory search "formatting" --user-id u1
 
 `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`

exemplar_cli-0.1.4/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.4/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.4/exemplar_cli/gateway.py

@@ -0,0 +1,111 @@
+"""CLI: exemplar gateway — list AI gateway providers and live models."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from exemplar_core import gateway_from_env
+
+
+def _cmd_providers(args: argparse.Namespace) -> int:
+    providers = gateway_from_env().list_providers(llm_only=not args.all_providers)
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "provider_key": p.provider_key,
+                        "display_name": p.display_name,
+                        "categories": p.categories,
+                    }
+                    for p in providers
+                ],
+                indent=2,
+            )
+        )
+        return 0
+    for item in providers:
+        cats = ",".join(item.categories) or "-"
+        print(f"{item.provider_key}\t{item.display_name}\t{cats}")
+    return 0
+
+
+def _cmd_models(args: argparse.Namespace) -> int:
+    result = gateway_from_env().list_models(args.provider)
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "provider_key": result.provider_key,
+                    "source": result.source,
+                    "error": result.error,
+                    "models": [
+                        {
+                            "gateway_model_id": m.gateway_model_id,
+                            "name": m.name,
+                        }
+                        for m in result.models
+                    ],
+                },
+                indent=2,
+            )
+        )
+        return 0
+    if result.error:
+        print(f"unavailable: {result.error}", file=sys.stderr)
+        return 1
+    for model in result.models:
+        print(f"{model.gateway_model_id}\t{model.name}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="exemplar gateway",
+        description=(
+            "List AI gateway providers and live upstream models from the Exemplar "
+            "integration-service catalog (/api/gateway)."
+        ),
+        epilog=(
+            "Examples:\n"
+            "  exemplar gateway providers\n"
+            "  exemplar gateway models --provider gemini\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    providers_p = sub.add_parser(
+        "providers",
+        help="List gateway LLM providers",
+        description="List providers from integrations/gateway_providers.yaml.",
+    )
+    providers_p.add_argument(
+        "--all-providers",
+        action="store_true",
+        help="Include non-LLM providers (default: LLM only)",
+    )
+    providers_p.add_argument("--json", action="store_true", help="Output JSON")
+    providers_p.set_defaults(func=_cmd_providers)
+
+    models_p = sub.add_parser(
+        "models",
+        help="List live models for a provider",
+        description="Proxy live model list from exemplar-ai-gateway for a connected provider.",
+    )
+    models_p.add_argument(
+        "provider",
+        metavar="PROVIDER",
+        help="Provider key, e.g. openai or gemini",
+    )
+    models_p.add_argument("--json", action="store_true", help="Output JSON")
+    models_p.set_defaults(func=_cmd_models)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

exemplar_cli-0.1.4/exemplar_cli/main.py

@@ -0,0 +1,76 @@
+"""Exemplar CLI entrypoint."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from exemplar_cli.doctor import main as doctor_main
+from exemplar_cli.gateway import main as gateway_main
+from exemplar_cli.memory import main as memory_main
+from exemplar_cli.prompts import main as prompts_main
+from exemplar_cli.skills import main as skills_main
+
+_EPILOG = """
+Commands:
+  skills   Manage org agent skills (pull to Cursor/Claude, push from disk)
+  prompts  Manage versioned prompt templates (create, run, publish)
+  gateway  List AI gateway providers and live models
+  memory   Manage long-term agent memory (add, search, recall)
+  doctor   Verify install, PATH, and EXEMPLAR_API_KEY
+
+Examples:
+  exemplar doctor
+  exemplar skills pull refund-policy
+  exemplar prompts list
+  exemplar gateway providers
+  exemplar memory add "User prefers bullets" --user-id u1
+
+Run `exemplar <command> --help` for full subcommand reference.
+"""
+
+
+def _build_root_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="exemplar",
+        description=(
+            "Exemplar terminal CLI for skills, prompts, and memory. "
+            "Requires EXEMPLAR_API_KEY (run `exemplar doctor` to verify setup)."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_EPILOG,
+    )
+    parser.add_argument(
+        "command",
+        nargs="?",
+        choices=["skills", "memory", "prompts", "gateway", "doctor"],
+        help="Command group to run",
+    )
+    parser.add_argument("args", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = list(argv if argv is not None else sys.argv[1:])
+    if raw and raw[0] in ("skills", "memory", "prompts", "gateway", "doctor"):
+        if raw[0] == "skills":
+            return skills_main(raw[1:])
+        if raw[0] == "memory":
+            return memory_main(raw[1:])
+        if raw[0] == "prompts":
+            return prompts_main(raw[1:])
+        if raw[0] == "gateway":
+            return gateway_main(raw[1:])
+        if raw[0] == "doctor":
+            return doctor_main(raw[1:])
+
+    parser = _build_root_parser()
+    args = parser.parse_args(raw)
+    if args.command is None:
+        parser.print_help()
+        return 2
+    return main([args.command, *args.args])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())