openagents --help

```

Run the same command again to update. The CLI does not include an

`openagents update` command.

## Update

```sh

openagents update

```

The command resolves the same channel the installer resolves, compares the

version it names against the running binary, and stops there when they agree.

Otherwise it downloads the new artifact, fetches `SHA256SUMS-<version>` over a

separate request, refuses anything it cannot verify, and replaces the binary in

place. `openagents self-update` is the same command.

Ask what the channel names without installing anything:

```sh

openagents update --check

```

Follow a different channel, or install one exact version:

```sh

openagents update --channel beta

openagents update --version 0.1.0-rc.2

```

`--force` reinstalls the version already running, which is how you repair a

binary you suspect is damaged.

Running the installer again does the same job and is the right choice when the

binary cannot start at all.

## Install a specific version

version you get next month. Pass an explicit version when you need the answer

to stay the same.

`beta` names the current release candidate. `stable` does not resolve yet:

it starts naming a version when the first release is cut, and until then the

installer says so and stops rather than guessing. Until that happens, pass a

version or follow `beta`.

## Choose where the binary lands

The installer links `openagents` and `oa` into `~/.openagents/bin`. Set

| --- | --- |

| macOS on Apple silicon | `macos-aarch64` |

| macOS on Intel | `macos-x86_64` |

| Linux on x86-64 | `linux-x86_64` |

| Linux on ARM64 | `linux-aarch64` |

| Linux on x86-64, glibc | `linux-x86_64` |

| Linux on x86-64, musl | `linux-x86_64-musl` |

| Linux on ARM64, glibc | `linux-aarch64` |

| Linux on ARM64, musl | `linux-aarch64-musl` |

| Windows on x86-64 | `windows-x86_64` |

On Apple silicon, a shell running under Rosetta reports an Intel processor. The

installer detects that and installs the native `macos-aarch64` build anyway.

On Linux, the installer picks between the two C library builds by looking for

the glibc dynamic loader for your architecture. A system that has it can run

the dynamically linked build and receives it. A system that does not — Alpine,

a distroless or BusyBox image, NixOS — receives the statically linked musl

build, which depends on no loader at all. Distributions are never named or

guessed at, and the check needs no tools beyond the shell, so it holds on

images that carry neither `ldd` nor a release file.

On Alpine and other minimal Linux images, pipe the installer into `sh`. The

script is POSIX shell, and those images ship no `bash`:

```sh

curl -fsSL https://openagents.com/install.sh | sh

```

`bash` works everywhere it exists, so either form is fine on a system that has

it.

On Windows, run the installer under Git for Windows or MSYS2 Bash. It installs

`openagents.exe` and `oa.exe`. Under WSL, use the Linux build: WSL is Linux, and

`uname -s` reports it as such.

#!/bin/bash

#!/bin/sh

#

# OpenAgents CLI installer — https://openagents.com/install.sh

#

# Usage:

#   curl -fsSL https://openagents.com/install.sh | bash            # latest stable

#   curl -fsSL https://openagents.com/install.sh | bash -s 0.1.0   # specific version

#   curl -fsSL https://openagents.com/install.sh | sh            # latest stable

#   curl -fsSL https://openagents.com/install.sh | sh -s 0.1.0   # specific version

#

# Windows: run under Git for Windows / MSYS2 Bash; WSL uses the Linux binary.

#

# This is POSIX shell, not bash, and the difference is the point. The musl

# builds exist for Alpine above all, and Alpine ships no bash: piping this into

# `bash` there fails before the first line runs, with an error about the shell

# rather than about anything the reader did. `sh` is on every system this

# installs to. Piping into `bash` still works and every published form of the

# command keeps working, so nothing that already ran stops running.

#

# What that costs: no `[[ ]]`, no `=~`, and no arrays. Version matching goes

# through `is_version` below, and the parallel download tracks its background

# jobs in a space-separated string.

set -e

TARGET="$1"

if [[ -n "$TARGET" ]] && [[ ! "$TARGET" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9._]+)?$ ]]; then

# The grammar the release publishes under, and the same one `ops/release-cli.sh`

# and `oa update` apply. A version one of them accepts and another rejects is a

# release nobody can ask for.

is_version() {

    printf '%s' "$1" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9._]+)?$'

}

if [ -n "$TARGET" ] && ! is_version "$TARGET"; then

    echo "Invalid version format: $TARGET (expected X.Y.Z or X.Y.Z-suffix)" >&2

    exit 1

fi

    local chunk_size=$(( (size + n - 1) / n ))

    local tmpdir

    tmpdir=$(mktemp -d 2>/dev/null) || { download_file "$url" "$output"; return; }

    local pids=() i start end

    for i in $(seq 0 $((n - 1))); do

    # A space-separated list rather than an array: `wait` takes one pid at a

    # time either way, and this is the part of bash the script does without.

    local pids="" i=0 start end

    while [ "$i" -lt "$n" ]; do

        start=$((i * chunk_size))

        end=$((start + chunk_size - 1))

        [ $end -ge $size ] && end=$((size - 1))

        curl -fsSL -r "${start}-${end}" -o "${tmpdir}/$(printf 'chunk.%03d' "$i")" "$url" &

        pids+=($!)

        pids="$pids $!"

        i=$((i + 1))

    done

    local all_ok=true pid

    for pid in "${pids[@]}"; do

    for pid in $pids; do

        wait "$pid" || all_ok=false

    done

    if [ "$all_ok" = true ] && cat "${tmpdir}"/chunk.* > "$output" 2>/dev/null; then

    fi

fi

# Which C library, on Linux. Two Linux builds exist per architecture because a

# glibc-linked executable does not run on a musl system: the kernel reports the

# missing interpreter as "no such file or directory" against a file that

# plainly exists, which is one of the least legible errors a first install can

# produce.

#

# The test is not "which distribution is this". Distribution detection needs

# files a minimal image may not carry, and `ldd` disagrees with itself across

# implementations -- GNU's prints a version banner to stdout and exits 0, musl's

# prints "musl libc" to stderr, and BusyBox's does neither. The question that

# actually decides the answer is narrower: is the glibc dynamic loader this

# artifact would ask for present on the system?

#

# The gnu artifact is dynamically linked and names that loader in its

# PT_INTERP. The musl artifact is statically linked and names no interpreter at

# all, so it runs anywhere. A system with the loader can run either and gets

# gnu; a system without it can only run musl. That reads correctly on Alpine,

# on a distroless or BusyBox-only image with no `ldd` to ask, on a Debian host

# that happens to have the `musl` package installed, and on NixOS, where the

# loader lives in the Nix store and the static build is genuinely the right

# answer. Every way this test can be wrong sends the reader to the artifact

# that still runs.

#

# $1 is the architecture; $2 is a filesystem root to search under, empty for

# the real one, so the choice can be exercised against a fixture.

linux_libc() {

    libc_arch="$1"

    libc_root="$2"

    case "$libc_arch" in

        x86_64)

            loaders="/lib64/ld-linux-x86-64.so.2 /lib/ld-linux-x86-64.so.2 /lib/x86_64-linux-gnu/ld-linux-x86-64.so.2"

            ;;

        aarch64)

            loaders="/lib/ld-linux-aarch64.so.1 /lib64/ld-linux-aarch64.so.1 /lib/aarch64-linux-gnu/ld-linux-aarch64.so.1"

            ;;

        *)

            echo "gnu"

            return

            ;;

    esac

    for loader in $loaders; do

        if [ -e "${libc_root}${loader}" ]; then

            # A system whose own `ldd` identifies as musl is musl even with a

            # glibc compatibility loader installed beside it, and that is the

            # one case where the loader alone would answer wrongly in the

            # direction that does not run.

            if [ -z "$libc_root" ] && command -v ldd >/dev/null 2>&1; then

                case "$(ldd --version 2>&1 || true)" in

                    *musl*) echo "musl"; return ;;

                esac

            fi

            echo "gnu"

            return

        fi

    done

    echo "musl"

}

libc=""

if [ "$os" = "linux" ]; then

    libc="$(linux_libc "$arch" "")"

fi

BASE_URL_PRIMARY="https://openagents.com/releases"

DOWNLOAD_DIR="$HOME/.openagents/downloads"

BIN_DIR="${OPENAGENTS_BIN_DIR:-$HOME/.openagents/bin}"

mkdir -p "$DOWNLOAD_DIR" "$BIN_DIR"

platform="${os}-${arch}"

# The glibc Linux artifact keeps the unsuffixed name it has always had, so

# every installer already in circulation keeps resolving. musl is the addition

# and carries the suffix.

if [ "$libc" = "musl" ]; then

    platform="${platform}-musl"

    echo "musl libc detected; installing the statically linked build." >&2

fi

CHANNEL="${OPENAGENTS_CHANNEL:-stable}"

# A channel is a pointer file naming the version it currently means, so

    version="$(download_file "${BASE_URL_PRIMARY}/${CHANNEL}" "" 2>/dev/null | tr -d '[:space:]')" || version=""

    if [ -z "$version" ]; then

        echo "Could not resolve the '${CHANNEL}' channel from ${BASE_URL_PRIMARY}/${CHANNEL}." >&2

        echo "Pass a version explicitly: curl -fsSL https://openagents.com/install.sh | bash -s X.Y.Z" >&2

        echo "Pass a version explicitly: curl -fsSL https://openagents.com/install.sh | sh -s X.Y.Z" >&2

        echo "Or follow another channel: OPENAGENTS_CHANNEL=beta" >&2

        exit 1

    fi

    if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9._]+)?$ ]]; then

    if ! is_version "$version"; then

        echo "The '${CHANNEL}' channel returned something that is not a version: ${version}" >&2

        exit 1

    fi

    end

  end

  test "every platform the installer can ask for is admitted", %{conn: conn} do

    Req.Test.stub(__MODULE__, fn upstream ->

      Plug.Conn.send_resp(upstream, 200, "bytes")

    end)

    # The musl artifacts carry two more hyphens than any name that existed when

    # the allowlist was written. A pattern tightened later without them in mind

    # would 404 every Alpine install while every other platform kept working.

    for platform <- [

          "macos-aarch64",

          "macos-x86_64",

          "linux-x86_64",

          "linux-x86_64-musl",

          "linux-aarch64",

          "linux-aarch64-musl",

          "windows-x86_64"

        ] do

      name = "openagents-0.1.0-rc.2-#{platform}"

      assert get(conn, ~p"/releases/#{name}").status == 200, "#{name} was refused"

    end

  end

  test "a deeper path names no object, and the reserved slug is what answers", %{conn: conn} do

    Req.Test.stub(__MODULE__, fn _upstream ->

      flunk("a multi-segment path reached the bucket")

  @script Path.join([File.cwd!(), "priv", "static", "install.sh"])

  defp libc(source, arch, root) do

    {output, 0} =

      System.cmd("bash", ["-c", ". #{source}; linux_libc #{arch} #{root}"],

        stderr_to_stdout: true

      )

    String.trim(output)

  end

  defp fixture(dir, name, paths) do

    root = Path.join(dir, name)

    File.mkdir_p!(root)

    Enum.each(paths, fn path ->

      absolute = Path.join(root, path)

      File.mkdir_p!(Path.dirname(absolute))

      File.write!(absolute, "")

    end)

    root

  end

  test "the installer is served under the name the published command uses" do

    assert "install.sh" in OpenAgentsWeb.static_paths(),

           "`install.sh` is not in static_paths/0, so /install.sh is a 404"

    assert {_output, 0} = System.cmd("bash", ["-n", @script], stderr_to_stdout: true)

  end

  test "the script needs no shell Alpine does not ship" do

    # The musl builds exist for Alpine above all, and Alpine ships no bash.

    # `curl … | bash` there fails before the first line runs, with an error

    # about the shell rather than about anything the reader did. So this is

    # POSIX shell, and these are the three things that would quietly make it

    # bash again.

    assert {_output, 0} = System.cmd("sh", ["-n", @script], stderr_to_stdout: true)

    script = File.read!(@script)

    body = String.replace(script, ~r/^#.*$/m, "")

    refute body =~ "[[", "`[[ ]]` is a bash conditional"

    refute body =~ "=~", "`=~` is a bash regex match"

    refute body =~ ~r/\[@\]/, "an array expansion is bash-only"

  end

  test "nothing is installed without a checksum that matches" do

    script = File.read!(@script)

           "the installer reinstalls whatever is already on disk"

  end

  describe "libc detection" do

    # `linux_libc` is extracted from the served script and run against fixture

    # roots, so these assert the code readers actually receive rather than a

    # copy of it. The choice matters more than most: a glibc binary on a musl

    # system fails at exec with "no such file or directory" naming a file that

    # is plainly there, and nothing in that message points at the installer.

    setup do

      script = File.read!(@script)

      [function] = Regex.run(~r/^linux_libc\(\).*?^\}/ms, script)

      dir = Path.join(System.tmp_dir!(), "install-libc-#{System.unique_integer([:positive])}")

      File.mkdir_p!(dir)

      on_exit(fn -> File.rm_rf(dir) end)

      source = Path.join(dir, "linux_libc.sh")

      File.write!(source, function)

      {:ok, source: source, dir: dir}

    end

    test "a present glibc loader means the dynamically linked build runs", context do

      root = fixture(context.dir, "glibc", ["lib64/ld-linux-x86-64.so.2"])

      assert libc(context.source, "x86_64", root) == "gnu"

    end

    test "a multiarch glibc loader counts too", context do

      root = fixture(context.dir, "multiarch", ["lib/x86_64-linux-gnu/ld-linux-x86-64.so.2"])

      assert libc(context.source, "x86_64", root) == "gnu"

    end

    test "no glibc loader means only the static build runs", context do

      root = fixture(context.dir, "alpine", ["lib/ld-musl-x86_64.so.1"])

      assert libc(context.source, "x86_64", root) == "musl"

    end

    test "an image carrying no libc at all still resolves to the static build", context do

      root = fixture(context.dir, "bare", [])

      assert libc(context.source, "x86_64", root) == "musl"

      assert libc(context.source, "aarch64", root) == "musl"

    end

    test "a glibc host with the musl package installed is still glibc", context do

      # Debian's `musl` package drops a musl loader onto a glibc system. The

      # question is which artifact runs, not which loaders exist, and both do.

      root =

        fixture(context.dir, "both", [

          "lib64/ld-linux-x86-64.so.2",

          "lib/ld-musl-x86_64.so.1"

        ])

      assert libc(context.source, "x86_64", root) == "gnu"

    end

    test "each architecture is judged by its own loader", context do

      root = fixture(context.dir, "arm", ["lib/ld-linux-aarch64.so.1"])

      assert libc(context.source, "aarch64", root) == "gnu"

      # The x86_64 loader is absent from this root, and an architecture's

      # verdict must not be borrowed from another's.

      assert libc(context.source, "x86_64", root) == "musl"

    end

    test "an architecture with no musl build asks for the glibc one", context do

      root = fixture(context.dir, "riscv", [])

      assert libc(context.source, "riscv64", root) == "gnu"

    end

  end

  test "the musl platform is named the way the release publishes it" do

    script = File.read!(@script)

    assert script =~ ~s(platform="${platform}-musl"),

           "the installer detects musl and then asks for the same artifact anyway"

    refute script =~ ~s(platform="${os}-${arch}-${libc}"),

           "the glibc artifact is renamed, which breaks every installer already in circulation"

  end

  test "the channel resolves a version rather than hardcoding one" do

    script = File.read!(@script)