codeer-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{codeer_cli-0.1.0 → codeer_cli-0.1.2}/.gitignore

@@ -22,6 +22,7 @@ venv/
 env/
 .env
 .env.*
+*.env
 !.env.example
 !.env.sample
 session.env
@@ -34,3 +35,4 @@ Thumbs.db
 
 # Local assistant/tool settings
 .claude/settings.local.json
+.codeer/

{codeer_cli-0.1.0 → codeer_cli-0.1.2}/API_REFERENCE.md

@@ -66,6 +66,38 @@ Base path: `/organizations/{org_id}/workspaces/{ws_id}/knowledge_bases`
 Attach KB files to an agent by listing their node IDs in the agent's
 `unified_tools[].knowledge_node_ids`.
 
+### Context Object FAQ
+
+Base path: `/external/context-object-faqs`
+
+| Method & path | Purpose |
+| --- | --- |
+| `GET /context-object-faqs` | List FAQ entries, optionally filtered by `context_object_id` |
+| `GET /context-object-faqs/{faq_id}` | Read one FAQ entry |
+| `POST /context-object-faqs` | Create an FAQ entry |
+| `PATCH /context-object-faqs/{faq_id}` | Update the linked context object and/or question |
+| `DELETE /context-object-faqs/{faq_id}` | Delete an FAQ entry |
+
+Create body:
+
+```json
+{"context_object_id": 123, "question": "How do I reset billing?"}
+```
+
+Update body accepts either or both fields:
+
+```json
+{"context_object_id": 456, "question": "How do I update billing?"}
+```
+
+`context_object_id` is the KB file's `snapshot_object_id` from the KB node
+listing. The compact CLI output includes it:
+
+```bash
+codeer kb files --kb-id <kb-id>
+codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+```
+
 ## Stage 3 — Live Test on a specific version
 
 | Method & path | Purpose |

codeer_cli-0.1.2/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: codeer-cli
+Version: 0.1.2
+Summary: Command line tools for managing Codeer agents over the Codeer API.
+Project-URL: Homepage, https://www.codeer.ai
+Author: Codeer.AI
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# codeer-cli
+
+Standalone CLI for managing Codeer agents over the Codeer API.
+
+## User install
+
+Install the CLI from PyPI with `pipx`:
+
+```bash
+pipx install codeer-cli
+```
+
+Verify that the command is available:
+
+```bash
+codeer --help
+```
+
+If `pipx` is not installed:
+
+```bash
+python -m pip install --user pipx
+python -m pipx ensurepath
+```
+
+Then restart the terminal and run:
+
+```bash
+pipx install codeer-cli
+```
+
+As a fallback, you can install into your user Python environment:
+
+```bash
+python -m pip install --user codeer-cli
+```
+
+## Credentials
+
+The CLI expects credentials to be configured outside any skill workspace. Add a
+named profile, select it, then verify the setup:
+
+```bash
+codeer profile add work
+codeer profile use work
+codeer check
+```
+
+`codeer profile add` prompts for the API key without echoing it. The local
+project stores only the selected profile name in `.codeer/profile`; API keys
+remain in the user-level config file.
+
+For a one-off shell session, you can also export an API key directly:
+
+```bash
+export CODEER_API_KEY=<admin-workspace-api-key>
+codeer check
+```
+
+`CODEER_API_BASE` defaults to `https://api.codeer.ai`. Override it only for
+local, beta, or preview environments:
+
+```bash
+export CODEER_API_BASE=http://localhost:8000
+```
+
+The CLI intentionally does not read repo-root credential files or caller CWD
+`.env`, because those files are often visible to LLM workspace context. Do not
+paste the API key into agent chat or commit it to the repository.
+
+Workspace and organization scope are inferred from the workspace API-key
+virtual user's profile. `--workspace`, `--org`, `CODEER_WORKSPACE_ID`, and
+`CODEER_ORGANIZATION_ID` are not used by the CLI.
+
+Agent scope is optional and can be set as a non-secret environment variable:
+
+```bash
+CODEER_AGENT_ID=<agent-id>
+```
+
+## Development install
+
+Use an editable install while the CLI is changing quickly:
+
+```bash
+cd /path/to/codeer-skills/codeer-cli
+uv tool install --editable .
+```
+
+Reinstall only when dependencies, entry points, or package metadata change:
+
+```bash
+uv tool install --reinstall --editable /path/to/codeer-skills/codeer-cli
+```
+
+Validate setup before API work:
+
+```bash
+codeer check
+```
+
+## Upgrade and uninstall
+
+Upgrade the CLI:
+
+```bash
+pipx upgrade codeer-cli
+codeer check
+```
+
+Remove the CLI:
+
+```bash
+pipx uninstall codeer-cli
+```
+
+## Output policy for coding agents
+
+The CLI is optimized for Codex, Claude Code, Claude Cowork, and similar coding
+agents that keep command output in their LLM context. Default stdout is a
+compact lifecycle summary, not the full server payload.
+
+Use this pattern during agent lifecycle work:
+
+```bash
+codeer agent list
+codeer history list --agent <agent-id> --limit 50
+codeer eval run --agent <agent-id> --evaluators <evaluator-id> --out .codeer/eval_run.json
+```
+
+Flags:
+
+- `--full` prints bounded extra detail for human inspection. It is still
+  intended to be safe for LLM context.
+- `--out <path>` writes complete diagnostic artifacts to a local file. Use it
+  for raw eval results, full conversation turns, full rubric matrices, and
+  other data that can grow with cases, versions, or turns.
+
+Avoid piping large raw JSON directly into agent chat. Prefer `--out`, then ask
+the coding agent to inspect targeted summaries, IDs, failing cases, or selected
+snippets from the saved file.
+
+## Website crawler KBs
+
+Website-backed KB folders can be created and updated with `codeer kb crawl-*`.
+Always preview crawler mutations with `--dry-run` first:
+
+```bash
+codeer kb crawl-create \
+    --url https://example.com/docs \
+    --folder-name "Product Docs" \
+    --include-path "/docs*" \
+    --exclude-path "/docs/private*" \
+    --limit 250 \
+    --max-depth 3 \
+    --only-main-content \
+    --dry-run
+```
+
+`--include-path` and `--exclude-path` are repeatable clean path patterns. Quote
+paths containing `*` so the shell passes the wildcard to the CLI. Advanced
+settings can still be passed through `--config-json`; explicit crawler flags
+override matching JSON keys.
+
+## Context Object FAQ
+
+Use Context Object FAQ entries to route high-value questions to a canonical KB
+file when semantic retrieval misses the right source. The FAQ target is a KB
+file's `snapshot_object_id`, shown by `codeer kb files`.
+
+```bash
+codeer kb files --kb-id <kb-id>
+codeer kb faq-list --context-object-id <snapshot-object-id>
+codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+```
+
+After reviewing the dry-run output, rerun the create/update/delete command
+without `--dry-run` to apply it.

codeer_cli-0.1.2/README.md

@@ -0,0 +1,178 @@
+# codeer-cli
+
+Standalone CLI for managing Codeer agents over the Codeer API.
+
+## User install
+
+Install the CLI from PyPI with `pipx`:
+
+```bash
+pipx install codeer-cli
+```
+
+Verify that the command is available:
+
+```bash
+codeer --help
+```
+
+If `pipx` is not installed:
+
+```bash
+python -m pip install --user pipx
+python -m pipx ensurepath
+```
+
+Then restart the terminal and run:
+
+```bash
+pipx install codeer-cli
+```
+
+As a fallback, you can install into your user Python environment:
+
+```bash
+python -m pip install --user codeer-cli
+```
+
+## Credentials
+
+The CLI expects credentials to be configured outside any skill workspace. Add a
+named profile, select it, then verify the setup:
+
+```bash
+codeer profile add work
+codeer profile use work
+codeer check
+```
+
+`codeer profile add` prompts for the API key without echoing it. The local
+project stores only the selected profile name in `.codeer/profile`; API keys
+remain in the user-level config file.
+
+For a one-off shell session, you can also export an API key directly:
+
+```bash
+export CODEER_API_KEY=<admin-workspace-api-key>
+codeer check
+```
+
+`CODEER_API_BASE` defaults to `https://api.codeer.ai`. Override it only for
+local, beta, or preview environments:
+
+```bash
+export CODEER_API_BASE=http://localhost:8000
+```
+
+The CLI intentionally does not read repo-root credential files or caller CWD
+`.env`, because those files are often visible to LLM workspace context. Do not
+paste the API key into agent chat or commit it to the repository.
+
+Workspace and organization scope are inferred from the workspace API-key
+virtual user's profile. `--workspace`, `--org`, `CODEER_WORKSPACE_ID`, and
+`CODEER_ORGANIZATION_ID` are not used by the CLI.
+
+Agent scope is optional and can be set as a non-secret environment variable:
+
+```bash
+CODEER_AGENT_ID=<agent-id>
+```
+
+## Development install
+
+Use an editable install while the CLI is changing quickly:
+
+```bash
+cd /path/to/codeer-skills/codeer-cli
+uv tool install --editable .
+```
+
+Reinstall only when dependencies, entry points, or package metadata change:
+
+```bash
+uv tool install --reinstall --editable /path/to/codeer-skills/codeer-cli
+```
+
+Validate setup before API work:
+
+```bash
+codeer check
+```
+
+## Upgrade and uninstall
+
+Upgrade the CLI:
+
+```bash
+pipx upgrade codeer-cli
+codeer check
+```
+
+Remove the CLI:
+
+```bash
+pipx uninstall codeer-cli
+```
+
+## Output policy for coding agents
+
+The CLI is optimized for Codex, Claude Code, Claude Cowork, and similar coding
+agents that keep command output in their LLM context. Default stdout is a
+compact lifecycle summary, not the full server payload.
+
+Use this pattern during agent lifecycle work:
+
+```bash
+codeer agent list
+codeer history list --agent <agent-id> --limit 50
+codeer eval run --agent <agent-id> --evaluators <evaluator-id> --out .codeer/eval_run.json
+```
+
+Flags:
+
+- `--full` prints bounded extra detail for human inspection. It is still
+  intended to be safe for LLM context.
+- `--out <path>` writes complete diagnostic artifacts to a local file. Use it
+  for raw eval results, full conversation turns, full rubric matrices, and
+  other data that can grow with cases, versions, or turns.
+
+Avoid piping large raw JSON directly into agent chat. Prefer `--out`, then ask
+the coding agent to inspect targeted summaries, IDs, failing cases, or selected
+snippets from the saved file.
+
+## Website crawler KBs
+
+Website-backed KB folders can be created and updated with `codeer kb crawl-*`.
+Always preview crawler mutations with `--dry-run` first:
+
+```bash
+codeer kb crawl-create \
+    --url https://example.com/docs \
+    --folder-name "Product Docs" \
+    --include-path "/docs*" \
+    --exclude-path "/docs/private*" \
+    --limit 250 \
+    --max-depth 3 \
+    --only-main-content \
+    --dry-run
+```
+
+`--include-path` and `--exclude-path` are repeatable clean path patterns. Quote
+paths containing `*` so the shell passes the wildcard to the CLI. Advanced
+settings can still be passed through `--config-json`; explicit crawler flags
+override matching JSON keys.
+
+## Context Object FAQ
+
+Use Context Object FAQ entries to route high-value questions to a canonical KB
+file when semantic retrieval misses the right source. The FAQ target is a KB
+file's `snapshot_object_id`, shown by `codeer kb files`.
+
+```bash
+codeer kb files --kb-id <kb-id>
+codeer kb faq-list --context-object-id <snapshot-object-id>
+codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+```
+
+After reviewing the dry-run output, rerun the create/update/delete command
+without `--dry-run` to apply it.

{codeer_cli-0.1.0 → codeer_cli-0.1.2}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codeer-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "Command line tools for managing Codeer agents over the Codeer API."
 readme = "README.md"
 requires-python = ">=3.11"
 authors = [{ name = "Codeer.AI" }]
-license = { text = "Proprietary" }
+license = { text = "MIT" }
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Environment :: Console",
@@ -23,6 +23,11 @@ dependencies = [
   "httpx>=0.27",
 ]
 
+[dependency-groups]
+dev = [
+  "ruff>=0.11",
+]
+
 [project.urls]
 Homepage = "https://www.codeer.ai"
 

{codeer_cli-0.1.0 → codeer_cli-0.1.2}/src/codeer_cli/agents.py

@@ -153,3 +153,8 @@ def get_version(client: CodeerClient, agent_id: str, history_id: str) -> dict:
 def check_impact(client: CodeerClient, agent_id: str) -> dict:
     """List downstream agents that call this one. Call before publishing breaking changes."""
     return client.get(f"/external/agents/{agent_id}/impact")
+
+
+def publish_version(client: CodeerClient, agent_id: str, history_id: str) -> dict:
+    """Promote one AgentHistory version to the published runtime version."""
+    return client.post(f"/external/agents/{agent_id}/versions/{history_id}:publish", json={})

{codeer_cli-0.1.0 → codeer_cli-0.1.2}/src/codeer_cli/cli.py

@@ -2,7 +2,7 @@
 
     codeer check
     codeer agent list|get|apply|diff|versions
-    codeer kb list|files|upload
+    codeer kb list|files|upload|faq-list|faq-get|faq-create|faq-update|faq-delete
     codeer eval list|evaluators|evaluator-create|evaluator-update|run|export|reconcile|cases-apply|rubrics|rubrics-apply
     codeer history list|get|conversations|negative-feedback
 """
@@ -18,7 +18,31 @@ from .commands import check
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="codeer")
+    parser = argparse.ArgumentParser(
+        prog="codeer",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Codeer CLI — self-describing agent lifecycle tools.",
+        epilog="""\
+Safe workflow for coding agents:
+  codeer check --json
+  codeer agent list
+  codeer agent get <agent-id> --full
+  codeer kb list
+  codeer eval list --agent <agent-id>
+  codeer eval evaluators
+  codeer agent diff --agent <agent-id> --from-version <n> --to-version <n>
+  codeer eval reconcile --agent <agent-id> --manifest .codeer/eval_cases.json
+
+Preview mutations before applying:
+  codeer agent apply --payload agent.json --dry-run
+  codeer eval cases-apply --agent <agent-id> --cases eval_cases.json --dry-run
+  codeer eval rubrics-apply --rubrics rubrics.json --dry-run
+  codeer kb upload --dir kb --name "Product KB" --dry-run
+  codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+
+Use --out <path> for large raw artifacts; stdout defaults to compact summaries.
+""",
+    )
     sub = parser.add_subparsers(dest="group")
 
     check.register(sub)
@@ -67,6 +91,16 @@ def main(argv: list[str] | None = None) -> int:
             client = CodeerClient.from_env()
         except AuthError as e:
             if args.group == "check":
+                if getattr(args, "json", False):
+                    print(json.dumps({
+                        "status": "fail",
+                        "auth": {
+                            "ok": False,
+                            "error": str(e),
+                        },
+                        "next_step": "Configure CODEER_API_KEY or a codeer profile",
+                    }, ensure_ascii=False, indent=2))
+                    return 1
                 print(f"FAIL  Auth: {e}", file=sys.stderr)
                 print("      Configure CODEER_API_KEY or a codeer profile", file=sys.stderr)
                 return 1

{codeer_cli-0.1.0 → codeer_cli-0.1.2}/src/codeer_cli/client.py

@@ -85,8 +85,7 @@ class CodeerClient:
         if not api_key:
             raise AuthError(
                 0,
-                "Missing API key. Export CODEER_API_KEY or run `codeer profile add <name>` "
-                "and `codeer profile use <name>`.",
+                "Missing API key. Export CODEER_API_KEY or run `codeer profile add <name>`.",
             )
 
         overrides.pop("workspace_id", None)

codeer_cli-0.1.2/src/codeer_cli/commands/_util.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def log(*args, **kwargs):
+    print(*args, file=sys.stderr, **kwargs)
+
+
+def truncate(text: str, n: int = 60) -> str:
+    text = text.replace("\n", " ").strip()
+    return text[:n] + "..." if len(text) > n else text
+
+
+NOISY_KEYS = {
+    "avatar",
+    "brand",
+    "creator",
+    "default_organization_id",
+    "default_scopes",
+    "default_workspace_id",
+    "is_owner",
+    "members",
+    "my_permissions",
+    "owner",
+    "profile",
+    "source_creator",
+    "user_role",
+    "workspace_organization_map",
+}
+
+
+def strip_noisy_fields(value: Any) -> Any:
+    """Remove server/account metadata that is not useful for agent lifecycle work."""
+    if isinstance(value, list):
+        return [strip_noisy_fields(item) for item in value]
+    if not isinstance(value, dict):
+        return value
+
+    out = {}
+    for key, item in value.items():
+        if key in NOISY_KEYS:
+            continue
+        if key == "workspace" and isinstance(item, dict):
+            out[key] = {
+                k: item.get(k)
+                for k in ("id", "name", "organization_id")
+                if item.get(k) is not None
+            }
+            continue
+        out[key] = strip_noisy_fields(item)
+    return out
+
+
+def print_json(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2, default=str))
+
+
+def write_json(path: str | None, value: Any) -> None:
+    if not path:
+        return
+    Path(path).write_text(json.dumps(value, ensure_ascii=False, indent=2, default=str) + "\n")
+    log(f"wrote full detail to {path}")