diff --git a/README.md b/README.md index 2fa78c9..a815f32 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ It exposes the same runtime in three public forms: - First run transcript: [docs/first-run.md](docs/first-run.md) - Terminal walkthrough GIF: [docs/assets/first-run.gif](docs/assets/first-run.gif) - PyPI package: [pypi.org/project/pyro-mcp](https://pypi.org/project/pyro-mcp/) +- What's new in 2.0: [CHANGELOG.md#200](CHANGELOG.md#200) - Host requirements: [docs/host-requirements.md](docs/host-requirements.md) - Integration targets: [docs/integrations.md](docs/integrations.md) - Public contract: [docs/public-contract.md](docs/public-contract.md) @@ -26,24 +27,35 @@ It exposes the same runtime in three public forms: ## Quickstart -Canonical published-package path: +Use either of these equivalent quickstart paths: ```bash +# Package without install python -m pip install uv uvx --from pyro-mcp pyro doctor +uvx --from pyro-mcp pyro env list uvx --from pyro-mcp pyro env pull debian:12 uvx --from pyro-mcp pyro run debian:12 -- git --version ``` ![Quickstart walkthrough](docs/assets/first-run.gif) -From a repo checkout, replace `uvx --from pyro-mcp pyro` with `uv run pyro`. +```bash +# Already installed +pyro doctor +pyro env list +pyro env pull debian:12 +pyro run debian:12 -- git --version +``` + +From a repo checkout, replace `pyro` with `uv run pyro`. What success looks like: ```bash Platform: linux-x86_64 Runtime: PASS +Catalog version: 2.0.0 ... Pulled: debian:12 ... @@ -56,7 +68,6 @@ access to `registry-1.docker.io`, and needs local cache space for the guest imag After the quickstart works: -- inspect the catalog with `uvx --from pyro-mcp pyro env list` - prove the full one-shot lifecycle with `uvx --from pyro-mcp pyro demo` - move to Python or MCP via [docs/integrations.md](docs/integrations.md) @@ -102,7 +113,7 @@ Capabilities: vm_boot=yes guest_exec=yes guest_network=yes Networking: tun=yes ip_forward=yes ``` -### 2. Inspect the catalog and pull the default environment +### 2. Inspect the catalog ```bash uvx --from pyro-mcp pyro env list @@ -117,6 +128,8 @@ debian:12-base [installed|not installed] Minimal Debian 12 environment for shell debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled. ``` +### 3. Pull the default environment + ```bash uvx --from pyro-mcp pyro env pull debian:12 ``` @@ -125,7 +138,7 @@ The first pull downloads an OCI environment from public Docker Hub, requires out access to `registry-1.docker.io`, and needs local cache space for the guest image. See [docs/host-requirements.md](docs/host-requirements.md) for the full host requirements. -### 3. Run one command in a guest +### 4. Run one command in a guest ```bash uvx --from pyro-mcp pyro run debian:12 -- git --version @@ -142,7 +155,7 @@ The guest command output and the `[run] ...` summary are written to different st may appear in either order in terminals or capture tools. Use `--json` if you need a deterministic structured result. -### 4. Optional demos +### 5. Optional demos ```bash uvx --from pyro-mcp pyro demo diff --git a/docs/first-run.md b/docs/first-run.md index 4d2f947..eb2da54 100644 --- a/docs/first-run.md +++ b/docs/first-run.md @@ -2,8 +2,9 @@ This is the intended evaluator path for a first successful run on a supported host. Copy the commands as-is. Paths and timing values will differ on your machine. -If you are running from a source checkout instead of the published package, replace -`uvx --from pyro-mcp pyro` with `uv run pyro`. +The same sequence works with an installed `pyro` binary by dropping the +`uvx --from pyro-mcp` prefix. If you are running from a source checkout instead +of the published package, replace `pyro` with `uv run pyro`. ## 1. Verify the host diff --git a/docs/install.md b/docs/install.md index f3e5627..c8618e3 100644 --- a/docs/install.md +++ b/docs/install.md @@ -35,9 +35,25 @@ Use these command forms consistently: ## Fastest Evaluation Path -Use the package directly without a manual install: +Use either of these equivalent evaluator paths: -If you are running from a repo checkout instead, replace `uvx --from pyro-mcp pyro` with `uv run pyro`. +```bash +# Package without install +uvx --from pyro-mcp pyro doctor +uvx --from pyro-mcp pyro env list +uvx --from pyro-mcp pyro env pull debian:12 +uvx --from pyro-mcp pyro run debian:12 -- git --version +``` + +```bash +# Already installed +pyro doctor +pyro env list +pyro env pull debian:12 +pyro run debian:12 -- git --version +``` + +If you are running from a repo checkout instead, replace `pyro` with `uv run pyro`. ### 1. Check the host first @@ -133,6 +149,8 @@ When you are done evaluating and want to remove stale cached environments, run ` ## Installed CLI +If you already installed the package, the same evaluator path works with plain `pyro ...`: + ```bash uv tool install pyro-mcp pyro --version diff --git a/src/pyro_mcp/cli.py b/src/pyro_mcp/cli.py index fc88f82..96f0118 100644 --- a/src/pyro_mcp/cli.py +++ b/src/pyro_mcp/cli.py @@ -168,6 +168,7 @@ def _build_parser() -> argparse.ArgumentParser: """ Suggested first run: pyro doctor + pyro env list pyro env pull debian:12 pyro run debian:12 -- git --version diff --git a/tests/test_cli.py b/tests/test_cli.py index 2fd88e9..4c2002c 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -27,6 +27,7 @@ def test_cli_help_guides_first_run() -> None: assert "Suggested first run:" in help_text assert "pyro doctor" in help_text + assert "pyro env list" in help_text assert "pyro env pull debian:12" in help_text assert "pyro run debian:12 -- git --version" in help_text assert "Use `pyro mcp serve` only after the CLI validation path works." in help_text