letz-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{letz_cli-0.1.0 → letz_cli-0.2.0}/.gitignore

@@ -2,3 +2,4 @@ dist/
 __pycache__/
 *.egg-info/
 letz_work/
+.release-venv/

{letz_cli-0.1.0 → letz_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: letz-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Letz Brain CLI - pull campaigns from the Letz platform, draft email sequences locally with Claude, and push them back staged for review.
 Project-URL: Homepage, https://sam.weareletz.com
 Author: Letz
@@ -25,29 +25,28 @@ Generate email sequences **off-platform** (on flat-rate Claude compute), push th
 the [Letz](https://sam.weareletz.com) platform staged for review, and let the cloud
 **just click send**. Zero cloud AI cost.
 
-## Why
-
-Every time the cloud app composes a sequence it spends metered AI money. This CLI moves
-all of that generation onto your own Claude subscription. The platform only renders the
-finished drafts for review and sends them when a human clicks **Activate**.
-
-## Install
-
-Requires Python 3.10+. No other dependencies (pure standard library).
+## 60-second start
 
 ```bash
-pip install letz-cli
-# or, in a managed Python environment:
-pipx install letz-cli
+pip install letz-cli                                        # or: pipx install letz-cli
+export LETZ_API_URL="https://your-letz-instance.example.com"
+letz campaigns                                              # list your campaigns + ids
+letz prompt <CAMPAIGN_ID>                                   # print the playbook for Claude
 ```
 
-Then point it at your Letz platform:
+Paste the output of `letz prompt` into a [Claude Code](https://docs.claude.com/en/docs/claude-code/overview)
+session signed in with a **Claude Pro or Max subscription** (not a metered API key — the
+subscription is what makes generation free). Claude runs the whole loop below for you,
+writes every email, and stages the result **paused**. You review in the platform UI and
+click **Activate** when happy. Nothing ever sends on its own.
 
-```bash
-export LETZ_API_URL="https://your-letz-instance.example.com"
-```
+## Why
+
+Every time the cloud app composes a sequence it spends metered AI money. This CLI moves
+all of that generation onto your own Claude subscription. The platform only renders the
+finished drafts for review and sends them when a human clicks **Activate**.
 
-## Workflow
+## The loop, step by step
 
 ```bash
 # 1. Pull a campaign's config + leads. Writes letz_work/<id>.pull.json and a
@@ -56,15 +55,13 @@ letz pull <campaign_id>
 
 # 2. GENERATION happens HERE: fill the "emails" arrays in letz_work/<id>.ready.json.
 #    In an interactive Claude session, Claude writes the sequences directly into that
-#    file, following the campaign's style guide + brand persona. Run this step on a
-#    subscription-auth Claude session — not a metered API key — or the cost saving
-#    is lost.
+#    file, following the campaign's style guide + brand persona.
 
 # 3. Quality gate (pure Python, no AI). Fails on em dashes, spam phrases, forbidden
 #    names, over-length, etc.
 letz check <campaign_id>
 
-# 4. Push staged (PAUSED — nothing sends). Idempotent.
+# 4. Push staged (PAUSED — nothing sends). Idempotent; safe to re-run.
 letz push <campaign_id>
 
 # 5. Review the drafts in the platform UI (campaign detail → previews), then click
@@ -79,13 +76,18 @@ letz status <campaign_id>
 
 | Command | What it does | AI? |
 |---|---|---|
+| `campaigns` | list your campaigns with their ids | no |
+| `prompt [id]` | print the recommended prompt to paste into Claude Code | no |
 | `pull <id>` | fetch campaign + persona + leads → pull.json + ready.json scaffold | no |
 | `check <id>` | run the deterministic quality gauntlet on ready.json | no |
 | `push <id>` | import drafts, staged paused; re-runs the gauntlet first | no |
 | `push <id> --activate` | push **and** flip the campaign active (begins sending) | no |
 | `status <id>` | staged enrollments / previews / sends | no |
 
-Flags: `--api <url>` (or `$LETZ_API_URL`), `--work <dir>` (or `$LETZ_WORK`, default `./letz_work`).
+Flags: `--api <url>` (or `$LETZ_API_URL`), `--work <dir>` (or `$LETZ_WORK`, default
+`./letz_work`), `--version`. Global flags go before the command: `letz --api <url> status <id>`.
+
+Requires Python 3.10+. Zero dependencies (pure standard library).
 
 ## Safety
 

{letz_cli-0.1.0 → letz_cli-0.2.0}/README.md

@@ -4,29 +4,28 @@ Generate email sequences **off-platform** (on flat-rate Claude compute), push th
 the [Letz](https://sam.weareletz.com) platform staged for review, and let the cloud
 **just click send**. Zero cloud AI cost.
 
-## Why
-
-Every time the cloud app composes a sequence it spends metered AI money. This CLI moves
-all of that generation onto your own Claude subscription. The platform only renders the
-finished drafts for review and sends them when a human clicks **Activate**.
-
-## Install
-
-Requires Python 3.10+. No other dependencies (pure standard library).
+## 60-second start
 
 ```bash
-pip install letz-cli
-# or, in a managed Python environment:
-pipx install letz-cli
+pip install letz-cli                                        # or: pipx install letz-cli
+export LETZ_API_URL="https://your-letz-instance.example.com"
+letz campaigns                                              # list your campaigns + ids
+letz prompt <CAMPAIGN_ID>                                   # print the playbook for Claude
 ```
 
-Then point it at your Letz platform:
+Paste the output of `letz prompt` into a [Claude Code](https://docs.claude.com/en/docs/claude-code/overview)
+session signed in with a **Claude Pro or Max subscription** (not a metered API key — the
+subscription is what makes generation free). Claude runs the whole loop below for you,
+writes every email, and stages the result **paused**. You review in the platform UI and
+click **Activate** when happy. Nothing ever sends on its own.
 
-```bash
-export LETZ_API_URL="https://your-letz-instance.example.com"
-```
+## Why
+
+Every time the cloud app composes a sequence it spends metered AI money. This CLI moves
+all of that generation onto your own Claude subscription. The platform only renders the
+finished drafts for review and sends them when a human clicks **Activate**.
 
-## Workflow
+## The loop, step by step
 
 ```bash
 # 1. Pull a campaign's config + leads. Writes letz_work/<id>.pull.json and a
@@ -35,15 +34,13 @@ letz pull <campaign_id>
 
 # 2. GENERATION happens HERE: fill the "emails" arrays in letz_work/<id>.ready.json.
 #    In an interactive Claude session, Claude writes the sequences directly into that
-#    file, following the campaign's style guide + brand persona. Run this step on a
-#    subscription-auth Claude session — not a metered API key — or the cost saving
-#    is lost.
+#    file, following the campaign's style guide + brand persona.
 
 # 3. Quality gate (pure Python, no AI). Fails on em dashes, spam phrases, forbidden
 #    names, over-length, etc.
 letz check <campaign_id>
 
-# 4. Push staged (PAUSED — nothing sends). Idempotent.
+# 4. Push staged (PAUSED — nothing sends). Idempotent; safe to re-run.
 letz push <campaign_id>
 
 # 5. Review the drafts in the platform UI (campaign detail → previews), then click
@@ -58,13 +55,18 @@ letz status <campaign_id>
 
 | Command | What it does | AI? |
 |---|---|---|
+| `campaigns` | list your campaigns with their ids | no |
+| `prompt [id]` | print the recommended prompt to paste into Claude Code | no |
 | `pull <id>` | fetch campaign + persona + leads → pull.json + ready.json scaffold | no |
 | `check <id>` | run the deterministic quality gauntlet on ready.json | no |
 | `push <id>` | import drafts, staged paused; re-runs the gauntlet first | no |
 | `push <id> --activate` | push **and** flip the campaign active (begins sending) | no |
 | `status <id>` | staged enrollments / previews / sends | no |
 
-Flags: `--api <url>` (or `$LETZ_API_URL`), `--work <dir>` (or `$LETZ_WORK`, default `./letz_work`).
+Flags: `--api <url>` (or `$LETZ_API_URL`), `--work <dir>` (or `$LETZ_WORK`, default
+`./letz_work`), `--version`. Global flags go before the command: `letz --api <url> status <id>`.
+
+Requires Python 3.10+. Zero dependencies (pure standard library).
 
 ## Safety
 

{letz_cli-0.1.0 → letz_cli-0.2.0}/letz/__init__.py

@@ -2,4 +2,4 @@
 sequences locally with Claude, and push them back staged for review.
 Nothing sends until a human clicks Activate.
 """
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{letz_cli-0.1.0 → letz_cli-0.2.0}/letz/__main__.py

@@ -1,6 +1,7 @@
 """Letz Brain CLI entrypoint.
 
 Workflow:
+    letz campaigns                 # list your campaigns + ids
     letz pull <campaign_id>        # fetch campaign + persona + leads -> work/<id>.pull.json
                                    #   (also writes a work/<id>.ready.json scaffold to fill)
     # --- generation happens HERE (Claude fills work/<id>.ready.json) ---
@@ -21,14 +22,27 @@ import os
 import sys
 
 try:
+    from . import __version__
     from .api import LetzAPI, LetzAPIError
     from .gauntlet import audit_sequence
 except ImportError:  # allow running as a plain script: python cli/letz/__main__.py
     sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from letz import __version__
     from letz.api import LetzAPI, LetzAPIError
     from letz.gauntlet import audit_sequence
 
 
+CLAUDE_PROMPT = """You are operating the Letz Brain CLI (the `letz` command, installed via `pip install letz-cli`). Do this for campaign {cid}:
+
+1. Run: letz pull {cid}
+2. Open letz_work/{cid}.ready.json. For every lead, write the "emails" array following the campaign's own style_guide and strategy_brief shown in the pull file. Keep it plain and human, no em dashes, personalize with first name and company only, never invent facts, and use the brand persona sender name (never the operator's real name).
+3. Run: letz check {cid} and fix every hard issue until it reports 0.
+4. Run: letz push {cid} (this stages everything PAUSED, it never sends).
+5. Tell me to review the drafts in the platform UI and click Activate.
+
+Do all generation yourself in this session on my Claude subscription. Never call a metered API key. Never activate a campaign without my explicit go-ahead."""
+
+
 def _work_dir(args) -> str:
     d = args.work or os.environ.get("LETZ_WORK") or os.path.join(os.getcwd(), "letz_work")
     os.makedirs(d, exist_ok=True)
@@ -50,6 +64,25 @@ def _save(path, obj):
 
 
 # ---------------------------------------------------------------- commands ----
+def cmd_campaigns(args):
+    api = LetzAPI(args.api)
+    camps = api.campaigns()
+    if not camps:
+        print(f"No campaigns found at {args.api}")
+        return 0
+    width = max(len(c.get("name", "") or "") for c in camps)
+    print(f"{'ID':36}  {'STATUS':9}  NAME")
+    for c in sorted(camps, key=lambda c: (c.get("status") != "active", c.get("name") or "")):
+        print(f"{c.get('id',''):36}  {c.get('status','?'):9}  {(c.get('name') or ''):{width}}")
+    print(f"\n{len(camps)} campaign(s). Next: letz pull <ID>   (or: letz prompt <ID> for the full Claude playbook)")
+    return 0
+
+
+def cmd_prompt(args):
+    print(CLAUDE_PROMPT.format(cid=args.campaign_id or "<CAMPAIGN_ID>"))
+    return 0
+
+
 def cmd_pull(args):
     api = LetzAPI(args.api)
     camp = api.campaign(args.campaign_id)
@@ -205,10 +238,18 @@ def cmd_status(args):
 
 def main(argv=None):
     p = argparse.ArgumentParser(prog="letz", description="Letz Brain CLI — off-platform generation, persist, click send.")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
     p.add_argument("--api", default=os.environ.get("LETZ_API_URL", "http://localhost:8000"), help="platform base URL")
     p.add_argument("--work", default=None, help="work dir (default ./letz_work)")
     sub = p.add_subparsers(dest="cmd", required=True)
 
+    sp = sub.add_parser("campaigns", help="list your campaigns with their ids")
+    sp.set_defaults(func=cmd_campaigns)
+
+    sp = sub.add_parser("prompt", help="print the recommended prompt to paste into Claude Code")
+    sp.add_argument("campaign_id", nargs="?", default=None)
+    sp.set_defaults(func=cmd_prompt)
+
     sp = sub.add_parser("pull", help="fetch campaign + leads, write a ready.json scaffold")
     sp.add_argument("campaign_id")
     sp.add_argument("--limit", type=int, default=1000)

{letz_cli-0.1.0 → letz_cli-0.2.0}/letz/api.py

@@ -38,12 +38,21 @@ class LetzAPI:
             except Exception:
                 payload = {"detail": "unreadable error body"}
             raise LetzAPIError(e.code, payload)
+        except urllib.error.URLError as e:
+            raise LetzAPIError(0, {
+                "detail": f"Could not reach {self.base} ({e.reason}). "
+                          "Set LETZ_API_URL to your Letz platform URL, e.g. "
+                          'export LETZ_API_URL="https://your-letz-instance.example.com"'
+            })
 
     # ---- reads ----
+    def campaigns(self, limit: int = 200) -> list:
+        data = self._req("GET", f"/campaigns?limit={limit}")
+        return data.get("campaigns", [])
+
     def campaign(self, campaign_id: str) -> dict | None:
         """No single-campaign GET exists; fetch the list and filter."""
-        data = self._req("GET", "/campaigns?limit=200")
-        for c in data.get("campaigns", []):
+        for c in self.campaigns():
             if c.get("id") == campaign_id:
                 return c
         return None

{letz_cli-0.1.0 → letz_cli-0.2.0}/letz/gauntlet.py

@@ -1,15 +1,10 @@
 """Pure-Python quality gauntlet for the Letz Brain CLI.
 
-Parity port of the platform's DETERMINISTIC email checks so off-platform
-generation meets the same bar the in-app critic enforced — with ZERO AI.
+Mirrors the Letz platform's deterministic email checks so off-platform
+generation meets the same bar the in-app critic enforces — with ZERO AI.
+Hard rule included: NO em dashes.
 
-Sources mirrored:
-  - services/critic.py:_deterministic_penalties + BAD_PHRASES
-  - services/email_audit.py:audit_email_deterministic + BANNED_PHRASES
-Plus the operator's hard rule: NO em dashes.
-
-The LLM-rubric half of the critic is replaced by careful generation upstream;
-this module is the hard gate that runs locally before anything is pushed.
+This module is the hard gate that runs locally before anything is pushed.
 """
 from __future__ import annotations
 import re
@@ -17,7 +12,6 @@ import re
 EM_DASH = "—"   # —
 EN_DASH = "–"   # –
 
-# Union of services/critic.py BAD_PHRASES and services/email_audit.py BANNED_PHRASES.
 BANNED_PHRASES = sorted(set([
     "i hope this email finds you well", "i hope this finds you well",
     "i hope you're well", "hope you're doing well", "i wanted to reach out",