exemplar-cli 0.1.0__tar.gz

exemplar_cli-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.1
+Name: exemplar-cli
+Version: 0.1.0
+Summary: Exemplar terminal CLI for skills and memory
+License: LicenseRef-Proprietary
+Author: Exemplar Dev LLC
+Requires-Python: >=3.10,<3.14
+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.0,<0.2)
+Description-Content-Type: text/markdown
+
+# 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`.
+

exemplar_cli-0.1.0/README.md

@@ -0,0 +1,32 @@
+# 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`.

exemplar_cli-0.1.0/exemplar_cli/_scopes.py

@@ -0,0 +1,23 @@
+"""Shared CLI helpers."""
+
+from __future__ import annotations
+
+import argparse
+
+from exemplar_core.memory.models import MemoryScopes
+
+
+def add_scope_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--user-id", dest="user_id")
+    parser.add_argument("--agent-id", dest="agent_id")
+    parser.add_argument("--session-id", dest="session_id")
+    parser.add_argument("--app-id", dest="app_id")
+
+
+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.0/exemplar_cli/main.py

@@ -0,0 +1,27 @@
+"""Exemplar CLI entrypoint."""
+
+from __future__ import annotations
+
+import sys
+
+from exemplar_cli.memory import main as memory_main
+from exemplar_cli.skills import main as skills_main
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv if argv is not None else sys.argv[1:])
+    if args and args[0] == "skills":
+        return skills_main(args[1:])
+    if args and args[0] == "memory":
+        return memory_main(args[1:])
+    print(
+        "Usage: exemplar <skills|memory> <subcommand> ...\n"
+        "  exemplar skills list|get|search|pull|push|init|export-zip\n"
+        "  exemplar memory add|list|get|search|recall|update|delete|delete-bulk",
+        file=sys.stderr,
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

exemplar_cli-0.1.0/exemplar_cli/memory.py

@@ -0,0 +1,196 @@
+"""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")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    add_p = sub.add_parser("add", help="Add a memory")
+    add_p.add_argument("content")
+    add_p.add_argument("--type", default="fact", dest="type")
+    add_p.add_argument("--json", action="store_true")
+    add_scope_arguments(add_p)
+    add_p.set_defaults(func=_cmd_add)
+
+    list_p = sub.add_parser("list", help="List memories")
+    list_p.add_argument("--type")
+    list_p.add_argument("--skip", type=int, default=0)
+    list_p.add_argument("--limit", type=int, default=100)
+    list_p.add_argument("--json", action="store_true")
+    add_scope_arguments(list_p)
+    list_p.set_defaults(func=_cmd_list)
+
+    get_p = sub.add_parser("get", help="Get a memory by ID")
+    get_p.add_argument("memory_id")
+    get_p.add_argument("--json", action="store_true")
+    add_scope_arguments(get_p)
+    get_p.set_defaults(func=_cmd_get)
+
+    search_p = sub.add_parser("search", help="Search memories")
+    search_p.add_argument("query")
+    search_p.add_argument("--top-k", type=int, default=10)
+    search_p.add_argument("--threshold", type=float, default=0.1)
+    search_p.add_argument("--json", action="store_true")
+    add_scope_arguments(search_p)
+    search_p.set_defaults(func=_cmd_search)
+
+    recall_p = sub.add_parser("recall", help="Print formatted recall for prompts")
+    recall_p.add_argument("query")
+    recall_p.add_argument("--top-k", type=int, default=5)
+    recall_p.add_argument("--threshold", type=float, default=0.1)
+    add_scope_arguments(recall_p)
+    recall_p.set_defaults(func=_cmd_recall)
+
+    update_p = sub.add_parser("update", help="Update a memory")
+    update_p.add_argument("memory_id")
+    update_p.add_argument("--content")
+    update_p.add_argument("--type")
+    update_p.add_argument("--json", action="store_true")
+    add_scope_arguments(update_p)
+    update_p.set_defaults(func=_cmd_update)
+
+    delete_p = sub.add_parser("delete", help="Delete a memory")
+    delete_p.add_argument("memory_id")
+    add_scope_arguments(delete_p)
+    delete_p.set_defaults(func=_cmd_delete)
+
+    bulk_p = sub.add_parser("delete-bulk", help="Bulk delete by scope filters")
+    bulk_p.add_argument("--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())

exemplar_cli-0.1.0/exemplar_cli/skills.py

@@ -0,0 +1,201 @@
+"""CLI: exemplar skills — manage org skill registry from the terminal."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from exemplar_core import skills_from_env
+from exemplar_core.skills.skill_md import parse_skill_md, skill_md_template
+
+
+def _default_dest(global_flag: bool) -> Path:
+    if global_flag:
+        return Path.home() / ".cursor" / "skills"
+    return Path(".cursor") / "skills"
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    skills = skills_from_env()
+    items = skills.list(tag=args.tag, limit=args.limit)
+    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.skill_id}{suffix}")
+    return 0
+
+
+def _cmd_get(args: argparse.Namespace) -> int:
+    record = skills_from_env().get(args.name)
+    if args.json:
+        print(json.dumps(record.__dict__, indent=2))
+        return 0
+    print(record.instructions)
+    return 0
+
+
+def _cmd_search(args: argparse.Namespace) -> int:
+    results = skills_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.description}")
+    return 0
+
+
+def _cmd_pull(args: argparse.Namespace) -> int:
+    client = skills_from_env()
+    dest_root = Path(args.dest) if args.dest else _default_dest(args.global_dest)
+
+    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}")
+        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'}")
+    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 _cmd_push(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if path.is_dir():
+        skill_file = path / "SKILL.md"
+    else:
+        skill_file = 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()
+    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 "",
+    }
+    try:
+        existing = skills.get(name)
+        record = skills.update(
+            existing.skill_id,
+            instructions=body["instructions"],
+            description=body["description"],
+        )
+        print(f"Updated {record.name} ({record.skill_id})")
+    except ValueError:
+        record = skills.create(
+            name=name,
+            instructions=body["instructions"],
+            description=body.get("description"),
+        )
+        print(f"Created {record.name} ({record.skill_id})")
+    return 0
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    dest_root = Path(args.dest) if args.dest else _default_dest(args.global_dest)
+    dest_dir = dest_root / args.name
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    skill_path = dest_dir / "SKILL.md"
+    if skill_path.exists() and not args.force:
+        print(f"already exists: {skill_path}", file=sys.stderr)
+        return 1
+    skill_path.write_text(
+        skill_md_template(
+            name=args.name,
+            description=args.description or "",
+            instructions=args.instructions or f"# {args.name}\n",
+        ),
+        encoding="utf-8",
+    )
+    print(f"Created {skill_path}")
+    return 0
+
+
+def _cmd_export_zip(args: argparse.Namespace) -> int:
+    payload = skills_from_env().export_zip(args.name)
+    out = Path(args.output) if args.output else Path(f"{args.name}.zip")
+    out.write_bytes(payload)
+    print(f"Wrote {out}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="exemplar skills")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    list_p = sub.add_parser("list", help="List org skills")
+    list_p.add_argument("--tag")
+    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 skill instructions")
+    get_p.add_argument("name")
+    get_p.add_argument("--json", action="store_true")
+    get_p.set_defaults(func=_cmd_get)
+
+    search_p = sub.add_parser("search", help="Search skills")
+    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)
+
+    pull_p = sub.add_parser("pull", help="Export skill(s) to local SKILL.md")
+    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.add_argument("path")
+    push_p.set_defaults(func=_cmd_push)
+
+    init_p = sub.add_parser("init", help="Scaffold local skill directory")
+    init_p.add_argument("name")
+    init_p.add_argument("--description", default="")
+    init_p.add_argument("--instructions", default="")
+    init_p.add_argument("--dest")
+    init_p.add_argument("--global", dest="global_dest", action="store_true")
+    init_p.add_argument("--force", action="store_true")
+    init_p.set_defaults(func=_cmd_init)
+
+    zip_p = sub.add_parser("export-zip", help="Download skill zip bundle")
+    zip_p.add_argument("name")
+    zip_p.add_argument("-o", "--output")
+    zip_p.set_defaults(func=_cmd_export_zip)
+
+    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.0/pyproject.toml

@@ -0,0 +1,26 @@
+[tool.poetry]
+name = "exemplar-cli"
+version = "0.1.0"
+description = "Exemplar terminal CLI for skills and memory"
+authors = ["Exemplar Dev LLC"]
+license = "LicenseRef-Proprietary"
+readme = "README.md"
+packages = [{ include = "exemplar_cli" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.14"
+exemplar-core = ">=0.1.0,<0.2"
+
+[tool.poetry.scripts]
+exemplar = "exemplar_cli.main:main"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]