mirror of
https://github.com/stablyai/orca.git
synced 2026-09-29 16:02:50 +00:00
docs(linux): say which package to install and how updates arrive
Closes #5188. Closes #10987. The install guide's entire Linux section was "AppImage and `.deb` builds are available. See the Releases page for details." It named two of the three published packages, gave no basis for choosing between them, and said nothing about updating -- which is the one thing that actually differs between them. Separately, nothing human-facing said the Linux CLI is `orca-ide`; only skills/orca-cli/SKILL.md carried it, which agents read and humans do not. Install page now picks the package by update behaviour: the AppImage self-updates, deb/rpm report the new version and hand over the install command, and a repackaged build is not offered a download it cannot apply. Records that Orca never escalates privileges for the package install, and points at #18086 for the signed repo as planned, not shipped. Adds .rpm to the download list. Release CI builds it (release-cut.yml: `--linux AppImage deb rpm`) and verify-release-required-assets.mjs requires the artifact, so omitting it was just wrong. The CLI command name is now stated where humans hit it -- the CLI reference and overview -- with the GNOME Orca collision as the reason, plus the two places bare `orca` does work: inside Orca-managed terminals (PTY PATH shim) and on a packaged `orca serve` host (the ~/.local/bin dispatcher). The headless guide gains the same note, which is what makes its `orca skills install` lines correct rather than a typo.
This commit is contained in:
Neil
@@ -341,6 +341,15 @@ the command:
|
||||
This disables a security boundary. Prefer a dedicated unprivileged service
|
||||
user, especially when the listener is reachable beyond localhost.
|
||||
|
||||
The Linux CLI is named `orca-ide`, not `orca`, so it never shadows the GNOME
|
||||
Orca screen reader at `/usr/bin/orca`. The `.deb` and `.rpm` packages put
|
||||
`orca-ide` on `PATH` themselves at install time; with the AppImage it arrives
|
||||
as `~/.local/bin/orca-ide` when the CLI is registered. On top of that, a
|
||||
packaged `orca serve` start also writes a bare `orca` into `~/.local/bin` that
|
||||
execs the same launcher — that is why the skills commands below can be typed as
|
||||
`orca`. It is skipped when a file Orca does not own already holds that name, so
|
||||
a host that really does run the screen reader keeps its own `orca`.
|
||||
|
||||
## Pairing troubleshooting
|
||||
|
||||
- A pairing offer is a capability containing a device credential and E2EE
|
||||
|
||||
@@ -14,7 +14,7 @@ import { Callout } from '@/components/docs/prose'
|
||||
|
||||
The Orca CLI is the `orca` command-line interface for scripting a running Orca editor from any shell. Use it to create and inspect worktrees, drive agent terminals, open files and diffs, automate the built-in browser, run scheduled automations, share HTML/Markdown artifacts, and control Orca-native tools from scripts or AI agents.
|
||||
|
||||
It ships with the desktop app; register it under [Settings → General → Orca CLI](/docs/settings).
|
||||
It ships with the desktop app; register it under [Settings → General → Orca CLI](/docs/settings). On Linux the command is `orca-ide`, because GNOME Orca's screen reader already owns `/usr/bin/orca` — see [Install → Linux](/docs/install#linux).
|
||||
|
||||
Agents can install the matching Orca CLI skill with:
|
||||
|
||||
|
||||
@@ -16,6 +16,13 @@ command -v orca
|
||||
orca status --json
|
||||
```
|
||||
|
||||
<Callout title="On Linux the command is orca-ide">
|
||||
GNOME Orca, the screen reader that ships with most GNOME desktops, already owns `/usr/bin/orca`,
|
||||
so Orca's Linux CLI installs as `orca-ide` instead. Use `orca-ide` in your own shell; bare `orca`
|
||||
works inside Orca's own terminals, and on a headless `orca serve` host. This page writes `orca`
|
||||
throughout — substitute `orca-ide` on Linux. See [Install → Linux](/docs/install#linux).
|
||||
</Callout>
|
||||
|
||||
If Orca is not already running:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -32,7 +32,8 @@ import { Callout } from '@/components/docs/prose'
|
||||
<li>
|
||||
**Linux:**
|
||||
[AppImage](https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage) ·
|
||||
[.deb](https://github.com/stablyai/orca/releases)
|
||||
[.deb](https://github.com/stablyai/orca/releases) ·
|
||||
[.rpm](https://github.com/stablyai/orca/releases) — see [Linux](#linux) for which to pick
|
||||
</li>
|
||||
<li>Older versions: [GitHub Releases](https://github.com/stablyai/orca/releases).</li>
|
||||
</ul>
|
||||
@@ -59,6 +60,8 @@ On first launch Orca will:
|
||||
|
||||
Orca auto-updates by default, tracking the **stable** channel. Stable releases are vetted; **RC (release candidate)** builds ship new features first, often daily.
|
||||
|
||||
On Linux, whether Orca can apply an update itself depends on which package you installed. See [Linux](#linux) before you pick one.
|
||||
|
||||
There is no permanent in-app opt-in for the RC channel. Modifier clicks on **Check for Updates** ([Settings → General → Updates](/docs/settings), or the app / Help menu):
|
||||
|
||||
| Modifier | Effect |
|
||||
@@ -87,4 +90,47 @@ The default shell can be set to PowerShell or CMD under [Settings → Terminal](
|
||||
|
||||
### Linux
|
||||
|
||||
AppImage and `.deb` builds are available. See the Releases page for details.
|
||||
Every release publishes three Linux packages — an **AppImage**, a **`.deb`**, and an **`.rpm`**. They contain the same app. What differs is how updates reach you, so pick on that.
|
||||
|
||||
| Package | Pick it when | Updates |
|
||||
| ------------ | --------------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| **AppImage** | You want Orca to update itself, like on macOS and Windows | Orca downloads and applies the update in place |
|
||||
| **`.deb`** | You manage software with `apt` on Debian or Ubuntu | Orca tells you a version is out and hands you the install command |
|
||||
| **`.rpm`** | You manage software with `dnf`, `yum`, or `zypper` | Same as `.deb` |
|
||||
|
||||
The AppImage has a stable download link and needs `chmod +x` before its first run. The `.deb` and `.rpm` filenames carry the version and architecture (`orca-ide_<version>_<arch>.deb`, `orca-ide-<version>.<arch>.rpm`), so take them from the [Releases page](https://github.com/stablyai/orca/releases) rather than a fixed URL.
|
||||
|
||||
#### How updating works
|
||||
|
||||
**The AppImage self-updates.** Choose it if you want automatic updates. Orca checks for a new release, you click **Update**, and it replaces the AppImage in place — the same flow as macOS and Windows.
|
||||
|
||||
**The `.deb` and `.rpm` do not self-update.** Orca still notices the new version and downloads the package, then gives you a **Copy Install Command** button. The command names the file it just downloaded:
|
||||
|
||||
```
|
||||
sudo apt install -- /home/you/.cache/orca-updater/pending/orca-ide_1.4.194_amd64.deb
|
||||
```
|
||||
|
||||
Run it in your own terminal, then quit and reopen Orca. Orca deliberately never escalates privileges to do this for you: installing a system package needs root, `orca serve` runs as an unprivileged user, and a headless machine has no authentication agent to prompt. VS Code and Signal make the same call on `.deb`.
|
||||
|
||||
**A distro-managed build is left alone.** If you are running a repackaged Orca — an AUR build, a Nix derivation, a container image that unpacks the `.deb` — Orca sees that no matching package manager owns this install and stops offering a download it could never apply. It still reports that a new version exists, so you can update the way you normally would.
|
||||
|
||||
<Callout title="Planned: a signed apt/yum repository">
|
||||
[#18086](https://github.com/stablyai/orca/issues/18086) tracks publishing a signed repository so
|
||||
your OS package manager owns Orca updates the way it owns everything else. It does not exist yet —
|
||||
today, `.deb` and `.rpm` updates are the manual step described above.
|
||||
</Callout>
|
||||
|
||||
#### The CLI command is `orca-ide`
|
||||
|
||||
On Linux the [Orca CLI](/docs/cli/reference) installs as **`orca-ide`**, not `orca`. GNOME Orca — the screen reader that ships by default on Ubuntu and other GNOME desktops — already owns `/usr/bin/orca`, and Orca will not shadow it. The `.deb` and `.rpm` packages are named `orca-ide` for the same reason.
|
||||
|
||||
- The `.deb` and `.rpm` put `orca-ide` on your `PATH` at install time, as `/usr/bin/orca-ide`.
|
||||
- With the AppImage, register the CLI from [Settings → General → Orca CLI](/docs/settings). That installs `~/.local/bin/orca-ide`.
|
||||
- Inside Orca's own terminals, bare `orca` works. Orca puts a shim on the `PATH` of the terminals it manages, so agents and scripts running there use the same command as on macOS and Windows.
|
||||
- On a headless [`orca serve`](/docs/remote-servers) host, Orca also installs a bare `orca` into `~/.local/bin`, unless a file it does not own already holds that name.
|
||||
|
||||
So: `orca-ide` in your own shell, `orca` inside Orca. If you want the short name everywhere and you do not use the screen reader, link it yourself:
|
||||
|
||||
```
|
||||
ln -s "$(command -v orca-ide)" ~/.local/bin/orca
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user