pipefy · gbrlcustodio · Jul 7, 2026 · Jul 6, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **CLI**: `pipefy card fill <card_id> --phase <phase_id> --fields '{"…"}'` fills phase fields non-interactively; filters to editable phase field IDs before `update_card`. Optional `--required-only` limits the phase field lookup to required fields. JSON responses may include `skipped_field_ids` when `--fields` keys are dropped by the filter.
 - **SDK**: `pipefy_sdk.field_filters` exports `filter_editable_field_definitions`, `filter_fields_by_definitions`, and `skipped_field_ids` for shared MCP/CLI field filtering.
 
+### Changed
+
+- **CLI / Plugin (Claude Code)**: the CLI install path now installs `pipefy-cli` from PyPI instead of a `git+…#subdirectory=packages/cli` reference with `--with` sibling pins. The `/pipefy:install` slash command runs `uv tool install --force pipefy-cli`, and the documented snippets (root `README.md`, `packages/cli/README.md`, `docs/MIGRATION.md`) use `uvx --from pipefy-cli pipefy …` / `uv tool install pipefy-cli`. PyPI resolves `pipefy` and `pipefy-auth` transitively, so the explicit `--with` flags are gone and installs no longer pay a git clone plus build. This matches the MCP server's PyPI install (#368); do not pass a global `--prerelease allow`, which would let transitive dependencies jump to their own pre-releases. `RELEASE.md` verification snippets move to PyPI accordingly, and the now-unused `latest` moving-tag release step is removed. Closes #234.
+
 ## [0.3.0-alpha.1] - 2026-07-04
 
 ### Added

diff --git a/README.md b/README.md
@@ -47,9 +47,9 @@ Feedback and issues: [GitHub Issues](https://github.com/pipefy/ai-toolkit/issues
 
 ## Installation
 
-> Pre-1.0 ships from this git repo via `uvx` and `uv tool install`. PyPI becomes the canonical source at **v1.0**. The current beta line is **`v0.2.0-beta.*`** (first tag: [`v0.2.0-beta.1`](https://github.com/pipefy/ai-toolkit/releases/tag/v0.2.0-beta.1)). Two install paths: the **Quick install** script below (resolves the latest GitHub Release at runtime and runs `uv tool install` for you), or **Claude Code** via the plugin marketplace.
+> Pre-1.0 ships pre-release builds to PyPI on every tag; `uvx` and `uv tool install` resolve them. A stable PyPI release becomes the default at **v1.0**. The current pre-release line is **`v0.3.0-alpha.*`** (first tag: [`v0.3.0-alpha.1`](https://github.com/pipefy/ai-toolkit/releases/tag/v0.3.0-alpha.1)). Two install paths: the **Quick install** script below (resolves the latest GitHub Release at runtime and runs `uv tool install` for you), or **Claude Code** via the plugin marketplace.
 >
-> The CLI snippets below pin **`@latest`**, a moving git tag the release flow updates to point at the most recent release. To pin a specific version, swap `@latest` for a version tag (e.g. `@v0.2.0-beta.2`). The `--with pipefy @ ...#subdirectory=packages/sdk` / `pipefy-auth @ ...#subdirectory=packages/auth` flags are required pre-1.0: this repo is a uv workspace, and the workspace members are not yet published to PyPI, so uv needs them named explicitly. The flags go away at v1.0 (PyPI install).
+> The CLI snippets below install `pipefy-cli` from PyPI, which resolves `pipefy` and `pipefy-auth` transitively (no explicit `--with` needed). While the toolkit ships only pre-release versions (the 0.x line), `uv` resolves the latest pre-release automatically; to pin a specific one, use `pipefy-cli==X.Y.Z` (PEP 440 form, e.g. `pipefy-cli==0.3.0a1`). Do not pass a global `--prerelease allow`: it also lets transitive dependencies jump to their own pre-releases, which can pull a broken build.
 
 Two auth paths:
 
@@ -93,20 +93,13 @@ After install, run `pipefy auth login` to authenticate (`--device` on headless s
 Ad-hoc:
 
 ```sh
-uvx \
-  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
-  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
-  --from "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli" \
-  pipefy-cli --help
+uvx --from pipefy-cli pipefy --help
 ```
 
 Permanent install:
 
 ```sh
-uv tool install \
-  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
-  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
-  "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli"
+uv tool install pipefy-cli
 pipefy --install-completion bash    # or zsh, fish
 pipefy auth login                   # browser OAuth, session in OS keychain
 ```

diff --git a/RELEASE.md b/RELEASE.md
@@ -4,7 +4,7 @@ Workspace distributions (`pipefy`, `pipefy-mcp-server`, `pipefy-cli`, `pipefy-au
 
 ## Cutting a release
 
-The Release workflow publishes to PyPI on **every `v*` tag**: it builds and uploads all five workspace wheels via Trusted Publishing, whatever the version. A pre-release tag (`aN` / `bN` / `rcN`, or the dashed `-alpha.N` / `-beta.N` forms) uploads to PyPI as a pre-release, so `pip` / `uv` install it only with `--pre`, while a stable `vX.Y.Z` tag is what a plain install resolves. Git-reference installs stay available too (for example `uvx --from git+https://github.com/<owner>/<repo>.git@vX.Y.Z --refresh pipefy-cli`).
+The Release workflow publishes to PyPI on **every `v*` tag**: it builds and uploads all five workspace wheels via Trusted Publishing, whatever the version. A pre-release tag (`aN` / `bN` / `rcN`, or the dashed `-alpha.N` / `-beta.N` forms) uploads to PyPI as a pre-release; a plain `uv` / `pip` install resolves it only while no stable version exists, otherwise pass `--pre` or pin the exact pre-release. A stable `vX.Y.Z` tag is what a plain install resolves by default.
 
 ### Public beta line (`v0.2.0-beta.*`)
 
@@ -36,19 +36,11 @@ The Release workflow requires the git tag (without leading `v`) to **exactly mat
    git tag vX.Y.Z && git push origin main && git push origin vX.Y.Z
    ```
 
-6. Roll the `latest` moving tag to point at the same commit. The README install snippets and shipping `.mcp.json` pin `@latest`, so this is what makes new installs pick up the release:
+6. Wait for the **Release** workflow (`.github/workflows/release.yml`) to finish.
+7. Confirm the GitHub Release lists the built wheels (`pipefy_cli-*.whl`, `pipefy_mcp_server-*.whl`, `pipefy-*.whl`, `pipefy_auth-*.whl`, and `pipefy_infra-*.whl`). Optionally verify the published version installs from PyPI (use the PEP 440 form, e.g. `0.2.0b1`, not the `v0.2.0-beta.1` git tag):
 
    ```bash
-   git tag -f latest vX.Y.Z && git push --force-with-lease origin latest
-   ```
-
-   **Skip this step for a pre-release tag** (`aN` / `bN` / `rcN` or the dashed `-alpha.N` / `-beta.N` forms). `latest` drives default installs, so it must track the newest stable release, not a pre-release.
-
-7. Wait for the **Release** workflow (`.github/workflows/release.yml`) to finish.
-8. Confirm the GitHub Release lists the built wheels (`pipefy_cli-*.whl`, `pipefy_mcp_server-*.whl`, `pipefy-*.whl`, `pipefy_auth-*.whl`, and `pipefy_infra-*.whl`). Optionally verify install from the tag, for example:
-
-   ```bash
-   uvx --from git+https://github.com/<owner>/<repo>.git@vX.Y.Z --refresh pipefy-cli --version
+   uvx --from "pipefy-cli==0.2.0b1" pipefy --version
    ```
 
    Sanity-check that the curl installer on `main` resolves the just-cut tag (no per-release maintenance needed; it hits the GitHub API at runtime):
@@ -62,16 +54,16 @@ The Release workflow requires the git tag (without leading `v`) to **exactly mat
 
 ## Verification (cross-platform smoke test)
 
-After tagging a release, run the following on macOS and a Linux machine (or CI runner) to confirm the wheels install correctly:
+After tagging a release, run the following on macOS and a Linux machine (or CI runner) to confirm the wheels install correctly. Pin the **PyPI/PEP 440** version (e.g. `0.2.0b1`), which differs from the `v0.2.0-beta.1` git tag:
 
 ```bash
-# Install CLI from the tagged release
-uvx --from "git+https://github.com/pipefy/ai-toolkit.git@vX.Y.Z" --refresh pipefy-cli --version
-# Expected: X.Y.Z
+# Install CLI from PyPI at the just-published version
+uvx --from "pipefy-cli==0.2.0b1" pipefy --version
+# Expected: the published version
 
 # Verify MCP server starts
-uvx --from "git+https://github.com/pipefy/ai-toolkit.git@vX.Y.Z" --refresh pipefy-mcp-server --help
-# Expected: help text (server may block in stdio mode — Ctrl-C after banner)
+uvx "pipefy-mcp-server==0.2.0b1" --help
+# Expected: help text (server may block in stdio mode, Ctrl-C after banner)
 ```
 
 ## v1.0 and later: stable PyPI installs

diff --git a/commands/install.md b/commands/install.md
@@ -9,10 +9,7 @@ If `command -v pipefy` succeeds, surface `pipefy --version` and stop.
 Otherwise prompt the user to confirm running:
 
 ```
-uv tool install --force \
-  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
-  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
-  "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli"
+uv tool install --force pipefy-cli
 ```
 
 Verify with `pipefy --version`.
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
@@ -6,12 +6,12 @@ Existing users of `pipefy-mcp-server`: this guide covers what changed and what t
 
 ## Package name — unchanged
 
-`pipefy-mcp-server` is the same PyPI package name as before. Your `pip install pipefy-mcp-server` or `uvx pipefy-mcp-server` still works. The existing PyPI version is frozen at the pre-monorepo release; new versions ship at v1.0 via the same name.
+`pipefy-mcp-server` is the same PyPI package name as before, so your `pip install pipefy-mcp-server` or `uvx pipefy-mcp-server` keeps working. Pre-release 0.x builds now publish to PyPI on every tag under this name; while only pre-releases exist a plain install resolves the latest one, and a stable release becomes the default at v1.0.
 
-**Pre-launch (v0.1 → v0.5):** install from git to get the latest:
+**Pre-launch (0.x):** install the latest pre-release from PyPI:
 
 ```sh
-uvx --from git+https://github.com/pipefy/ai-toolkit@latest --refresh pipefy-mcp-server
+uvx pipefy-mcp-server
 ```
 
 ---
@@ -49,10 +49,10 @@ The toolkit lives in the **Pipefy org** at **[github.com/pipefy/ai-toolkit](http
 git remote set-url origin https://github.com/pipefy/ai-toolkit.git
 ```
 
-Pre-1.0 installs from git:
+Pre-1.0 installs the latest pre-release from PyPI:
 
 ```sh
-uvx --from git+https://github.com/pipefy/ai-toolkit@latest --refresh pipefy-mcp-server
+uvx pipefy-mcp-server
 ```
 
 ---
@@ -64,8 +64,7 @@ These are new additions — all optional to adopt:
 **`pipefy-cli`** — a terminal CLI with the same capabilities as the MCP server.
 
 ```sh
-uvx --from git+https://github.com/pipefy/ai-toolkit@latest --refresh pipefy-cli
-pipefy card get 12345
+uvx --from pipefy-cli pipefy card get 12345
 ```
 
 **`skills/` catalog** — Anthropic Skills-format playbooks for common Pipefy workflows, consumable by any LLM agent. Install via [`skills.sh`](https://github.com/vercel-labs/skills):

diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -2,26 +2,19 @@
 
 Typer-based CLI for Pipefy. Exposes all MCP tool capabilities as terminal commands and scripts. Depends on [`pipefy`](../sdk/README.md) for GraphQL calls.
 
-## Install (pre-launch, v0.1 → v0.5)
+## Install
 
 ```sh
-uvx \
-  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
-  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
-  --from "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli" \
-  --refresh pipefy-cli
+uvx --from pipefy-cli pipefy --help
 ```
 
 Or persistently:
 
 ```sh
-uv tool install \
-  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
-  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
-  "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli"
+uv tool install pipefy-cli
 ```
 
-The `--with` flags are required pre-1.0 because the workspace members are not yet on PyPI. At v1.0 this collapses to `uv tool install pipefy-cli`.
+`pipefy-cli` and its dependencies (`pipefy`, `pipefy-auth`) are published to PyPI, so `uv` resolves the whole set from there. While the toolkit ships only pre-release versions (the 0.x line), `uv` resolves the latest pre-release automatically; once a stable release exists it resolves that instead. Do not pass a global `--prerelease allow`: it also lets transitive dependencies jump to their own pre-releases, which can pull a broken build. The console script is `pipefy`, so `uvx --from pipefy-cli` runs it as `pipefy`.
 
 ## Quick start