Install the CLI

The current preview provides native tapstate CLI archives for macOS and Linux. The CLI installer is separate from the local Docker playground, so choose the path that matches what you want to do.

This page installs the CLI only. It does not install or start a tapstate server, open a local port, or install connector JARs.

If you want to see tapstate run before installing anything, use the Quickstart. Its convenience command is curl -fsSL https://install.tapstate.dev | sh; that root URL runs the disposable Docker playground and does not add tapstate to your shell PATH.

Understand the CLI and server

The CLI can author and validate a local workspace without a server. A tapstate server is a separate, headless service that exposes an authenticated control plane and runs pipelines; it has no built-in web UI in the current preview.

The CLI cannot test a database connection or move data without a server. This release does not publish a standalone server installer. To explore a server-backed path, use the disposable Quickstart, which downloads its own CLI and starts the server and sample databases with Docker Compose. You do not need to install the CLI first.

Supported platforms

On macOS and glibc-based Linux, the installer checks the release's recommended platform version when the release metadata is available. If the machine is older, it warns but does not stop the installation. The published Linux builds target glibc 2.34 or later; older systems may not launch them. Alpine Linux and other musl-based distributions are not supported by the published binaries. On Windows, use WSL 2 or build from source.

Install the CLI

Choose your platform, then run the CLI installer. The /cli endpoint serves the current pinned preview installer; the installer selects the matching archive and verifies its checksum before placing the binary.

curl -fsSL https://install.tapstate.dev/cli | sh

curl -fsSL https://install.tapstate.dev/cli | sh

The installer sends a one-time anonymous ping on successful installation to help prioritize platform support.

curl -fsSL https://install.tapstate.dev/cli | TAPSTATE_TELEMETRY=off sh

The /cli endpoint returns the installer script. The script may fetch the release's platform-minimums.txt to print a platform notice, then downloads the platform archive and its published SHA-256 checksum from the GitHub release. The installer:

• selects the archive for your operating system and architecture;
• downloads the preview release configured by the installer;
• verifies its SHA-256 checksum;
• installs tapstate in $HOME/.tapstate/bin by default;
• does not use sudo or edit your shell profile.

It should finish with a message similar to:

tapstate installed to <home>/.tapstate/bin/tapstate

Add the installation directory to PATH if it is not already available:

export PATH="$HOME/.tapstate/bin:$PATH"

To keep the setting for future Zsh sessions:

printf '%s\n' 'export PATH="$HOME/.tapstate/bin:$PATH"' >> "$HOME/.zshrc"

Verify the result:

tapstate --version

The command should report tapstate 0.4.3.

When the name tap is available, the installer also creates it as an optional shortcut to tapstate. It skips the shortcut instead of replacing an existing file or command. You can manage it later with:

tapstate alias install
tapstate alias uninstall

If Zsh reports command not found: tapstate, either the installer did not finish or its default directory is not on the current shell's PATH. Check the installed file first:

test -x "$HOME/.tapstate/bin/tapstate" && "$HOME/.tapstate/bin/tapstate" --version

If that succeeds, run the export PATH=... command above for the current shell. After adding it to .zshrc, open a new terminal or run source "$HOME/.zshrc", then repeat tapstate --version.

Recover an interrupted download

The installer stages each downloaded asset in a .part file, retries an interrupted transfer, and resumes an existing .part file when you run the installer again. It only uses the completed archive after its checksum passes.

If the installer reports a download failure, run the same command again. To restart a transfer from zero, remove only the reported .part file; do not remove the installed bundle unless you intend to reinstall it.

Other installation methods

Pin a release

To install a specific preview release instead of the installer's default, set TAPSTATE_VERSION:

curl -fsSL https://install.tapstate.dev/cli | \
  TAPSTATE_VERSION=0.4.3 sh

Replace 0.4.3 with another published release when you need to pin a different version.

Use a different installation directory

Set TAPSTATE_INSTALL_DIR before running the installer:

curl -fsSL https://install.tapstate.dev/cli | \
  TAPSTATE_INSTALL_DIR="$HOME/bin" sh

The selected directory must be on your PATH before you can invoke tapstate by name.

Install manually

The v0.4.3 release includes four platform archives, individual .sha256 files, and a combined checksums.txt. Download the archive that matches your system and verify its checksum before extracting it.

For example, on Apple silicon:

curl -fL --retry 2 -C - -o tapstate-0.4.3-darwin-arm64.tar.gz \
  https://github.com/tapstate/tapstate/releases/download/v0.4.3/tapstate-0.4.3-darwin-arm64.tar.gz
curl -fL --retry 2 -C - -o tapstate-0.4.3-darwin-arm64.tar.gz.sha256 \
  https://github.com/tapstate/tapstate/releases/download/v0.4.3/tapstate-0.4.3-darwin-arm64.tar.gz.sha256

shasum -a 256 -c tapstate-0.4.3-darwin-arm64.tar.gz.sha256
tar -xzf tapstate-0.4.3-darwin-arm64.tar.gz

The archive extracts a complete tapstate-cli-0.4.3 bundle. Keep its bin and

libexec directories together so tapstate mcp can find its sidecar.

If macOS blocks a manually downloaded binary after the checksum passes, remove the quarantine attribute and try again:

xattr -d com.apple.quarantine ./tapstate-cli-0.4.3/bin/tapstate
./tapstate-cli-0.4.3/bin/tapstate --version

Update or remove the CLI

The preview has no automatic updater. To install a later release, rerun the installer and verify the reported version.

To remove the default installation, including versioned bundles and the MCP sidecar:

rm -rf "$HOME/.tapstate"

Workspaces, containers, and external-system data are separate and are not removed.

Connect an MCP host

The full CLI bundle includes tapstate mcp, a local gateway for MCP-compatible AI tools. Configure it after a tapstate server is running and you have created a scoped machine token. See Connect an MCP host for the authentication flow and Codex, Claude Code, and generic host examples.

Next steps

• Create your own workspace using only the installed CLI.
• If Docker is available, run the Quickstart, then explore the order-state demo.
• Review the v0.4 release notes before evaluating the runtime.