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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: ermes-cli
-Version: 1.0.0
-Summary: CLI-first access to Ermes marketing automation, with Auth0 multi-project auth and an optional compatibility MCP.
+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
 Author: Martech-DM
@@ -14,7 +14,6 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Communications :: Email
 Requires-Python: >=3.10
-Requires-Dist: fastmcp>=2.0
 Requires-Dist: httpx>=0.28
 Requires-Dist: keyring>=24.0
 Requires-Dist: pyyaml>=6.0
@@ -28,13 +27,13 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: responses>=0.25; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# Ermes CLI and optional compatibility MCP
+# Ermes CLI
 
-This package gives Ermes operators a CLI-first surface for explicit-project API reads and guarded
-writes. It also retains a 10-tool read-only MCP for temporary compatibility, but normal agent
-sessions leave that server unregistered.
+This package gives Ermes operators a CLI surface for explicit-project API reads and guarded writes.
 
-Version 1.0.0 (DEV-2261). Verified 2026-10-20.
+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
 
@@ -55,22 +54,54 @@ 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.
 
-If a temporary rollback needs fixed typed schemas, register the compatibility MCP only for one
-explicit project:
+## Teach your AI assistant
 
 ```bash
-./cli/scripts/install-mcp.sh --project=<project-name-or-id>
+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
 ```
 
-Remove it after the rollback window. Removal preserves Auth0 tokens, project keys, and every file
-under `~/.ermes`:
+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
+most once every 24 hours (2-second timeout, cached in `~/.ermes/update-check.json`; failed checks
+are cached too, so an offline laptop is not slowed down). When one exists it asks before running
+your command:
+
+```
+ermes-cli 1.2.0 is available (you have 1.1.0). Update now? [Y]es / [n]ot now / [s]kip this version
+```
+
+- **Yes** (Enter): runs `pipx upgrade ermes-cli`, checks the new version in a fresh process, then
+  re-runs your command on it.
+- **Not now**: runs your command; asks again on the next run.
+- **Skip this version**: never asks about that version again; a newer release asks once more.
+
+A failed upgrade or Ctrl-C at the prompt prints one line and runs your command on the current
+version. The check never runs with `--json`, when `CI` is set, when stdin/stdout/stderr is not a
+TTY, before `ermes version` / `ermes update`, or with `ERMES_NO_UPDATE_CHECK=1`.
+
+**Manual.**
 
 ```bash
-./cli/scripts/install-mcp.sh --uninstall
+ermes update            # check, then ask before upgrading
+ermes update --check    # report only, never install
+ermes update --yes      # upgrade without asking
+ermes --json update [--yes]   # --json installs only with --yes
 ```
 
-Never run `ermes logout` as part of registration removal; logout deletes the Keychain session and
-`projects.yml`.
+**Status values** (`--json` `status`): `up_to_date`, `ahead`, `update_available`, `updated`,
+`lookup_failed` (exit 1), `update_failed` (exit 1). Installer output goes to stderr; stdout stays
+one JSON document.
+
+**Supported install.** Only the pipx install of the PyPI package (`install-cli.sh`, or
+`pipx install ermes-cli`) upgrades itself. `pipx upgrade` keeps the old venv if pip fails, so a
+failed upgrade never leaves you without a CLI. Editable checkouts (`git pull`), git or local-dir
+installs, non-pipx environments and an `ermes` that is not the venv pipx manages get the manual
+command instead of a prompt. Keychain tokens and `~/.ermes` are untouched.
 
 ## Auth — Auth0 device login (recommended)
 
@@ -161,8 +192,8 @@ State lives in `~/.ermes/state.yml` (chmod 600), separate from `projects.yml`
 so refreshing projects doesn't clobber the write window. `ermes whoami` shows
 the current write status.
 
-The optional compatibility MCP remains fixed at 10 read-only tools. Mutations stay CLI-only so every
-agent write must carry explicit project scope and one-process `ERMES_ALLOW_WRITES=1` authorization.
+Every agent write must carry explicit project scope and one-process `ERMES_ALLOW_WRITES=1`
+authorization.
 
 ## Metrics
 
@@ -239,39 +270,17 @@ 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`.
 
-### Optional compatibility MCP (`ermes-mcp`)
-
-The 10-tool read-only MCP remains for temporary Claude Code rollback only. Normal sessions use the
-CLI so they can pin project scope per command without loading fixed schemas at startup.
-`install-mcp.sh --project=<name-or-id>` writes an explicit `ERMES_PROJECT`; `ermes use` doesn't
-retarget that process.
-
-The CLI covers every compatibility read and is the preferred path:
-
-| Tool | Purpose |
-|---|---|
-| `whoami` | Current profile + base URL (no API call) |
-| `list_campaigns(limit?, status?)` | Campaigns; use CLI `campaigns list --status` when filtering |
-| `get_campaign(campaign_id)` | One campaign |
-| `list_templates(limit?)` | Templates |
-| `get_template(template_id)` | One template |
-| `list_lists(limit?)` | Contact lists |
-| `list_journeys(limit?)` | Automation journeys |
-| `list_users(limit?, email?)` | Users; use CLI `users list --q` for exact search |
-| `get_user(user_id)` | One user; the CLI argument is the external ID |
-| `get_user_events(user_id, limit?)` | Recent events; the CLI argument is the external ID |
-
 ## Where in the wider stack
 
 Ermes is a CLI-first integration in the
 [`Martech-DM/martech-mcps`](https://github.com/Martech-DM/martech-mcps) registry.
 That repo's `ermes/README.md` and `ermes/skills/ermes-ops/SKILL.md` are the
-cross-fleet setup and operating runbooks. The compatibility MCP stays
-unregistered during normal operation.
+cross-fleet setup and operating runbooks.
 
 ## CLI source history
 

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

@@ -1,10 +1,10 @@
-# Ermes CLI and optional compatibility MCP
+# Ermes CLI
 
-This package gives Ermes operators a CLI-first surface for explicit-project API reads and guarded
-writes. It also retains a 10-tool read-only MCP for temporary compatibility, but normal agent
-sessions leave that server unregistered.
+This package gives Ermes operators a CLI surface for explicit-project API reads and guarded writes.
 
-Version 1.0.0 (DEV-2261). Verified 2026-10-20.
+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
 
@@ -25,22 +25,54 @@ 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.
 
-If a temporary rollback needs fixed typed schemas, register the compatibility MCP only for one
-explicit project:
+## Teach your AI assistant
 
 ```bash
-./cli/scripts/install-mcp.sh --project=<project-name-or-id>
+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
 ```
 
-Remove it after the rollback window. Removal preserves Auth0 tokens, project keys, and every file
-under `~/.ermes`:
+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
+most once every 24 hours (2-second timeout, cached in `~/.ermes/update-check.json`; failed checks
+are cached too, so an offline laptop is not slowed down). When one exists it asks before running
+your command:
+
+```
+ermes-cli 1.2.0 is available (you have 1.1.0). Update now? [Y]es / [n]ot now / [s]kip this version
+```
+
+- **Yes** (Enter): runs `pipx upgrade ermes-cli`, checks the new version in a fresh process, then
+  re-runs your command on it.
+- **Not now**: runs your command; asks again on the next run.
+- **Skip this version**: never asks about that version again; a newer release asks once more.
+
+A failed upgrade or Ctrl-C at the prompt prints one line and runs your command on the current
+version. The check never runs with `--json`, when `CI` is set, when stdin/stdout/stderr is not a
+TTY, before `ermes version` / `ermes update`, or with `ERMES_NO_UPDATE_CHECK=1`.
+
+**Manual.**
 
 ```bash
-./cli/scripts/install-mcp.sh --uninstall
+ermes update            # check, then ask before upgrading
+ermes update --check    # report only, never install
+ermes update --yes      # upgrade without asking
+ermes --json update [--yes]   # --json installs only with --yes
 ```
 
-Never run `ermes logout` as part of registration removal; logout deletes the Keychain session and
-`projects.yml`.
+**Status values** (`--json` `status`): `up_to_date`, `ahead`, `update_available`, `updated`,
+`lookup_failed` (exit 1), `update_failed` (exit 1). Installer output goes to stderr; stdout stays
+one JSON document.
+
+**Supported install.** Only the pipx install of the PyPI package (`install-cli.sh`, or
+`pipx install ermes-cli`) upgrades itself. `pipx upgrade` keeps the old venv if pip fails, so a
+failed upgrade never leaves you without a CLI. Editable checkouts (`git pull`), git or local-dir
+installs, non-pipx environments and an `ermes` that is not the venv pipx manages get the manual
+command instead of a prompt. Keychain tokens and `~/.ermes` are untouched.
 
 ## Auth — Auth0 device login (recommended)
 
@@ -131,8 +163,8 @@ State lives in `~/.ermes/state.yml` (chmod 600), separate from `projects.yml`
 so refreshing projects doesn't clobber the write window. `ermes whoami` shows
 the current write status.
 
-The optional compatibility MCP remains fixed at 10 read-only tools. Mutations stay CLI-only so every
-agent write must carry explicit project scope and one-process `ERMES_ALLOW_WRITES=1` authorization.
+Every agent write must carry explicit project scope and one-process `ERMES_ALLOW_WRITES=1`
+authorization.
 
 ## Metrics
 
@@ -209,39 +241,17 @@ 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`.
 
-### Optional compatibility MCP (`ermes-mcp`)
-
-The 10-tool read-only MCP remains for temporary Claude Code rollback only. Normal sessions use the
-CLI so they can pin project scope per command without loading fixed schemas at startup.
-`install-mcp.sh --project=<name-or-id>` writes an explicit `ERMES_PROJECT`; `ermes use` doesn't
-retarget that process.
-
-The CLI covers every compatibility read and is the preferred path:
-
-| Tool | Purpose |
-|---|---|
-| `whoami` | Current profile + base URL (no API call) |
-| `list_campaigns(limit?, status?)` | Campaigns; use CLI `campaigns list --status` when filtering |
-| `get_campaign(campaign_id)` | One campaign |
-| `list_templates(limit?)` | Templates |
-| `get_template(template_id)` | One template |
-| `list_lists(limit?)` | Contact lists |
-| `list_journeys(limit?)` | Automation journeys |
-| `list_users(limit?, email?)` | Users; use CLI `users list --q` for exact search |
-| `get_user(user_id)` | One user; the CLI argument is the external ID |
-| `get_user_events(user_id, limit?)` | Recent events; the CLI argument is the external ID |
-
 ## Where in the wider stack
 
 Ermes is a CLI-first integration in the
 [`Martech-DM/martech-mcps`](https://github.com/Martech-DM/martech-mcps) registry.
 That repo's `ermes/README.md` and `ermes/skills/ermes-ops/SKILL.md` are the
-cross-fleet setup and operating runbooks. The compatibility MCP stays
-unregistered during normal operation.
+cross-fleet setup and operating runbooks.
 
 ## CLI source history
 

ermes_cli-1.2.0/ermes_cli/__init__.py

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

{ermes_cli-1.0.0 → ermes_cli-1.2.0}/ermes_cli/commands/auth_cmds.py

@@ -80,7 +80,7 @@ def _hostname() -> str:
 def ensure_project_key(project_id: int) -> str:
     """Return the cached CLI key for `project_id`, minting it on first use.
 
-    Raises `ConfigError` (never SystemExit — the MCP server calls this too)
+    Raises `ConfigError` (never SystemExit)
     when there is no Auth0 session or the server refuses.
     """
     payload = load_projects_file()

{ermes_cli-1.0.0 → ermes_cli-1.2.0}/ermes_cli/commands/projects.py

@@ -246,7 +246,7 @@ def use(
         ..., help="Project name or numeric id (from `ermes projects list`)"
     ),
 ) -> None:
-    """Switch the active project. Affects every subsequent CLI + MCP call."""
+    """Switch the active project. Affects every subsequent CLI call."""
     projects = get_projects()
     if not projects:
         console.print("[yellow]No cached projects.[/yellow] Run `ermes login` first.")

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.0.0 → ermes_cli-1.2.0}/ermes_cli/config.py

@@ -304,7 +304,7 @@ def get_auth0_email() -> str | None:
 
 
 # ---------------------------------------------------------------------------
-# Profile resolution — what the CLI / MCP actually consume at runtime
+# Profile resolution — what the CLI actually consumes at runtime
 # ---------------------------------------------------------------------------
 
 

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

@@ -32,11 +32,15 @@ atexit.register(_close_client)
 
 @app.callback()
 def main(
+    ctx: typer.Context,
     profile: Optional[str] = typer.Option(None, "--profile", "-p", help="Profile name"),
     use_json: bool = typer.Option(False, "--json", help="Output as JSON"),
 ):
     state.profile_name = profile
     state.use_json = use_json
+    from ermes_cli.update import maybe_prompt
+
+    maybe_prompt(use_json, ctx.invoked_subcommand)
 
 
 def get_client() -> ErmesClient:
@@ -61,6 +65,50 @@ def version():
         typer.echo(f"ermes-cli {__version__}")
 
 
+@app.command()
+def update(
+    check: bool = typer.Option(False, "--check", help="Only report whether a newer version exists."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Upgrade without asking."),
+):
+    """Check PyPI for a newer ermes-cli and upgrade the pipx install. Disable the daily prompt with ERMES_NO_UPDATE_CHECK=1."""
+    import json
+    import time
+
+    from ermes_cli import update as upd
+
+    def done(status: str, code: int = 0, **extra) -> None:
+        if state.use_json:
+            print(json.dumps({"status": status, "installed": __version__, **extra}))
+        raise typer.Exit(code=code)
+
+    try:
+        latest = upd.fetch_latest()
+    except upd.UpdateError as e:
+        typer.echo(f"Update check failed: {e}", err=True)
+        done("lookup_failed", 1, error=str(e))
+    upd.write_cache(checked_at=time.time(), latest=latest, error=None)
+
+    if not upd.is_newer(latest, __version__):
+        status = "ahead" if upd.is_newer(__version__, latest) else "up_to_date"
+        if not state.use_json:
+            typer.echo(f"ermes-cli {__version__} is {'newer than PyPI ' + latest if status == 'ahead' else 'up to date'}.")
+        done(status, latest=latest)
+    if check or (state.use_json and not yes):
+        if not state.use_json:
+            typer.echo(f"ermes-cli {latest} is available (you have {__version__}). Run `ermes update` to install.")
+        done("update_available", latest=latest)
+    if not yes and not typer.confirm(f"Upgrade ermes-cli {__version__} -> {latest}?", default=True, err=True):
+        done("update_available", latest=latest)
+    try:
+        installed = upd.upgrade(upd.detect_install(), latest)
+    except upd.UpdateError as e:
+        typer.echo(f"Update failed: {e}", err=True)
+        done("update_failed", 1, latest=latest, error=str(e))
+    if not state.use_json:
+        typer.echo(f"Updated ermes-cli to {installed}.")
+    done("updated", latest=latest)
+
+
 @app.command()
 def whoami(
     check: bool = typer.Option(
@@ -171,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")
@@ -188,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.