rhylthyme-cli-runner 0.2.2a0__tar.gz → 0.2.4a0__tar.gz

{rhylthyme_cli_runner-0.2.2a0/src/rhylthyme_cli_runner.egg-info → rhylthyme_cli_runner-0.2.4a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhylthyme-cli-runner
-Version: 0.2.2a0
+Version: 0.2.4a0
 Summary: CLI runner for Rhylthyme real-time program schedules
 Home-page: https://github.com/rhylthyme/rhylthyme-cli-runner
 Author: Rhylthyme Team
@@ -69,6 +69,107 @@ rhylthyme login
 rhylthyme generate "roast chicken, potatoes and green beans for 6" -e kitchen --by 19:00 --with "one oven"
 ```
 
+## A timeline in five commands: a birthday party
+
+Parents collect at 4:00. Working backwards from that: when does the cake go in
+the oven, when do the balloons go up, and do the pizzas and the cake ever want
+the oven at the same time?
+
+```bash
+pip install rhylthyme-cli-runner
+
+# 1. a program: the party, the kitchen and the setup crew, 13 steps
+curl -sO https://raw.githubusercontent.com/rhylthyme/rhylthyme-cli-runner/main/examples/recipe/birthday-party.json
+
+# 2. is it well formed?
+rhylthyme validate birthday-party.json --strict
+
+# 3. any clashes, and what time does everything start if we finish at 4?
+rhylthyme analyze birthday-party.json --finish-at 16:00
+```
+
+```
+**Makespan:** 3h 10m across 3 tracks, 13 steps.
+**Critical path:** Guests arrive → Party games → Pizza → Candles and cake → Piñata, until it breaks → Party bags and goodbyes
+**Binding constraints:** step dependencies only — no resource or in-flight limit gates the critical path.
+**Peak concurrency:** 2 steps at 10:00.
+**Resource conflicts:** none.
+
+**Tracks that finish early:** Kitchen (1h 10m early), Setup crew (50m early)
+
+Start Sat 12:50, finish Sat 16:00 (local time)
+  Sat 12:50  Bake the cake
+  Sat 13:00  Balloons and banner
+  Sat 13:25  Cake cools
+  Sat 13:30  Hang the piñata
+  Sat 13:50  Guests arrive
+  Sat 14:05  Frost and decorate
+  Sat 14:20  Party games
+  Sat 14:35  Pizzas in the oven
+  Sat 14:50  Fill party bags
+  Sat 14:50  Pizza
+  Sat 15:15  Candles and cake
+  Sat 15:30  Piñata, until it breaks
+  Sat 15:45  Party bags and goodbyes
+```
+
+```bash
+# 4. a live timeline for the fridge door (or a phone): timers, cues, and you end the piñata when it breaks
+rhylthyme publish birthday-party.json --open --image party-preview.png
+
+# 5. a picture for the group chat, on the wall clock (needs Node; nothing to install)
+npx -y github:rhylthyme/rhylthyme-timeline birthday-party.json -o birthday-party.png \
+  --style web --palette vivid --label-overflow outside --start-at "$(date +%F)T12:50:00"
+```
+
+![Eighth birthday party: the party, the kitchen and the setup crew on a wall-clock axis](https://raw.githubusercontent.com/rhylthyme/rhylthyme-cli-runner/main/examples/recipe/birthday-party.png)
+
+The pizzas go in 15 minutes after the games *start*, so they come out as the
+games end; the party bags get filled while everyone is eating. Try
+`--finish-at 17:30`, or turn the cake into a two-hour fruitcake (`"seconds": "2h"`
+on `bake`) and `analyze` reports the clash: `oven needs 2 but max is 1 from
+1:45:00 to 2:00:00 (bake, heat-pizza)`. `rhylthyme run birthday-party.json --time-scale 60` rehearses
+the whole afternoon in the terminal at a minute per second.
+
+## This repository and rhylthyme-mcp
+
+Two repositories do related things and are easy to confuse. This one is the
+**command a person types**. [rhylthyme-mcp](https://github.com/rhylthyme/rhylthyme-mcp)
+is the **server an AI assistant talks to**.
+
+| | [rhylthyme-mcp](https://github.com/rhylthyme/rhylthyme-mcp) | [rhylthyme-cli-runner](https://github.com/rhylthyme/rhylthyme-cli-runner) |
+|---|---|---|
+| What it is | The MCP **server**: the tools an AI assistant calls | A command-line **program**: the `rhylthyme` command |
+| Who uses it | Claude, ChatGPT, Cursor or any MCP client, on a person's behalf | A person at a terminal, a script, or CI |
+| Where it runs | Hosted at `mcp.rhylthyme.com`; nothing to install | On your machine: `pip install rhylthyme-cli-runner` |
+| Language | JavaScript (Node 20+) | Python 3.12+ |
+| Input | A program the assistant builds in conversation | A program file on disk (JSON or YAML) |
+| Validate a program | `validate_program` | `rhylthyme validate` (works offline) |
+| Import a recipe or protocol | `import_from_source` | `rhylthyme import` |
+| Timing, conflicts, deadlines | `analyze_schedule` | `rhylthyme analyze` (asks the server) |
+| Publish a live timeline | `visualize_schedule` | `rhylthyme publish` (asks the server) |
+| Run a schedule with timers | no: it hands back a link to the web timeline | `rhylthyme run`, an interactive terminal runner |
+| Recorded runs, calibration | reads runs saved to an account | records runs locally; `rhylthyme runs`, `rhylthyme calibrate` |
+| Catalog search, account library | yes | no |
+| Also in the repository | the `rhylthyme-mcp` PyPI package (a stdio bridge to the hosted server), the Claude plugin marketplace | the Claude skill's source, the prompt-evaluation harness and its results, `rhylthyme mcp-test` |
+
+How they fit together: this tool is one of the MCP server's clients.
+`rhylthyme analyze`, `publish`, `generate` and `mcp-test` are MCP calls to
+`mcp.rhylthyme.com`; `rhylthyme validate`, `run`, `runs` and `calibrate` never
+touch the network. Each has its own validator for the same program schema
+(Python here, JavaScript there), so a program is checked again when it is
+published.
+
+Use this repository if you have a program file and a terminal, want timers in
+the terminal, or keep run records. Use rhylthyme-mcp to connect Claude, ChatGPT
+or another assistant, or to read or self-host the server.
+
+Two names to keep apart: `rhylthyme-cli-runner` on PyPI is this tool (command
+`rhylthyme`); `rhylthyme-mcp` on PyPI is the server's stdio bridge (command
+`rhylthyme-mcp`). The program format itself is defined in
+[rhylthyme-spec](https://github.com/rhylthyme/rhylthyme-spec), with examples in
+[rhylthyme-examples](https://github.com/rhylthyme/rhylthyme-examples).
+
 ## Installation
 
 ### From Source
@@ -257,6 +358,16 @@ it for conflicts, and hand back a live timeline. It follows the layout of
 [K-Dense scientific skills](https://github.com/K-Dense-AI/claude-scientific-skills):
 a `SKILL.md` plus `references/`.
 
+The easiest install is the Claude Code plugin, which also connects the hosted
+MCP server:
+
+```
+/plugin marketplace add rhylthyme/rhylthyme-mcp
+/plugin install rhylthyme@rhylthyme
+```
+
+Or copy the skill by hand:
+
 ```bash
 # Claude Code, for one user
 mkdir -p ~/.claude/skills
@@ -421,15 +532,37 @@ and tracks that finish early. No sign-in; nothing is published.
 
 ### `rhylthyme publish`
 
-Publishes a program file as a live timeline and prints its URL. No sign-in.
+Publishes a program (a file, an http(s) URL, or `-` for standard input) as a
+live timeline and prints its URL. No sign-in.
 A published timeline is reachable by anyone who has the link.
 
 **Options:**
 - `-e, --env`: `generic`, `kitchen`, `lab`, `events`, `gym` (default: from `environmentType`)
 - `-q, --quiet`: print only the URL
 - `--json`: `url`, `shareId`, `imageUrl`, `makespanSeconds`, `warnings`
+- `--image PATH`: also save a PNG of the timeline
 - `--open`: open it in a browser
 
+### `rhylthyme import`
+
+Imports a recipe, protocol or slide deck as a program, validates it, and
+writes `<programId>.json`. Needs `rhylthyme-importers` (included in
+`pip install rhylthyme`).
+
+```bash
+rhylthyme import https://www.seriouseats.com/the-best-chili-recipe   # any of ~580 recipe sites
+rhylthyme import 52772 -i themealdb --publish                        # a TheMealDB id, straight to a live timeline
+rhylthyme import https://www.protocols.io/view/western-blot-...      # needs PROTOCOLS_IO_TOKEN
+rhylthyme import protocol.py -o protocol.json                        # an Opentrons file
+rhylthyme import "Neapolitan Pizza.cook" -i cooklang
+rhylthyme importers                                                  # what is installed
+rhylthyme search "pad thai" -i spoonacular                           # then import a hit's URL
+```
+
+**Options:** `-i IMPORTER` (default: chosen from the URL), `-o PATH`,
+`--stdout`, `--publish` (and `--open`), `--no-validate`. `-` reads pasted
+source from stdin (with `-i`).
+
 ### `rhylthyme plan`
 
 An older stagger heuristic. It reads the pre-0.2 program format and leaves

{rhylthyme_cli_runner-0.2.2a0 → rhylthyme_cli_runner-0.2.4a0}/README.md

@@ -9,6 +9,107 @@ rhylthyme login
 rhylthyme generate "roast chicken, potatoes and green beans for 6" -e kitchen --by 19:00 --with "one oven"
 ```
 
+## A timeline in five commands: a birthday party
+
+Parents collect at 4:00. Working backwards from that: when does the cake go in
+the oven, when do the balloons go up, and do the pizzas and the cake ever want
+the oven at the same time?
+
+```bash
+pip install rhylthyme-cli-runner
+
+# 1. a program: the party, the kitchen and the setup crew, 13 steps
+curl -sO https://raw.githubusercontent.com/rhylthyme/rhylthyme-cli-runner/main/examples/recipe/birthday-party.json
+
+# 2. is it well formed?
+rhylthyme validate birthday-party.json --strict
+
+# 3. any clashes, and what time does everything start if we finish at 4?
+rhylthyme analyze birthday-party.json --finish-at 16:00
+```
+
+```
+**Makespan:** 3h 10m across 3 tracks, 13 steps.
+**Critical path:** Guests arrive → Party games → Pizza → Candles and cake → Piñata, until it breaks → Party bags and goodbyes
+**Binding constraints:** step dependencies only — no resource or in-flight limit gates the critical path.
+**Peak concurrency:** 2 steps at 10:00.
+**Resource conflicts:** none.
+
+**Tracks that finish early:** Kitchen (1h 10m early), Setup crew (50m early)
+
+Start Sat 12:50, finish Sat 16:00 (local time)
+  Sat 12:50  Bake the cake
+  Sat 13:00  Balloons and banner
+  Sat 13:25  Cake cools
+  Sat 13:30  Hang the piñata
+  Sat 13:50  Guests arrive
+  Sat 14:05  Frost and decorate
+  Sat 14:20  Party games
+  Sat 14:35  Pizzas in the oven
+  Sat 14:50  Fill party bags
+  Sat 14:50  Pizza
+  Sat 15:15  Candles and cake
+  Sat 15:30  Piñata, until it breaks
+  Sat 15:45  Party bags and goodbyes
+```
+
+```bash
+# 4. a live timeline for the fridge door (or a phone): timers, cues, and you end the piñata when it breaks
+rhylthyme publish birthday-party.json --open --image party-preview.png
+
+# 5. a picture for the group chat, on the wall clock (needs Node; nothing to install)
+npx -y github:rhylthyme/rhylthyme-timeline birthday-party.json -o birthday-party.png \
+  --style web --palette vivid --label-overflow outside --start-at "$(date +%F)T12:50:00"
+```
+
+![Eighth birthday party: the party, the kitchen and the setup crew on a wall-clock axis](https://raw.githubusercontent.com/rhylthyme/rhylthyme-cli-runner/main/examples/recipe/birthday-party.png)
+
+The pizzas go in 15 minutes after the games *start*, so they come out as the
+games end; the party bags get filled while everyone is eating. Try
+`--finish-at 17:30`, or turn the cake into a two-hour fruitcake (`"seconds": "2h"`
+on `bake`) and `analyze` reports the clash: `oven needs 2 but max is 1 from
+1:45:00 to 2:00:00 (bake, heat-pizza)`. `rhylthyme run birthday-party.json --time-scale 60` rehearses
+the whole afternoon in the terminal at a minute per second.
+
+## This repository and rhylthyme-mcp
+
+Two repositories do related things and are easy to confuse. This one is the
+**command a person types**. [rhylthyme-mcp](https://github.com/rhylthyme/rhylthyme-mcp)
+is the **server an AI assistant talks to**.
+
+| | [rhylthyme-mcp](https://github.com/rhylthyme/rhylthyme-mcp) | [rhylthyme-cli-runner](https://github.com/rhylthyme/rhylthyme-cli-runner) |
+|---|---|---|
+| What it is | The MCP **server**: the tools an AI assistant calls | A command-line **program**: the `rhylthyme` command |
+| Who uses it | Claude, ChatGPT, Cursor or any MCP client, on a person's behalf | A person at a terminal, a script, or CI |
+| Where it runs | Hosted at `mcp.rhylthyme.com`; nothing to install | On your machine: `pip install rhylthyme-cli-runner` |
+| Language | JavaScript (Node 20+) | Python 3.12+ |
+| Input | A program the assistant builds in conversation | A program file on disk (JSON or YAML) |
+| Validate a program | `validate_program` | `rhylthyme validate` (works offline) |
+| Import a recipe or protocol | `import_from_source` | `rhylthyme import` |
+| Timing, conflicts, deadlines | `analyze_schedule` | `rhylthyme analyze` (asks the server) |
+| Publish a live timeline | `visualize_schedule` | `rhylthyme publish` (asks the server) |
+| Run a schedule with timers | no: it hands back a link to the web timeline | `rhylthyme run`, an interactive terminal runner |
+| Recorded runs, calibration | reads runs saved to an account | records runs locally; `rhylthyme runs`, `rhylthyme calibrate` |
+| Catalog search, account library | yes | no |
+| Also in the repository | the `rhylthyme-mcp` PyPI package (a stdio bridge to the hosted server), the Claude plugin marketplace | the Claude skill's source, the prompt-evaluation harness and its results, `rhylthyme mcp-test` |
+
+How they fit together: this tool is one of the MCP server's clients.
+`rhylthyme analyze`, `publish`, `generate` and `mcp-test` are MCP calls to
+`mcp.rhylthyme.com`; `rhylthyme validate`, `run`, `runs` and `calibrate` never
+touch the network. Each has its own validator for the same program schema
+(Python here, JavaScript there), so a program is checked again when it is
+published.
+
+Use this repository if you have a program file and a terminal, want timers in
+the terminal, or keep run records. Use rhylthyme-mcp to connect Claude, ChatGPT
+or another assistant, or to read or self-host the server.
+
+Two names to keep apart: `rhylthyme-cli-runner` on PyPI is this tool (command
+`rhylthyme`); `rhylthyme-mcp` on PyPI is the server's stdio bridge (command
+`rhylthyme-mcp`). The program format itself is defined in
+[rhylthyme-spec](https://github.com/rhylthyme/rhylthyme-spec), with examples in
+[rhylthyme-examples](https://github.com/rhylthyme/rhylthyme-examples).
+
 ## Installation
 
 ### From Source
@@ -197,6 +298,16 @@ it for conflicts, and hand back a live timeline. It follows the layout of
 [K-Dense scientific skills](https://github.com/K-Dense-AI/claude-scientific-skills):
 a `SKILL.md` plus `references/`.
 
+The easiest install is the Claude Code plugin, which also connects the hosted
+MCP server:
+
+```
+/plugin marketplace add rhylthyme/rhylthyme-mcp
+/plugin install rhylthyme@rhylthyme
+```
+
+Or copy the skill by hand:
+
 ```bash
 # Claude Code, for one user
 mkdir -p ~/.claude/skills
@@ -361,15 +472,37 @@ and tracks that finish early. No sign-in; nothing is published.
 
 ### `rhylthyme publish`
 
-Publishes a program file as a live timeline and prints its URL. No sign-in.
+Publishes a program (a file, an http(s) URL, or `-` for standard input) as a
+live timeline and prints its URL. No sign-in.
 A published timeline is reachable by anyone who has the link.
 
 **Options:**
 - `-e, --env`: `generic`, `kitchen`, `lab`, `events`, `gym` (default: from `environmentType`)
 - `-q, --quiet`: print only the URL
 - `--json`: `url`, `shareId`, `imageUrl`, `makespanSeconds`, `warnings`
+- `--image PATH`: also save a PNG of the timeline
 - `--open`: open it in a browser
 
+### `rhylthyme import`
+
+Imports a recipe, protocol or slide deck as a program, validates it, and
+writes `<programId>.json`. Needs `rhylthyme-importers` (included in
+`pip install rhylthyme`).
+
+```bash
+rhylthyme import https://www.seriouseats.com/the-best-chili-recipe   # any of ~580 recipe sites
+rhylthyme import 52772 -i themealdb --publish                        # a TheMealDB id, straight to a live timeline
+rhylthyme import https://www.protocols.io/view/western-blot-...      # needs PROTOCOLS_IO_TOKEN
+rhylthyme import protocol.py -o protocol.json                        # an Opentrons file
+rhylthyme import "Neapolitan Pizza.cook" -i cooklang
+rhylthyme importers                                                  # what is installed
+rhylthyme search "pad thai" -i spoonacular                           # then import a hit's URL
+```
+
+**Options:** `-i IMPORTER` (default: chosen from the URL), `-o PATH`,
+`--stdout`, `--publish` (and `--open`), `--no-validate`. `-` reads pasted
+source from stdin (with `-i`).
+
 ### `rhylthyme plan`
 
 An older stagger heuristic. It reads the pre-0.2 program format and leaves

{rhylthyme_cli_runner-0.2.2a0 → rhylthyme_cli_runner-0.2.4a0}/setup.py

@@ -19,7 +19,7 @@ def read_readme():
 
 setup(
     name="rhylthyme-cli-runner",
-    version="0.2.2a0",
+    version="0.2.4a0",
     description="CLI runner for Rhylthyme real-time program schedules",
     long_description=read_readme(),
     long_description_content_type="text/markdown",

{rhylthyme_cli_runner-0.2.2a0 → rhylthyme_cli_runner-0.2.4a0}/src/rhylthyme_cli_runner/__init__.py

@@ -6,7 +6,7 @@ This package provides the command-line interface for running and validating
 Rhylthyme real-time program schedules.
 """
 
-__version__ = "0.2.2a0"
+__version__ = "0.2.4a0"
 __author__ = "Rhylthyme Team"
 __description__ = "CLI runner for Rhylthyme real-time program schedules"
 

{rhylthyme_cli_runner-0.2.2a0 → rhylthyme_cli_runner-0.2.4a0}/src/rhylthyme_cli_runner/cli.py

@@ -544,6 +544,16 @@ def _register_remote_commands():
 _register_remote_commands()
 
 
+def _register_import_commands():
+    """Attach `import`, `search`, `importers` (rhylthyme_cli_runner.import_cli)."""
+    from .import_cli import register as register_import
+
+    register_import(cli)
+
+
+_register_import_commands()
+
+
 def main():
     """Entry point for the CLI."""
     cli()

{rhylthyme_cli_runner-0.2.2a0 → rhylthyme_cli_runner-0.2.4a0}/src/rhylthyme_cli_runner/history/render.py

@@ -76,6 +76,15 @@ def find_renderer() -> Optional[Path]:
         candidate = Path(explicit).expanduser()
         # Absolute: `node -e` has no script directory to resolve against.
         return candidate.resolve() if candidate.is_file() else None
+    # The pip package (rhylthyme-timeline) carries the renderer.
+    try:
+        from rhylthyme_timeline import renderer_path
+
+        packaged = renderer_path()
+        if packaged.is_file():
+            return packaged
+    except ImportError:
+        pass
     here = Path(__file__).resolve()
     for parent in here.parents:
         for relative in _RENDERER_PATHS:

rhylthyme_cli_runner-0.2.4a0/src/rhylthyme_cli_runner/import_cli.py

@@ -0,0 +1,250 @@
+"""``rhylthyme import`` and ``rhylthyme search``: the importers from
+rhylthyme-importers, reached from the one command people already have.
+
+``rhylthyme-import`` (the importers' own command) still exists; this is the
+same work with the CLI's validation and publishing on the end of it.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+import click
+
+INSTALL_HINT = (
+    "The importers are a separate package: pip install rhylthyme-importers "
+    "(or pip install rhylthyme, which includes them)."
+)
+
+
+def _registry():
+    try:
+        from rhylthyme_importers import ImporterRegistry
+    except ImportError:
+        raise click.ClickException(INSTALL_HINT)
+    return ImporterRegistry
+
+
+def _pick(registry, source: str, importer_name: Optional[str]):
+    if importer_name:
+        importer = registry.get(importer_name)
+        if importer is None:
+            names = ", ".join(sorted(i["name"] for i in registry.list_importers()))
+            raise click.ClickException(
+                f"Unknown importer '{importer_name}'. Installed: {names}."
+            )
+        return importer
+    importer = registry.find_for_url(source)
+    if importer is None:
+        names = ", ".join(sorted(i["name"] for i in registry.list_importers()))
+        raise click.ClickException(
+            f"No importer recognises {source!r}. Pass -i with one of: {names}. "
+            "For a file on disk, name its importer (-i opentrons, -i cooklang, -i slidedeck)."
+        )
+    return importer
+
+
+def _import_one(importer, source: str, text: Optional[str]):
+    if text is not None and hasattr(importer, "import_from_source"):
+        return importer.import_from_source(text)
+    if text is not None and hasattr(importer, "import_from_content"):
+        return importer.import_from_content(
+            text, source_name=Path(source).stem if source != "-" else "recipe"
+        )
+    path = Path(source)
+    if path.is_file():
+        # A local file was named explicitly; that is the command line's job
+        # to allow (a server never does this).
+        if hasattr(importer, "allow_local_files"):
+            importer.allow_local_files = True
+        return importer.import_from_url(str(path))
+    return importer.import_from_url(source)
+
+
+def _validation(program: dict):
+    from .validate_program import validate_program_file_structured
+
+    with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as tmp:
+        json.dump(program, tmp)
+        tmp_path = tmp.name
+    try:
+        from .cli import _default_schema_path
+
+        return validate_program_file_structured(
+            tmp_path, schema_file=_default_schema_path()
+        )
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
+
+
+@click.command("import")
+@click.argument("source", metavar="URL_OR_ID_OR_FILE")
+@click.option(
+    "-i",
+    "--importer",
+    "importer_name",
+    default=None,
+    help="Which importer to use (default: chosen from the URL).",
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(dir_okay=False),
+    default=None,
+    help="Write the program here (default: <name>.json in the current directory).",
+)
+@click.option(
+    "--stdout",
+    "to_stdout",
+    is_flag=True,
+    help="Print the program instead of writing a file.",
+)
+@click.option(
+    "--publish",
+    "do_publish",
+    is_flag=True,
+    help="Also publish it as a live timeline and print the URL.",
+)
+@click.option(
+    "--open",
+    "open_url",
+    is_flag=True,
+    help="With --publish: open the timeline in a browser.",
+)
+@click.option(
+    "--no-validate", is_flag=True, help="Skip validation of the imported program."
+)
+def import_command(
+    source, importer_name, output, to_stdout, do_publish, open_url, no_validate
+):
+    """Import a recipe, protocol or deck as a program.
+
+    \b
+    URL_OR_ID_OR_FILE is a recipe-site or protocols.io URL, a TheMealDB or
+    Spoonacular id, a .cook or GitHub .cook URL, or a local .py (Opentrons),
+    .cook or .pptx file. `-` reads the source text from stdin (with -i).
+      rhylthyme import https://www.seriouseats.com/the-best-chili-recipe
+      rhylthyme import 52772 -i themealdb --publish
+      rhylthyme import protocol.py -o protocol.json
+      rhylthyme importers          # what is installed
+    """
+    registry = _registry()
+    text = None
+    if source == "-":
+        if not importer_name:
+            raise click.ClickException(
+                "Reading from stdin needs -i to say which importer."
+            )
+        text = sys.stdin.read()
+    importer = _pick(registry, source, importer_name)
+    click.echo(f"Importing with {importer.name}…", err=True)
+    result = _import_one(importer, source, text)
+    if not result.success:
+        raise click.ClickException(result.error or "import failed")
+    program = result.program
+
+    if not no_validate:
+        v = _validation(program)
+        errors = v.get("errors") or v.get("logic_errors") or []
+        if not v.get("is_valid", v.get("valid", True)):
+            for e in errors[:8]:
+                click.echo(
+                    f"  ✗ {e if isinstance(e, str) else e.get('message', e)}", err=True
+                )
+            raise click.ClickException(
+                "The imported program does not validate; not published. Re-run with --no-validate to keep it anyway."
+            )
+        for w in (v.get("warnings") or [])[:5]:
+            click.echo(
+                f"  ! {w if isinstance(w, str) else w.get('message', w)}", err=True
+            )
+
+    payload = json.dumps(program, indent=2, ensure_ascii=False)
+    if to_stdout:
+        click.echo(payload)
+    else:
+        target = (
+            Path(output)
+            if output
+            else Path(f"{program.get('programId') or 'program'}.json")
+        )
+        target.write_text(payload + "\n")
+        click.echo(f"Saved {target}", err=True)
+
+    if do_publish:
+        from .remote.cli import publish as publish_command
+
+        ctx = click.get_current_context()
+        with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as tmp:
+            tmp.write(payload)
+            tmp_path = tmp.name
+        try:
+            ctx.invoke(
+                publish_command,
+                program_file=tmp_path,
+                environment=None,
+                open_url=open_url,
+                json_output=False,
+                quiet=True,
+                image_path=None,
+            )
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+
+
+@click.command("search")
+@click.argument("query")
+@click.option(
+    "-i",
+    "--importer",
+    "importer_name",
+    default="themealdb",
+    show_default=True,
+    help="Which catalogue to search.",
+)
+@click.option("--json", "json_output", is_flag=True)
+def search_command(query, importer_name, json_output):
+    """Search a recipe or protocol source; import a hit with `rhylthyme import <url>`."""
+    registry = _registry()
+    importer = registry.get(importer_name)
+    if importer is None:
+        names = ", ".join(sorted(i["name"] for i in registry.list_importers()))
+        raise click.ClickException(
+            f"Unknown importer '{importer_name}'. Installed: {names}."
+        )
+    hits = importer.search(query)
+    if json_output:
+        click.echo(json.dumps(hits, indent=2, ensure_ascii=False))
+        return
+    if not hits:
+        click.echo("No results.")
+        return
+    for h in hits:
+        click.echo(f"{h.get('name')}\n    {h.get('url')}")
+        if h.get("description"):
+            click.echo(f"    {h['description']}")
+
+
+@click.command("importers")
+def importers_command():
+    """List the installed importers."""
+    registry = _registry()
+    for info in registry.list_importers():
+        domains = info.get("supported_domains") or []
+        where = (
+            ", ".join(domains[:4])
+            + (f", … ({len(domains)} sites)" if len(domains) > 4 else "")
+            if domains
+            else "files, ids or pasted text"
+        )
+        click.echo(f"{info['name']:18} {info['description']}  [{where}]")
+
+
+def register(cli_group: click.Group) -> None:
+    cli_group.add_command(import_command)
+    cli_group.add_command(search_command)
+    cli_group.add_command(importers_command)