OpenAgents

Commit

Correct the install page: three names, POSIX sh, no npm

e347f251b39b · AtlantisPleb · · parent c5c3173a05bb 

Correct the install page: three names, POSIX sh, no npm

The page opened with a banner saying the installer and the standalone
binaries were withdrawn. They were not: `stable` resolves to 0.0.2 and the
installer is the supported path. The banner sent readers to npm instead.

Four other things on the page were false:

- It said the installer links `openagents` and `oa`. It links three names --
  `openagents`, `coder`, and `oa` -- onto one binary, and the page never
  explained that running it bare starts a coder session while giving it a
  command runs that command.
- It told readers to pipe the script into `bash`. The script is `#!/bin/sh`.
- It said `stable` does not resolve and to follow `beta`. That is backwards:
  `stable` names 0.0.2, `beta` resolves to nothing.
- Examples named 0.1.0-rc.1 and 0.1.0-rc.2, versions that were never released.

The npm and npx sections are removed rather than corrected. They claimed the
npm package "provides the same `openagents` command", and it does not -- it is
a different program answering to the same name. That is not a hypothetical
hazard: the 0.0.2 installer put the native binary ahead of the npm one on
PATH and broke `git push` machine-wide this morning, because only one of the
two implements `auth git-credential` correctly. A page offering them as
interchangeable installs of one CLI is how someone ends up with both.

The test asserted the npm command was present, so it encoded the old
contract. It now asserts the three names and the `sh` pipe, and refutes the
npm command, `npx`, the package name, and `| bash`, so none of them returns
quietly. Verified adversarially: reinstating the npm line turns it red.

Seven other docs pages still point at the npm package; those are a separate
change.

Deploy story

What this commit did to the running system — joined from the forge receipt chain, the part a commit page elsewhere cannot show.

pushed
by user · WAL seq 449 · 2026-08-26T15:35:29.864494Z

Changed files

  • modified priv/docs/install-cli.md
  • modified test/openagents_web/docs_catalog_test.exs

Diff

2 files changed, +60 -107

priv/docs/install-cli.md modified +40 -104

@@ -1,27 +1,29 @@

1 1 
# Install the OpenAgents CLI
2 2
3 
> **The `curl | sh` installer and the standalone binaries are withdrawn.**
4 
> The 0.1.0 binary release was published and then removed: its CLI shipped
5 
> commands that printed fabricated data as though it were real. Install with
6 
> npm until a release is cut from a build that has been verified end to end.
7 
>
8 
> ```sh
9 
> npm i -g @openagentsinc/cli
10 
> ```
11
12 3 
The CLI is a single native binary. Install it with the installer script:
13 4
14 5 
```sh
15 
curl -fsSL https://openagents.com/install.sh | bash
6 
curl -fsSL https://openagents.com/install.sh | sh
16 7 
```
17 8
18 9 
The installer detects your operating system and processor, downloads the
19 
matching build, verifies its SHA-256 checksum, and links `openagents` and `oa`
20 
into `~/.openagents/bin`. It also adds that directory to `PATH` in your shell
21 
configuration file. Open a new shell, then confirm the installation:
10 
matching build, verifies its SHA-256 checksum, and links three names —
11 
`openagents`, `coder`, and `oa` — into `~/.openagents/bin`. It also adds that
12 
directory to `PATH` in your shell configuration file. Open a new shell, then
13 
confirm the installation:
14
15 
```sh
16 
openagents --version
17 
```
18
19 
The three names are one binary. Run it bare and it starts a coder session; give
20 
it a command and it runs that command. So `openagents` and `coder` are two doors
21 
onto the same program, and `oa` is the short one:
22 22
23 23 
```sh
24 
openagents --help
24 
coder                   # start a coder session
25 
openagents repo list    # run a command
26 
oa repo list            # the same command, less typing
25 27 
```
26 28
27 29 
## Update

@@ -46,7 +48,7 @@ Follow a different channel, or install one exact version:

46 48
47 49 
```sh
48 50 
openagents update --channel beta
49 
openagents update --version 0.1.0-rc.2
51 
openagents update --version 0.0.2
50 52 
```
51 53
52 54 
`--force` reinstalls the version already running, which is how you repair a

@@ -61,7 +63,7 @@ Pass a version to the script when a script or qualification run must be

61 63 
reproducible:
62 64
63 65 
```sh
64 
curl -fsSL https://openagents.com/install.sh | bash -s 0.1.0-rc.1
66 
curl -fsSL https://openagents.com/install.sh | sh -s 0.0.2
65 67 
```
66 68
67 69 
The version must read as `X.Y.Z` or `X.Y.Z-suffix`. The installer refuses

@@ -74,25 +76,29 @@ currently names. `stable` is the default. Set `OPENAGENTS_CHANNEL` to follow a

74 76 
different one:
75 77
76 78 
```sh
77 
curl -fsSL https://openagents.com/install.sh | OPENAGENTS_CHANNEL=beta bash
79 
curl -fsSL https://openagents.com/install.sh | OPENAGENTS_CHANNEL=beta sh
78 80 
```
79 81
80 82 
A channel is a pointer that moves, so the version you get today is not the
81 83 
version you get next month. Pass an explicit version when you need the answer
82 84 
to stay the same.
83 85
84 
`beta` names the current release candidate. `stable` does not resolve yet:
85 
it starts naming a version when the first release is cut, and until then the
86 
installer says so and stops rather than guessing. Until that happens, pass a
87 
version or follow `beta`.
86 
`stable` names the current release and is what you get by default. `beta` does
87 
not resolve at present: a channel that names no version makes the installer say
88 
so and stop rather than guess, so follow `beta` only when a release candidate is
89 
outstanding. Ask a channel what it names without installing anything:
90
91 
```sh
92 
curl -fsSL https://openagents.com/releases/stable
93 
```
88 94
89 95 
## Choose where the binary lands
90 96
91 
The installer links `openagents` and `oa` into `~/.openagents/bin`. Set
92 
`OPENAGENTS_BIN_DIR` to link them somewhere already on your `PATH`:
97 
The installer links `openagents`, `coder`, and `oa` into `~/.openagents/bin`.
98 
Set `OPENAGENTS_BIN_DIR` to link them somewhere already on your `PATH`:
93 99
94 100 
```sh
95 
curl -fsSL https://openagents.com/install.sh | OPENAGENTS_BIN_DIR="$HOME/.local/bin" bash
101 
curl -fsSL https://openagents.com/install.sh | OPENAGENTS_BIN_DIR="$HOME/.local/bin" sh
96 102 
```
97 103
98 104 
The downloaded binary itself always lands in `~/.openagents/downloads`.

@@ -120,19 +126,14 @@ build, which depends on no loader at all. Distributions are never named or

120 126 
guessed at, and the check needs no tools beyond the shell, so it holds on
121 127 
images that carry neither `ldd` nor a release file.
122 128
123 
On Alpine and other minimal Linux images, pipe the installer into `sh`. The
124 
script is POSIX shell, and those images ship no `bash`:
125
126 
```sh
127 
curl -fsSL https://openagents.com/install.sh | sh
128 
```
129
130 
`bash` works everywhere it exists, so either form is fine on a system that has
131 
it.
129 
The script is POSIX shell, so `sh` runs it everywhere, including Alpine and
130 
other minimal images that ship no `bash`. `bash` also runs it on any system that
131 
has one, so either form works.
132 132
133 133 
On Windows, run the installer under Git for Windows or MSYS2 Bash. It installs
134 
`openagents.exe` and `oa.exe`. Under WSL, use the Linux build: WSL is Linux, and
135 
`uname -s` reports it as such.
134 
`openagents.exe`, `coder.exe`, and `oa.exe` as three copies rather than
135 
symlinks. Under WSL, use the Linux build: WSL is Linux, and `uname -s` reports
136 
it as such.
136 137
137 138 
## What the installer verifies
138 139

@@ -153,72 +154,15 @@ and says so.

153 154 
Download the artifact and its sums file, then compare them yourself:
154 155
155 156 
```sh
156 
curl -fsSLO https://openagents.com/releases/openagents-0.1.0-rc.1-macos-aarch64
157 
curl -fsSLO https://openagents.com/releases/SHA256SUMS-0.1.0-rc.1
158 
shasum -a 256 openagents-0.1.0-rc.1-macos-aarch64
159 
grep openagents-0.1.0-rc.1-macos-aarch64 SHA256SUMS-0.1.0-rc.1
157 
curl -fsSLO https://openagents.com/releases/openagents-0.0.2-macos-aarch64
158 
curl -fsSLO https://openagents.com/releases/SHA256SUMS-0.0.2
159 
shasum -a 256 openagents-0.0.2-macos-aarch64
160 
grep openagents-0.0.2-macos-aarch64 SHA256SUMS-0.0.2
160 161 
```
161 162
162 163 
The two hexadecimal digests must match exactly. On Linux, use `sha256sum` in
163 164 
place of `shasum -a 256`.
164 165
165 
## Install with npm instead
166
167 
The npm package is `@openagentsinc/cli`. It provides the same `openagents`
168 
command and requires Node.js 20 or later. Use it when you already manage your
169 
tools with npm:
170
171 
```sh
172 
npm install --global @openagentsinc/cli
173 
npm list --global @openagentsinc/cli --depth=0
174 
openagents --help
175 
```
176
177 
`@openagentsinc/cli@0.2.1` contains an older embedded `--version` value and
178 
reports `0.1.7`. Use the npm package listing to verify that release until a
179 
later CLI release corrects the embedded value. Follow
180 
[`OpenAgentsInc/openagents` issue 1](/OpenAgentsInc/openagents/issues/1) for the
181 
correction.
182
183 
Install the latest release again when you want to update:
184
185 
```sh
186 
npm install --global @openagentsinc/cli@latest
187 
```
188
189 
## Run one command with npx
190
191 
Use `npx` when you want to run one CLI command without installing the package
192 
globally:
193
194 
```sh
195 
npx --yes @openagentsinc/cli@latest --help
196 
npx --yes @openagentsinc/cli@latest repo list
197 
```
198
199 
Pin the package version when a script or qualification run must be
200 
reproducible:
201
202 
```sh
203 
npx --yes @openagentsinc/cli@0.2.1 --help
204 
```
205
206 
Place every `openagents` argument after the package name:
207
208 
```sh
209 
npx --yes @openagentsinc/cli@latest --profile staging auth status
210 
npx --yes @openagentsinc/cli@latest repo import OWNER/REPOSITORY
211 
```
212
213 
`npx` works for authentication, repository creation, imports, listing,
214 
inspection, and cloning. The CLI stores an approved login in the same
215 
operating-system credential store that a global installation uses.
216
217 
Do not run `auth setup-git` through `npx`. That command writes a persistent Git
218 
helper configuration that calls `openagents`, but the temporary `npx`
219 
executable disappears after the command. Install the CLI globally before you
220 
configure a local or global Git helper.
221
222 166 
## Sign in
223 167
224 168 
Start the browser-assisted device authorization flow:

@@ -247,14 +191,6 @@ Use `--headless` to force the resumable flow in an interactive terminal. Use

247 191 
when an agent needs structured output. The agent never receives your GitHub
248 192 
token or the issued OpenAgents token.
249 193
250 
The two-step flow also works without a global installation:
251
252 
```sh
253 
npx --yes @openagentsinc/cli@latest --json auth login
254 
# After approval:
255 
npx --yes @openagentsinc/cli@latest --json auth login --resume
256 
```
257
258 194 
The CLI stores the pending request in a private mode-`0600` local file. It
259 195 
removes the request after successful authorization or when it detects that the
260 196 
request expired.
test/openagents_web/docs_catalog_test.exs modified +20 -3

@@ -134,12 +134,29 @@ defmodule OpenAgentsWeb.DocsCatalogTest do

134 134
135 135 
  test "published CLI docs cover authentication, installation, imports, and API access" do
136 136 
    assert {:ok, install} = DocsCatalog.render("install-cli")
137 
    assert install.markdown =~ "npm install --global @openagentsinc/cli"
138 
    assert install.markdown =~ "npx --yes @openagentsinc/cli@latest"
139 137 
    assert install.markdown =~ "openagents auth login --resume"
140 138 
    assert install.markdown =~ "returns immediately"
141 139 
    assert install.markdown =~ "`OPENAGENTS_AGENT_TOKEN` is an internal agent-runtime credential"
142 
    assert install.markdown =~ "Do not run `auth setup-git` through `npx`"
140
141 
    # The installer links three names onto one binary, and the page must say all
142 
    # three: a reader who installed `openagents` and reads only about `oa` has no
143 
    # way to connect the two.
144 
    assert install.markdown =~ "`openagents`, `coder`, and `oa`"
145 
    assert install.markdown =~ "curl -fsSL https://openagents.com/install.sh | sh"
146
147 
    # The page must not send anyone to the npm package. It publishes a *different*
148 
    # program under the same `openagents` name, and having both on one PATH is not
149 
    # hypothetical: the 0.0.2 installer put the native binary ahead of the npm one
150 
    # and broke `git push` machine-wide, because only one of them implements
151 
    # `auth git-credential` correctly. A page that offers them as interchangeable
152 
    # installs of the same CLI is how someone ends up with both.
153 
    refute install.markdown =~ "npm install"
154 
    refute install.markdown =~ "npx"
155 
    refute install.markdown =~ "@openagentsinc/cli"
156
157 
    # The script is `#!/bin/sh`. Piping it to `bash` works, but telling people to
158 
    # is what the Alpine and BusyBox note exists to undo.
159 
    refute install.markdown =~ "install.sh | bash"
143 160
144 161 
    assert {:ok, import} = DocsCatalog.render("import-github")
145 162 
    assert import.markdown =~ "one-time copy"

This page updates live while a promote is in flight · changelog