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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: exemplar-cli
-Version: 0.1.2
+Version: 0.1.3
 Summary: Exemplar terminal CLI for skills, prompts, and memory
 License: LicenseRef-Proprietary
 Author: Exemplar Dev LLC
@@ -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.3}/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.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/main.py

@@ -0,0 +1,71 @@
+"""Exemplar CLI entrypoint."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from exemplar_cli.doctor import main as doctor_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)
+  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 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", "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", "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] == "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())

exemplar_cli-0.1.3/exemplar_cli/memory.py

@@ -0,0 +1,264 @@
+"""CLI: exemplar memory — manage long-term memory from the terminal."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+
+from exemplar_core import memory_from_env
+from exemplar_cli._scopes import add_scope_arguments, scopes_from_args
+
+
+def _memory(args: argparse.Namespace):
+    scopes = scopes_from_args(args)
+    return memory_from_env(
+        user_id=scopes.user_id,
+        agent_id=scopes.agent_id,
+        session_id=scopes.session_id,
+        app_id=scopes.app_id,
+    )
+
+
+def _record_dict(record) -> dict:
+    data = asdict(record)
+    if record.scopes is not None:
+        data["scopes"] = record.scopes.to_api_dict()
+    return data
+
+
+def _cmd_add(args: argparse.Namespace) -> int:
+    try:
+        result = _memory(args).add(args.content, memory_type=args.type)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Added memory {result.get('memoryId', '')}")
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    records = _memory(args).list(
+        skip=args.skip,
+        limit=args.limit,
+        memory_type=args.type,
+    )
+    if args.json:
+        print(json.dumps([_record_dict(r) for r in records], indent=2))
+        return 0
+    for record in records:
+        print(f"{record.memory_id}\t[{record.memory_type}]\t{record.content}")
+    return 0
+
+
+def _cmd_get(args: argparse.Namespace) -> int:
+    record = _memory(args).get(args.memory_id)
+    if args.json:
+        print(json.dumps(_record_dict(record), indent=2))
+        return 0
+    print(record.content)
+    return 0
+
+
+def _cmd_search(args: argparse.Namespace) -> int:
+    records = _memory(args).search(
+        args.query,
+        top_k=args.top_k,
+        threshold=args.threshold,
+    )
+    if args.json:
+        print(json.dumps([_record_dict(r) for r in records], indent=2))
+        return 0
+    for record in records:
+        score = f"{record.score:.2f}\t" if record.score is not None else ""
+        print(f"{score}{record.memory_id}\t[{record.memory_type}]\t{record.content}")
+    return 0
+
+
+def _cmd_recall(args: argparse.Namespace) -> int:
+    text = _memory(args).recall(
+        args.query,
+        top_k=args.top_k,
+        threshold=args.threshold,
+    )
+    print(text)
+    return 0
+
+
+def _cmd_update(args: argparse.Namespace) -> int:
+    if args.content is None and args.type is None:
+        print("provide --content and/or --type", file=sys.stderr)
+        return 1
+    try:
+        record = _memory(args).update(
+            args.memory_id,
+            content=args.content,
+            memory_type=args.type,
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(_record_dict(record), indent=2))
+    else:
+        print(f"Updated {record.memory_id}")
+    return 0
+
+
+def _cmd_delete(args: argparse.Namespace) -> int:
+    _memory(args).delete(args.memory_id)
+    print(f"Deleted {args.memory_id}")
+    return 0
+
+
+def _cmd_delete_bulk(args: argparse.Namespace) -> int:
+    try:
+        deleted = _memory(args).delete_bulk(memory_type=args.type)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(f"Deleted {deleted} memory(s)")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="exemplar memory",
+        description=(
+            "Manage long-term agent memory in Exemplar — add facts and preferences, "
+            "search, recall formatted context for prompts, update, and delete."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  exemplar memory add \"User prefers bullets\" --user-id u1 --type preference\n"
+            "  exemplar memory search \"formatting\" --user-id u1\n"
+            "  exemplar memory recall \"how should I format answers?\" --user-id u1\n"
+            "  exemplar memory delete-bulk --user-id u1 --type fact\n"
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    add_p = sub.add_parser(
+        "add",
+        help="Store a new memory record",
+        description="Add a memory string scoped to user, agent, session, or app.",
+    )
+    add_p.add_argument("content", metavar="TEXT", help="Memory content to store")
+    add_p.add_argument(
+        "--type",
+        default="fact",
+        dest="type",
+        metavar="TYPE",
+        help="Memory type label (default: fact)",
+    )
+    add_p.add_argument("--json", action="store_true", help="Output API response as JSON")
+    add_scope_arguments(add_p)
+    add_p.set_defaults(func=_cmd_add)
+
+    list_p = sub.add_parser(
+        "list",
+        help="List memories for the given scope",
+        description="List memory records matching scope filters.",
+    )
+    list_p.add_argument("--type", metavar="TYPE", help="Filter by memory type")
+    list_p.add_argument("--skip", type=int, default=0, help="Skip first N records (default: 0)")
+    list_p.add_argument("--limit", type=int, default=100, help="Maximum results (default: 100)")
+    list_p.add_argument("--json", action="store_true", help="Output JSON instead of TSV")
+    add_scope_arguments(list_p)
+    list_p.set_defaults(func=_cmd_list)
+
+    get_p = sub.add_parser(
+        "get",
+        help="Fetch a memory by ID",
+        description="Retrieve a single memory record by memory_id.",
+    )
+    get_p.add_argument("memory_id", metavar="ID", help="Memory ID")
+    get_p.add_argument("--json", action="store_true", help="Output full record as JSON")
+    add_scope_arguments(get_p)
+    get_p.set_defaults(func=_cmd_get)
+
+    search_p = sub.add_parser(
+        "search",
+        help="Semantic search over memories",
+        description="Search scoped memories by natural-language query.",
+    )
+    search_p.add_argument("query", metavar="QUERY", help="Search query")
+    search_p.add_argument("--top-k", type=int, default=10, help="Maximum results (default: 10)")
+    search_p.add_argument(
+        "--threshold",
+        type=float,
+        default=0.1,
+        help="Minimum similarity score 0–1 (default: 0.1)",
+    )
+    search_p.add_argument("--json", action="store_true", help="Output JSON instead of TSV")
+    add_scope_arguments(search_p)
+    search_p.set_defaults(func=_cmd_search)
+
+    recall_p = sub.add_parser(
+        "recall",
+        help="Print formatted memory context for a query",
+        description=(
+            "Search and format top memories as text suitable for injecting into "
+            "system prompts or agent instructions."
+        ),
+    )
+    recall_p.add_argument("query", metavar="QUERY", help="Question or topic to recall context for")
+    recall_p.add_argument("--top-k", type=int, default=5, help="Maximum memories to include (default: 5)")
+    recall_p.add_argument(
+        "--threshold",
+        type=float,
+        default=0.1,
+        help="Minimum similarity score 0–1 (default: 0.1)",
+    )
+    add_scope_arguments(recall_p)
+    recall_p.set_defaults(func=_cmd_recall)
+
+    update_p = sub.add_parser(
+        "update",
+        help="Update an existing memory",
+        description="Change content and/or type of a memory record.",
+    )
+    update_p.add_argument("memory_id", metavar="ID", help="Memory ID")
+    update_p.add_argument("--content", metavar="TEXT", help="New memory content")
+    update_p.add_argument("--type", metavar="TYPE", help="New memory type")
+    update_p.add_argument("--json", action="store_true", help="Output updated record as JSON")
+    add_scope_arguments(update_p)
+    update_p.set_defaults(func=_cmd_update)
+
+    delete_p = sub.add_parser(
+        "delete",
+        help="Delete a memory by ID",
+        description="Remove a single memory record.",
+    )
+    delete_p.add_argument("memory_id", metavar="ID", help="Memory ID")
+    add_scope_arguments(delete_p)
+    delete_p.set_defaults(func=_cmd_delete)
+
+    bulk_p = sub.add_parser(
+        "delete-bulk",
+        help="Delete many memories matching scope filters",
+        description=(
+            "Bulk-delete memories for the given scope. Requires at least one scope flag. "
+            "Optionally filter by --type."
+        ),
+    )
+    bulk_p.add_argument("--type", metavar="TYPE", help="Only delete memories of this type")
+    add_scope_arguments(bulk_p)
+    bulk_p.set_defaults(func=_cmd_delete_bulk)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())