# Installation

workrex ships prebuilt binaries for macOS on Apple Silicon (`darwin-arm64`) and
Linux on x86_64 (`linux-amd64`). On other platforms,
[build from source](#build-from-source).

Workrex needs a running Rex server and the `rex` CLI on your PATH. See the
[Rex installation docs](https://www.superlogical.com/rex/docs/).

## Install script

The install script downloads the latest release for your platform, checks its
SHA-256 checksum, and puts `workrex` in `/usr/local/bin`, or in `~/.local/bin`
when `/usr/local/bin` is not writable.

```bash
curl -fsSL https://raw.githubusercontent.com/kong109/workrex/main/scripts/install-workrex.sh | bash
```

To pick the directory, set `WORKREX_INSTALL_DIR`. To pin a release, set
`WORKREX_VERSION`:

```bash
curl -fsSL https://raw.githubusercontent.com/kong109/workrex/main/scripts/install-workrex.sh | WORKREX_VERSION=v0.1.278-rex.1 bash
```

Configuration uses `.workrex.yaml`, `~/.config/workrex/`, and `WORKREX_*`
environment variables. See [Configuration](https://kong109.github.io/workrex/guide/configuration/).

## Release tarball

Each [release](https://github.com/kong109/workrex/releases) has a
`workrex-<platform>.tar.gz` and a matching `.sha256` file. This example installs
the macOS build. For Linux, use `workrex-linux-amd64` and `sha256sum -c`.

```bash
curl -fsSLO https://github.com/kong109/workrex/releases/latest/download/workrex-darwin-arm64.tar.gz
curl -fsSLO https://github.com/kong109/workrex/releases/latest/download/workrex-darwin-arm64.sha256
shasum -a 256 -c workrex-darwin-arm64.sha256
tar -xzf workrex-darwin-arm64.tar.gz
mv workrex ~/.local/bin/
```

## Build from source

Building needs Rust. Install it with [rustup](https://rustup.rs/) if you don't
have it, then install the `workrex` package from this repository:

```bash
cargo install --git https://github.com/kong109/workrex --bin workrex
```

## Update

To update a binary from the install script or a tarball, run
[`workrex update`](https://kong109.github.io/workrex/reference/commands/update/). For a source build, run the
`cargo install` command again.

### Existing installations

This build uses its own configuration, state, cache, and Git metadata namespaces.
Use `.workrex.yaml` for each project's settings and `WORKREX_*` for environment
overrides. A copied global profile preserves preferences; it does not import
earlier workspace ownership, recovery records, remote placements, or agent
conversation history.

Existing sessions and earlier stored data are left intact. Finish or stop agents
started by an older build before reopening their worktrees with this build.
Rex can rediscover some running agents for display, but that does not transfer
their earlier management records.

## Shell alias

To type less, alias `workrex` to `wr` in your `.bashrc`, `.zshrc`, or other
shell configuration file:

```bash
alias wr='workrex'
```

## Shell completions

To complete commands and branch names, add the line for your shell to its
configuration file.

### Bash

```bash
# Add to ~/.bashrc
eval "$(workrex completions bash)"
```
### Zsh

```bash
# Add to ~/.zshrc
eval "$(workrex completions zsh)"
```
### Fish

```bash
# Add to ~/.config/fish/config.fish
workrex completions fish | source
```
## Uninstall

The uninstall script runs `workrex uninstall`, which removes the status hooks
and skills that `workrex setup` installed, workrex's state directory, and its
update cache. Then the script deletes the binary from `/usr/local/bin`,
`~/.local/bin`, and `~/.cargo/bin`. To see what `workrex uninstall` would remove,
run `workrex uninstall --dry-run`.

```bash
curl -fsSL https://raw.githubusercontent.com/kong109/workrex/main/scripts/uninstall-workrex.sh | bash
```

The script preserves your configuration at `~/.config/workrex/`. Delete it
yourself when you no longer need those settings. Remove the completion line
and the `wm` alias from your shell configuration. To find worktrees that
are still on disk, run `git worktree list`.