ermes-cli 1.1.0__tar.gz → 1.2.0__tar.gz

{ermes_cli-1.1.0 → ermes_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ermes-cli
-Version: 1.1.0
+Version: 1.2.0
 Summary: CLI-first access to Ermes marketing automation with Auth0 multi-project auth.
 Project-URL: Homepage, https://ermes.publinker.com
 Project-URL: Repository, https://github.com/Martech-DM/ermes
@@ -31,8 +31,9 @@ Description-Content-Type: text/markdown
 
 This package gives Ermes operators a CLI surface for explicit-project API reads and guarded writes.
 
-Version 1.1.0. It removed the `ermes-mcp` compatibility server that 1.0.0 shipped (DEV-2326); a
-machine that registered it must drop that registration (e.g. `claude mcp remove ermes`).
+Version 1.2.0. It adds `ermes skill install` (DEV-2329). 1.1.0 removed the `ermes-mcp`
+compatibility server that 1.0.0 shipped (DEV-2326); a machine that registered it must drop that
+registration (e.g. `claude mcp remove ermes`).
 
 ## Install the CLI
 
@@ -53,6 +54,16 @@ Releases are cut by pushing a tag `ermes-cli-vX.Y.Z` equal to `cli/pyproject.tom
 (`.github/workflows/publish-cli.yml` runs the tests, builds the wheel, publishes to PyPI and attaches
 it to a GitHub Release). `install-cli.sh` is idempotent and safe to re-run for upgrades.
 
+## Teach your AI assistant
+
+```bash
+ermes skill install     # writes ~/.claude/skills/ermes/SKILL.md (Claude Code) and ~/.agents/skills/ermes/SKILL.md (Codex)
+ermes skill path        # prints the packaged SKILL.md, for any other assistant
+```
+
+The skill ships inside the package, so it matches the installed version. Re-run `ermes skill
+install` after `ermes update`, then restart the assistant.
+
 ## Update the CLI
 
 **Automatic prompt.** In an interactive terminal, the CLI checks PyPI for a newer `ermes-cli` at
@@ -259,6 +270,7 @@ is legible.
 | `subscriptions`, `tags`, `providers`, `ingest`, `export`, `config` | … |
 | `login`, `logout`, `whoami`, `use`, `projects` | Auth0 device-flow auth + multi-project context |
 | `metrics` | Campaign metrics, email or push (mirrors UI Metrics view) |
+| `skill install / path` | Install the packaged agent skill for Claude Code / Codex |
 | `write allow / deny / status` | Control the write-mode guard (mutations blocked by default) |
 
 Full surface: `ermes --help`.

{ermes_cli-1.1.0 → ermes_cli-1.2.0}/README.md

@@ -2,8 +2,9 @@
 
 This package gives Ermes operators a CLI surface for explicit-project API reads and guarded writes.
 
-Version 1.1.0. It removed the `ermes-mcp` compatibility server that 1.0.0 shipped (DEV-2326); a
-machine that registered it must drop that registration (e.g. `claude mcp remove ermes`).
+Version 1.2.0. It adds `ermes skill install` (DEV-2329). 1.1.0 removed the `ermes-mcp`
+compatibility server that 1.0.0 shipped (DEV-2326); a machine that registered it must drop that
+registration (e.g. `claude mcp remove ermes`).
 
 ## Install the CLI
 
@@ -24,6 +25,16 @@ Releases are cut by pushing a tag `ermes-cli-vX.Y.Z` equal to `cli/pyproject.tom
 (`.github/workflows/publish-cli.yml` runs the tests, builds the wheel, publishes to PyPI and attaches
 it to a GitHub Release). `install-cli.sh` is idempotent and safe to re-run for upgrades.
 
+## Teach your AI assistant
+
+```bash
+ermes skill install     # writes ~/.claude/skills/ermes/SKILL.md (Claude Code) and ~/.agents/skills/ermes/SKILL.md (Codex)
+ermes skill path        # prints the packaged SKILL.md, for any other assistant
+```
+
+The skill ships inside the package, so it matches the installed version. Re-run `ermes skill
+install` after `ermes update`, then restart the assistant.
+
 ## Update the CLI
 
 **Automatic prompt.** In an interactive terminal, the CLI checks PyPI for a newer `ermes-cli` at
@@ -230,6 +241,7 @@ is legible.
 | `subscriptions`, `tags`, `providers`, `ingest`, `export`, `config` | … |
 | `login`, `logout`, `whoami`, `use`, `projects` | Auth0 device-flow auth + multi-project context |
 | `metrics` | Campaign metrics, email or push (mirrors UI Metrics view) |
+| `skill install / path` | Install the packaged agent skill for Claude Code / Codex |
 | `write allow / deny / status` | Control the write-mode guard (mutations blocked by default) |
 
 Full surface: `ermes --help`.

ermes_cli-1.2.0/ermes_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.2.0"

ermes_cli-1.2.0/ermes_cli/commands/skill.py

@@ -0,0 +1,40 @@
+"""`ermes skill` — install the agent skill that teaches AI assistants the CLI.
+
+The skill is a plain SKILL.md packaged with the CLI, so it always matches the
+installed version. `install` copies it to the user-level skill folders that
+Claude Code and Codex read; `path` prints it for any other assistant.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+import typer
+
+skill_app = typer.Typer(help="Install the Ermes skill for Claude Code and Codex.", no_args_is_help=True)
+
+SKILL_NAME = "ermes"
+# User-level skill folders: Claude Code reads ~/.claude/skills, Codex reads
+# ~/.agents/skills. Both take <name>/SKILL.md.
+TARGETS = (Path(".claude/skills"), Path(".agents/skills"))
+
+
+def packaged_skill() -> Path:
+    return Path(str(resources.files("ermes_cli") / "skill" / "SKILL.md"))
+
+
+@skill_app.command("install", help="Copy the skill into ~/.claude/skills and ~/.agents/skills.")
+def install_cmd() -> None:
+    text = packaged_skill().read_text(encoding="utf-8")
+    for target in TARGETS:
+        dest = Path.home() / target / SKILL_NAME / "SKILL.md"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(text, encoding="utf-8")
+        typer.echo(f"installed {dest}")
+    typer.echo("Restart Claude Code / Codex to pick it up.")
+
+
+@skill_app.command("path", help="Print the packaged SKILL.md path (for other assistants).")
+def path_cmd() -> None:
+    typer.echo(packaged_skill())

{ermes_cli-1.1.0 → ermes_cli-1.2.0}/ermes_cli/main.py

@@ -219,6 +219,7 @@ from ermes_cli.commands.auth_cmds import login as _login, logout as _logout
 from ermes_cli.commands.projects import projects_app, use as _use
 from ermes_cli.commands.write_cmds import write_app
 from ermes_cli.commands.metrics import metrics_app
+from ermes_cli.commands.skill import skill_app
 
 app.add_typer(campaigns_app, name="campaigns")
 app.add_typer(templates_app, name="templates")
@@ -236,6 +237,7 @@ app.add_typer(export_app, name="export")
 app.add_typer(projects_app, name="projects")
 app.add_typer(write_app, name="write")
 app.add_typer(metrics_app, name="metrics")
+app.add_typer(skill_app, name="skill")
 app.command(name="login", help="Auth0 device login + auto-discover projects")(_login)
 app.command(name="logout", help="Forget Auth0 tokens + cached projects")(_logout)
 app.command(name="use", help="Switch active project (by name or id)")(_use)

ermes_cli-1.2.0/ermes_cli/skill/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ermes
+description: Read and manage Ermes marketing-automation data (campaigns, journeys, lists, templates, users, events, metrics, subscriptions) with the `ermes` CLI. Use when the user asks about their Ermes projects, campaigns, email metrics, contacts or lists, or mentions ermes.
+---
+
+# Ermes CLI
+
+The `ermes` command talks to the Ermes API for one project at a time. It only
+sees the projects the logged-in user has access to.
+
+## Before anything
+
+1. `ermes whoami` shows the selected project (it does not prove the login is
+   still valid). If there is no login, ask the user to run `ermes login`
+   themselves (it opens a browser to confirm a code). Never run `ermes login`
+   for them, and never print API keys or the contents of `~/.ermes`.
+2. `ermes projects list` to see the projects. Name the project on every
+   command with `ERMES_PROJECT=<name-or-id>` in front of it. Do not run
+   `ermes use` to switch projects: it changes the user's shared default.
+
+```bash
+ERMES_PROJECT=<project> ermes --json campaigns list --limit 5
+```
+
+## Find the right command
+
+Every group and command has `--help`; read it instead of guessing flags.
+
+```bash
+ermes --help
+ermes campaigns --help
+ermes metrics --help
+```
+
+`--json` is a root option: `ermes --json campaigns list`, not
+`ermes campaigns list --json`. Bound list reads with `--limit`.
+
+## Common reads
+
+```bash
+ERMES_PROJECT=<project> ermes --json campaigns get <id>
+ERMES_PROJECT=<project> ermes --json journeys list --limit 20
+ERMES_PROJECT=<project> ermes --json users get <external-id>
+ERMES_PROJECT=<project> ermes --json users events <external-id> --limit 20
+ERMES_PROJECT=<project> ermes --json metrics --help
+```
+
+User commands take the user's `external_id`, not an email address.
+
+## Changes (writes)
+
+Commands that create, change or delete data are blocked by default. Before a write:
+
+1. Read the current value first, then tell the user exactly what will change
+   and get a clear yes for that exact command.
+2. Run that one command with `ERMES_ALLOW_WRITES=1` and an explicit project:
+   `ERMES_PROJECT=<project> ERMES_ALLOW_WRITES=1 ermes --json campaigns update <id> ...`
+3. Never `export ERMES_ALLOW_WRITES` and never run `ermes write allow`;
+   nothing should stay unlocked afterwards.
+4. Read the value again and show the user the result. If a write times out,
+   read before retrying; it may have gone through.
+
+## Errors
+
+- `401` / no login: the user runs `ermes login`.
+- `403` or a missing project: the user has no access to it, or runs
+  `ermes projects refresh` after being added. Do not retry on other projects.
+- A newer version is announced: tell the user to run `ermes update`, then
+  `ermes skill install` to refresh this skill.

{ermes_cli-1.1.0 → ermes_cli-1.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "ermes-cli"
 # Keep in lockstep with ermes_cli/__init__.py::__version__ — tests/test_version.py fails if they drift.
-version = "1.1.0"
+version = "1.2.0"
 description = "CLI-first access to Ermes marketing automation with Auth0 multi-project auth."
 readme = "README.md"
 requires-python = ">=3.10"

ermes_cli-1.2.0/tests/test_skill_command.py

@@ -0,0 +1,20 @@
+"""Tests for `ermes skill install|path`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def test_install_writes_the_packaged_skill_for_claude_and_codex(invoke, tmp_path, monkeypatch) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    result = invoke(["skill", "install"])
+    assert result.exit_code == 0, result.output
+    for root in (".claude/skills", ".agents/skills"):
+        skill = (tmp_path / root / "ermes" / "SKILL.md").read_text()
+        assert skill.startswith("---\nname: ermes\n")
+
+
+def test_path_prints_an_existing_skill_file(invoke) -> None:
+    result = invoke(["skill", "path"])
+    assert result.exit_code == 0, result.output
+    assert Path(result.output.strip()).is_file()

ermes_cli-1.1.0/ermes_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.1.0"