Skip to content

install: v1 is the stable release #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ZergsLaw wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

install: v1 is the stable release #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 37 additions & 63 deletions content/docs/introduction/install.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,15 @@
title: "Install EasyP"
---

<Callout type="info">
Install EasyP v1 only by an explicitly selected, published nightly tag. The default stable installation remains v0.17.0 while v1 has only prerelease tags. To use the v1 configuration and commands in these docs, follow [the nightly instructions](#opt-into-v1-nightly).
</Callout>
EasyP v1 is the current release. Every channel below installs it; projects still on v0 can move with [`easyp migrate`](/docs/migration/easyp-v0).

## Install the stable CLI
## Install the CLI

<Tabs items={["Homebrew", "Go install", "Binary Download"]}>
<Tabs items={["Homebrew", "Go install", "Binary Download", "Docker"]}>
<Tab value="Homebrew">
#### Homebrew

You can install a binary release on macOS using brew:
On macOS or Linux, the formula installs both `easyp` and the `easyp-mcp` server:

```bash
brew install easyp-tech/tap/easyp
Expand All @@ -23,82 +21,58 @@ Install EasyP v1 only by an explicitly selected, published nightly tag. The defa
<Tab value="Go install">
#### Go toolchain

Install the latest published stable version using the Go toolchain required by that release:
Building v1 requires **Go 1.26.6 or later**:

```bash
go install github.com/easyp-tech/easyp/cmd/easyp@latest
go install github.com/easyp-tech/easyp/cmd/easyp-mcp@latest
```
</Tab>
<Tab value="Binary Download">
Download the archive for your OS and architecture from the [latest stable release](https://github.com/easyp-tech/easyp/releases/latest). Extract it and place the `easyp` binary on `PATH`.
</Tab>
</Tabs>

The stable Docker channel is `ghcr.io/easyp-tech/easyp:latest`; it currently
points to the same image as `ghcr.io/easyp-tech/easyp:v0.17.0`.
Every archive contains both `easyp` and `easyp-mcp`. Download the one for your OS and architecture from the [latest release](https://github.com/easyp-tech/easyp/releases/latest) and verify it with the release checksums. For Linux amd64:

## Opt into v1 nightly

Nightly tags use `v1.0.0-nightly.YYYYMMDD.sequence`. The commands below pin [v1.0.0-nightly.20261009.1](https://github.com/easyp-tech/easyp/releases/tag/v1.0.0-nightly.20261009.1). To select another version, choose an exact published tag from [GitHub Releases](https://github.com/easyp-tech/easyp/releases). Nightly releases do not update the stable Homebrew formula or Docker `latest` image.
```bash
TAG=$(curl -fsSL https://api.github.com/repos/easyp-tech/easyp/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')
VERSION="${TAG#v}"
ASSET="easyp-${VERSION}-linux-amd64.tar.gz"
curl -fLO "https://github.com/easyp-tech/easyp/releases/download/${TAG}/${ASSET}"
curl -fLO "https://github.com/easyp-tech/easyp/releases/download/${TAG}/easyp-${VERSION}-checksums.txt"
sha256sum --check --ignore-missing "easyp-${VERSION}-checksums.txt"
tar -xzf "$ASSET"
sudo install "easyp-${VERSION}-linux-amd64/easyp" "easyp-${VERSION}-linux-amd64/easyp-mcp" /usr/local/bin/
```

### Go: CLI and MCP
macOS archives use `darwin`; Windows archives use `.zip` and contain `.exe` binaries. No Go toolchain is needed to run these binaries.
</Tab>
<Tab value="Docker">
The CLI image is published to GHCR as `latest` and as each exact release tag:

Building v1 requires **Go 1.26.6 or later**. Install both binaries at the same exact version in a separate directory to keep your stable CLI on `PATH`:
```bash
docker run --rm -v "$PWD:/workspace" -w /workspace \
ghcr.io/easyp-tech/easyp:latest --version
```

```bash
# Select an exact published nightly tag.
NIGHTLY_TAG='v1.0.0-nightly.20261009.1'
NIGHTLY_BIN="$HOME/.local/share/easyp-nightly/bin"
mkdir -p "$NIGHTLY_BIN"
GOBIN="$NIGHTLY_BIN" go install "github.com/easyp-tech/easyp/cmd/easyp@${NIGHTLY_TAG}"
GOBIN="$NIGHTLY_BIN" go install "github.com/easyp-tech/easyp/cmd/easyp-mcp@${NIGHTLY_TAG}"
"$NIGHTLY_BIN/easyp" --version
```
Replace `--version` with the EasyP command you need, and pin an exact tag in CI. This image contains the CLI; use Homebrew, Go install or an archive for the MCP stdio server.
</Tab>
</Tabs>

Invoke the nightly CLI by its full path. Configure your MCP client to run the `easyp-mcp` binary from this directory as a stdio server; it exposes the v1 configuration reference through `easyp_config_describe`. To run the v1 examples with bare `easyp` commands, select the nightly for that terminal session with `export PATH="$NIGHTLY_BIN:$PATH"`. Keep it off your permanent `PATH` to retain stable defaults.
Configure your MCP client to run `easyp-mcp` as a stdio server; it exposes the v1 configuration reference through `easyp_config_describe`.

### Release archive: CLI and MCP
## Staying on v0

The v1 archive contains both `easyp` and `easyp-mcp`. Download the asset matching your platform and verify it with the release checksums. For Linux amd64:
v0 remains available by its exact version, for projects that have not migrated yet or to record a baseline before migrating:

```bash
# Select an exact published nightly tag.
NIGHTLY_TAG='v1.0.0-nightly.20261009.1'
NIGHTLY_VERSION="${NIGHTLY_TAG#v}"
NIGHTLY_ASSET="easyp-${NIGHTLY_VERSION}-linux-amd64.tar.gz"
NIGHTLY_BIN="$HOME/.local/share/easyp-nightly/bin"
curl -fLO "https://github.com/easyp-tech/easyp/releases/download/${NIGHTLY_TAG}/${NIGHTLY_ASSET}"
curl -fLO "https://github.com/easyp-tech/easyp/releases/download/${NIGHTLY_TAG}/easyp-${NIGHTLY_VERSION}-checksums.txt"
sha256sum --check --ignore-missing "easyp-${NIGHTLY_VERSION}-checksums.txt"
mkdir -p "$NIGHTLY_BIN"
tar -xzf "$NIGHTLY_ASSET" --strip-components=1 -C "$NIGHTLY_BIN"
"$NIGHTLY_BIN/easyp" --version
go install github.com/easyp-tech/easyp/cmd/easyp@v0.17.0
docker run --rm -v "$PWD:/workspace" -w /workspace ghcr.io/easyp-tech/easyp:v0.17.0 --version
```

Invoke the CLI and MCP binaries by their full paths in this separate directory. macOS archives use `darwin`; Windows archives use `.zip` and contain `.exe` binaries. No Go toolchain is needed to run these binaries.

### Docker: CLI

The nightly CLI image uses its exact tag in GHCR:
## Prereleases

```bash
# Select an exact published nightly tag.
NIGHTLY_TAG='v1.0.0-nightly.20261009.1'
docker run --rm -v "$PWD:/workspace" -w /workspace \
"ghcr.io/easyp-tech/easyp:${NIGHTLY_TAG}" --version
```

Replace `--version` with the EasyP command you need. This image contains the CLI; use the Go install or archive for the MCP stdio server.
Prerelease builds are published as `v1.X.Y-nightly.YYYYMMDD.N` tags on [GitHub Releases](https://github.com/easyp-tech/easyp/releases) and as `ghcr.io/easyp-tech/easyp:<nightly-tag>`. They are installed only by their exact tag, for example `go install github.com/easyp-tech/easyp/cmd/easyp@<nightly-tag>`, and never update Homebrew, Go `@latest` or the Docker `latest` image.

## Go modules: moving from v0 to v1

EasyP v0 and v1 share the module path `github.com/easyp-tech/easyp`; there is no `/v1` suffix. Go requires a new `/v2` path starting at major version 2 so incompatible major versions can coexist. A v0→v1 upgrade can still require changes to your code and configuration. See [Go's version numbering](https://go.dev/doc/modules/version-numbers).

Merging v1 development into `main` leaves the published `v0.17.0` tag and pinned v0 installations unchanged. When starting from v0, `@latest` and ordinary `go get -u` prefer a published stable version over v1 prereleases; explicitly requesting a nightly opts into v1 and its API/configuration changes. An existing requirement on a higher prerelease is not automatically downgraded. See [Go version queries](https://go.dev/ref/mod#version-queries).

A stable `v1.0.0` Git tag would become eligible for Go's default selection even without a GitHub Release, or if that Release were marked prerelease. For this nightly-only phase, publish only the exact nightly tag format above. `@main` explicitly requests development code; it is not the stable installation channel.
EasyP v0 and v1 share the module path `github.com/easyp-tech/easyp`; there is no `/v1` suffix. Go requires a new `/v2` path starting at major version 2 so incompatible major versions can coexist. See [Go's version numbering](https://go.dev/doc/modules/version-numbers).

Go selects one version per module path for a build. A different dependency
requiring a v1 nightly can also raise the selected EasyP version through
[minimal version selection](https://go.dev/ref/mod#minimal-version-selection).
Library consumers keeping v0 need a dependency graph compatible with that version.
Code that imports EasyP as a library therefore moves to v1 on `go get -u` or `@latest`, and the v1 API and configuration may require changes. Pin `v0.17.0` until that code is ported. Go selects one version per module path for a build, so a different dependency requiring v1 can also raise the selected EasyP version through [minimal version selection](https://go.dev/ref/mod#minimal-version-selection).
Loading
Loading