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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: exemplar-cli
-Version: 0.1.1
-Summary: Exemplar terminal CLI for skills and memory
+Version: 0.1.2
+Summary: Exemplar terminal CLI for skills, prompts, and memory
 License: LicenseRef-Proprietary
 Author: Exemplar Dev LLC
 Requires-Python: >=3.10,<4.0
@@ -10,17 +10,55 @@ 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.1,<0.2)
+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
@@ -36,10 +74,18 @@ exemplar memory search "formatting" --user-id u1
 
 ## Commands
 
+### Doctor
+
+`exemplar doctor` — check package install, `PATH`, and required environment variables.
+
 ### Skills
 
 `list`, `get`, `search`, `pull`, `push`, `init`, `export-zip`
 
+### Prompts
+
+`list`, `get`, `search`, `create`, `run`, `publish`, `delete`
+
 ### Memory
 
 `add`, `list`, `get`, `search`, `recall`, `update`, `delete`, `delete-bulk`

exemplar_cli-0.1.2/README.md

@@ -0,0 +1,78 @@
+# 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) |
+
+## Commands
+
+### Doctor
+
+`exemplar doctor` — check package install, `PATH`, and required environment variables.
+
+### Skills
+
+`list`, `get`, `search`, `pull`, `push`, `init`, `export-zip`
+
+### 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.2/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())

{exemplar_cli-0.1.1 → exemplar_cli-0.1.2}/exemplar_cli/main.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 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
 
 
@@ -14,10 +16,16 @@ def main(argv: list[str] | None = None) -> int:
         return skills_main(args[1:])
     if args and args[0] == "memory":
         return memory_main(args[1:])
+    if args and args[0] == "prompts":
+        return prompts_main(args[1:])
+    if args and args[0] == "doctor":
+        return doctor_main(args[1:])
     print(
-        "Usage: exemplar <skills|memory> <subcommand> ...\n"
+        "Usage: exemplar <skills|memory|prompts|doctor> <subcommand> ...\n"
         "  exemplar skills list|get|search|pull|push|init|export-zip\n"
-        "  exemplar memory add|list|get|search|recall|update|delete|delete-bulk",
+        "  exemplar memory add|list|get|search|recall|update|delete|delete-bulk\n"
+        "  exemplar prompts list|get|search|create|run|publish|delete\n"
+        "  exemplar doctor",
         file=sys.stderr,
     )
     return 2

exemplar_cli-0.1.2/exemplar_cli/prompts.py

@@ -0,0 +1,171 @@
+"""CLI: exemplar prompts — manage org prompt registry from the terminal."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+
+from exemplar_core import prompts_from_env
+
+
+def _record_dict(record) -> dict:
+    data = asdict(record)
+    if hasattr(record, "messages"):
+        data["messages"] = [{"role": m.role, "content": m.content} for m in record.messages]
+    return data
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    items = prompts_from_env().list(limit=args.limit, q=args.q)
+    if args.json:
+        print(json.dumps([item.__dict__ for item in items], indent=2))
+        return 0
+    for item in items:
+        tags = ",".join(item.tags) if item.tags else ""
+        suffix = f" [{tags}]" if tags else ""
+        print(f"{item.name}\t{item.prompt_id}\tv{item.current_version}{suffix}")
+    return 0
+
+
+def _cmd_get(args: argparse.Namespace) -> int:
+    record = prompts_from_env().get(args.prompt_id)
+    if args.json:
+        print(json.dumps(_record_dict(record), indent=2))
+        return 0
+    for message in record.messages:
+        print(f"[{message.role}]\n{message.content}\n")
+    return 0
+
+
+def _cmd_search(args: argparse.Namespace) -> int:
+    results = prompts_from_env().search(args.query, top_k=args.top_k)
+    if args.json:
+        print(json.dumps([item.__dict__ for item in results], indent=2))
+        return 0
+    for item in results:
+        print(f"{item.name}\t{item.title}")
+    return 0
+
+
+def _cmd_create(args: argparse.Namespace) -> int:
+    messages = [{"role": "system", "content": args.system}]
+    if args.user:
+        messages.append({"role": "user", "content": args.user})
+    variables = [v.strip() for v in args.variables.split(",") if v.strip()] if args.variables else []
+    record = prompts_from_env().create(
+        name=args.name,
+        title=args.title,
+        description=args.description,
+        messages=messages,
+        variables=variables,
+        tags=[t.strip() for t in args.tags.split(",") if t.strip()] if args.tags else [],
+    )
+    if args.json:
+        print(json.dumps(_record_dict(record), indent=2))
+    else:
+        print(f"Created {record.name} ({record.prompt_id})")
+    return 0
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    variables = {}
+    for pair in args.var or []:
+        if "=" not in pair:
+            print(f"expected KEY=VALUE, got {pair!r}", file=sys.stderr)
+            return 1
+        key, value = pair.split("=", 1)
+        variables[key.strip()] = value
+    result = prompts_from_env().run(args.prompt_id, variables=variables, model=args.model)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(result.get("content") or json.dumps(result))
+    return 0
+
+
+def _cmd_publish(args: argparse.Namespace) -> int:
+    messages = [{"role": "system", "content": args.system}]
+    if args.user:
+        messages.append({"role": "user", "content": args.user})
+    record = prompts_from_env().publish_version(
+        args.prompt_id,
+        messages=messages,
+        change_notes=args.notes,
+    )
+    if args.json:
+        print(json.dumps(_record_dict(record), indent=2))
+    else:
+        print(f"Published v{record.current_version} for {record.name}")
+    return 0
+
+
+def _cmd_delete(args: argparse.Namespace) -> int:
+    prompts_from_env().delete(args.prompt_id)
+    print(f"Deleted {args.prompt_id}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="exemplar prompts")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    list_p = sub.add_parser("list", help="List org prompts")
+    list_p.add_argument("--q")
+    list_p.add_argument("--limit", type=int, default=100)
+    list_p.add_argument("--json", action="store_true")
+    list_p.set_defaults(func=_cmd_list)
+
+    get_p = sub.add_parser("get", help="Get prompt by ID")
+    get_p.add_argument("prompt_id")
+    get_p.add_argument("--json", action="store_true")
+    get_p.set_defaults(func=_cmd_get)
+
+    search_p = sub.add_parser("search", help="Search prompts")
+    search_p.add_argument("query")
+    search_p.add_argument("--top-k", type=int, default=20)
+    search_p.add_argument("--json", action="store_true")
+    search_p.set_defaults(func=_cmd_search)
+
+    create_p = sub.add_parser("create", help="Create a prompt")
+    create_p.add_argument("name")
+    create_p.add_argument("--title", required=True)
+    create_p.add_argument("--description", default="")
+    create_p.add_argument("--system", required=True, help="System message content")
+    create_p.add_argument("--user", help="Optional user message template")
+    create_p.add_argument("--variables", help="Comma-separated variable names")
+    create_p.add_argument("--tags", help="Comma-separated tags")
+    create_p.add_argument("--json", action="store_true")
+    create_p.set_defaults(func=_cmd_create)
+
+    run_p = sub.add_parser("run", help="Run a prompt with variables")
+    run_p.add_argument("prompt_id")
+    run_p.add_argument("--var", action="append", metavar="KEY=VALUE", help="Template variable")
+    run_p.add_argument("--model")
+    run_p.add_argument("--json", action="store_true")
+    run_p.set_defaults(func=_cmd_run)
+
+    publish_p = sub.add_parser("publish", help="Publish a new prompt version")
+    publish_p.add_argument("prompt_id")
+    publish_p.add_argument("--system", required=True)
+    publish_p.add_argument("--user")
+    publish_p.add_argument("--notes", default="CLI publish")
+    publish_p.add_argument("--json", action="store_true")
+    publish_p.set_defaults(func=_cmd_publish)
+
+    delete_p = sub.add_parser("delete", help="Delete a prompt")
+    delete_p.add_argument("prompt_id")
+    delete_p.set_defaults(func=_cmd_delete)
+
+    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())

{exemplar_cli-0.1.1 → exemplar_cli-0.1.2}/exemplar_cli/skills.py

@@ -56,60 +56,59 @@ def _cmd_pull(args: argparse.Namespace) -> int:
     if args.all:
         items = client.list(limit=500)
         for item in items:
-            _write_skill_md(client, item.name, dest_root / item.name)
-        print(f"Pulled {len(items)} skill(s) to {dest_root}")
+            out = dest_root / item.name
+            client.export_folder(item.name, out)
+        print(f"Pulled {len(items)} skill folder(s) to {dest_root}")
         return 0
 
     if not args.name:
         print("skill name required unless --all is set", file=sys.stderr)
         return 1
 
-    _write_skill_md(client, args.name, dest_root / args.name)
-    print(f"Pulled {args.name} to {dest_root / args.name / 'SKILL.md'}")
+    out = dest_root / args.name
+    client.export_folder(args.name, out)
+    print(f"Pulled {args.name} to {out}")
     return 0
 
 
-def _write_skill_md(client, name: str, dest_dir: Path) -> None:
-    dest_dir.mkdir(parents=True, exist_ok=True)
-    content = client.export_skill_md(name)
-    (dest_dir / "SKILL.md").write_text(content, encoding="utf-8")
+def _resolve_skill_dir(path: Path) -> tuple[Path, Path]:
+    if path.is_dir():
+        return path, path / "SKILL.md"
+    return path.parent, path
 
 
 def _cmd_push(args: argparse.Namespace) -> int:
     path = Path(args.path)
-    if path.is_dir():
-        skill_file = path / "SKILL.md"
-    else:
-        skill_file = path
+    skill_dir, skill_file = _resolve_skill_dir(path)
     if not skill_file.is_file():
         print(f"SKILL.md not found: {skill_file}", file=sys.stderr)
         return 1
 
     parsed = parse_skill_md(skill_file.read_text(encoding="utf-8"))
-    name = (parsed.get("name") or path.parent.name or path.stem).strip()
+    name = (parsed.get("name") or skill_dir.name or path.stem).strip()
     if not name:
         print("could not determine skill name from frontmatter or path", file=sys.stderr)
         return 1
 
     skills = skills_from_env()
-    body = {
-        "instructions": parsed.get("instructions") or "",
-        "description": parsed.get("description") or "",
-    }
+    instructions = parsed.get("instructions") or ""
+    description = parsed.get("description") or ""
     try:
         existing = skills.get(name)
-        record = skills.update(
+        skills.update(
             existing.skill_id,
-            instructions=body["instructions"],
-            description=body["description"],
+            instructions=instructions,
+            description=description or None,
         )
+        record = skills.import_folder(existing.skill_id, skill_dir, prune=args.prune)
         print(f"Updated {record.name} ({record.skill_id})")
     except ValueError:
         record = skills.create(
             name=name,
-            instructions=body["instructions"],
-            description=body.get("description"),
+            instructions=instructions,
+            description=description or None,
         )
+        record = skills.import_folder(record.skill_id, skill_dir, prune=args.prune)
         print(f"Created {record.name} ({record.skill_id})")
     return 0
 
@@ -163,15 +162,20 @@ def build_parser() -> argparse.ArgumentParser:
     search_p.add_argument("--json", action="store_true")
     search_p.set_defaults(func=_cmd_search)
 
-    pull_p = sub.add_parser("pull", help="Export skill(s) to local SKILL.md")
+    pull_p = sub.add_parser("pull", help="Export skill folder(s) from registry")
     pull_p.add_argument("name", nargs="?")
     pull_p.add_argument("--all", action="store_true")
     pull_p.add_argument("--dest")
     pull_p.add_argument("--global", dest="global_dest", action="store_true")
     pull_p.set_defaults(func=_cmd_pull)
 
-    push_p = sub.add_parser("push", help="Upload local SKILL.md to registry")
+    push_p = sub.add_parser("push", help="Upload local skill folder to registry")
     push_p.add_argument("path")
+    push_p.add_argument(
+        "--prune",
+        action="store_true",
+        help="Remove remote files not present in local folder",
+    )
     push_p.set_defaults(func=_cmd_push)
 
     init_p = sub.add_parser("init", help="Scaffold local skill directory")

{exemplar_cli-0.1.1 → exemplar_cli-0.1.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "exemplar-cli"
-version = "0.1.1"
-description = "Exemplar terminal CLI for skills and memory"
+version = "0.1.2"
+description = "Exemplar terminal CLI for skills, prompts, and memory"
 authors = ["Exemplar Dev LLC"]
 license = "LicenseRef-Proprietary"
 readme = "README.md"
@@ -9,7 +9,7 @@ packages = [{ include = "exemplar_cli" }]
 
 [tool.poetry.dependencies]
 python = ">=3.10,<4.0"
-exemplar-core = ">=0.1.1,<0.2"
+exemplar-core = ">=0.1.2,<0.2"
 
 [tool.poetry.scripts]
 exemplar = "exemplar_cli.main:main"

exemplar_cli-0.1.1/README.md

@@ -1,32 +0,0 @@
-# exemplar-cli
-
-Terminal CLI for Exemplar **skills** and **memory**.
-
-```bash
-pip install exemplar-cli
-export EXEMPLAR_API_KEY=eis_...
-
-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) |
-
-## Commands
-
-### Skills
-
-`list`, `get`, `search`, `pull`, `push`, `init`, `export-zip`
-
-### Memory
-
-`add`, `list`, `get`, `search`, `recall`, `update`, `delete`, `delete-bulk`
-
-Memory commands accept scope flags: `--user-id`, `--agent-id`, `--session-id`, `--app-id`.