Skip to content

Put the orca CLI on PATH at install time for headless hosts - #5842

Merged
Jinwoo-H merged 1 commit into
mainfrom
Jinwoo-H/cli-on-path-headless
Jun 19, 2026
Merged

Jinwoo-H merged 1 commit into
mainfrom
Jinwoo-H/cli-on-path-headless

Conversation

@Jinwoo-H

@Jinwoo-H Jinwoo-H commented Jun 19, 2026 •

Copy link
Copy Markdown
Contributor

What & why

The bundled orca / orca-ide CLI only lands on PATH when a user triggers the in-app Install CLI action (CliInstaller, via the cli:install IPC). That requires opening the desktop GUI — which a headless server can never do. So on the exact hosts where you'd want orca serve (VMs, cloud boxes), the CLI was unreachable from the shell after install.

This registers the CLI at package-install time, through the distribution channels we control, so orca serve works on a headless host with no GUI step.

How

  • Homebrew cask (Casks/orca.rb + Casks/orca@rc.rb): add a binary stanza pointing at the bundled shim (Orca.app/Contents/Resources/bin/orca). brew install --cask orca now symlinks orca into Homebrew's already-on-PATH bin dir. The cask is the source of truth synced to the tap by homebrew-bump.yml, so this propagates automatically on the next release.
  • deb/rpm (config/electron-builder.config.cjs + resources/linux/packaging/*.sh): add afterInstall / afterRemove fpm scripts that symlink the bundled …/resources/bin/orca-ide to /usr/bin/orca-ide on install and remove it on uninstall. The deb already declares the xvfb dependency orca serve needs to render browser panes headlessly, so apt install now yields a working headless serve in one step.

The shims resolve the real app by walking up symlinks, so a PATH symlink works correctly. The install dir is discovered (not hardcoded /opt/Orca) because electron-builder's directory name can vary.

Safety guards

  • after-install never clobbers an unrelated /usr/bin/orca-ide (e.g. Ubuntu's GNOME Orca) — it only writes when the path is absent or already a symlink.
  • after-remove only deletes a symlink that still points into an Orca install dir, so it won't remove something another package/user owns.

Verification

Ran the postinstall/postremove logic against mock install trees in real Debian (debian:stable-slim) and Fedora (fedora:latest) containers:

  • ✅ symlink created → orca-ide resolves on PATH, runs, forwards args (orca-ide serve --foo)
  • ✅ does not clobber a pre-existing real /usr/bin/orca-ide
  • ✅ uninstall removes our symlink
  • ✅ uninstall leaves an unrelated symlink alone

Also confirmed both casks pass ruby -c, the builder config loads, and electron-builder 26.8.1 supports afterInstall/afterRemove (they map to fpm --after-install/--after-remove).

Scope / not included

  • AppImage has no install hook, so it can't auto-register the CLI — documented as a manual ln -s elsewhere; out of scope here.
  • The AUR package is community-owned and GUI-only today; making it headless-capable is a separate upstream conversation.

Follow-ups (not blocking)

  • macOS cask binary from an auto_updates app: confirm the symlink survives an in-app updater swap (path inside the .app is stable, so it should).
  • Headless secrets currently fall back to plaintext without an OS keychain — worth closing before promoting headless serve as secure-by-default.

Made with Orca 🐋


Open in Stage

The bundled orca/orca-ide CLI is only registered on PATH by the in-app
'Install CLI' action (CliInstaller via the cli:install IPC), which can never
run on a headless server. As a result, 'orca serve' was unreachable from the
shell on exactly the hosts that need it.

Register the CLI at install time instead, through the channels we control:

- Homebrew cask (orca + orca@rc): add a 'binary' stanza pointing at the
  bundled shim so 'brew install --cask orca' symlinks 'orca' into Homebrew's
  on-PATH bin. No GUI needed.
- deb/rpm: add after-install/after-remove fpm scripts that symlink the bundled
  orca-ide shim to /usr/bin/orca-ide on install and remove it on uninstall.
  Guards avoid clobbering an unrelated /usr/bin/orca-ide (e.g. GNOME Orca) and
  only remove a symlink that still points into an Orca install dir.

The shims resolve the real app by walking symlinks, so a PATH symlink works.
The deb already declares the xvfb dependency 'orca serve' needs for browser
panes, so apt/dnf installs now give a working headless serve in one step.

Verified the postinstall/postremove logic in Debian and Fedora containers:
symlink created + CLI invokable via PATH, args forwarded, both clobber guards
hold, and uninstall cleans up only our own symlink.

Co-authored-by: Orca <help@stably.ai>
@ghost

ghost commented Jun 19, 2026

Copy link
Copy Markdown

Ready to review this PR? Stage has broken it down into 3 individual chapters for you:

Title
1 Add CLI symlink to Homebrew casks
2 Create Linux post-install and post-remove scripts
3 Configure Linux package builders to use scripts
Open in Stage

Chapters generated by Stage for commit ce8ec83 on Jun 19, 2026 9:18pm UTC.

@coderabbitai

coderabbitai Bot commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The pull request adds PATH-accessible CLI registration for the bundled orca executable across macOS and Linux install paths. On macOS, a binary stanza is added to both the stable (orca.rb) and release-candidate (orca@rc.rb) Homebrew casks, pointing to Orca.app/Contents/Resources/bin/orca. On Linux, electron-builder.config.cjs is updated to reference new afterInstall and afterRemove lifecycle scripts for both deb and rpm targets; the deb target also gains additional runtime dependencies. Two new shell scripts—after-install.sh and after-remove.sh—manage creation and cleanup of a /usr/bin/orca-ide symlink based on the presence of an executable shim under /opt/Orca or /opt/orca-ide.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: registering the orca CLI on PATH at install time specifically for headless hosts.
Description check ✅ Passed The description comprehensively covers the change rationale, implementation details across platforms, safety measures, and verification performed.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 4652798f-8060-4fd4-812b-bcb078961236

📥 Commits

Reviewing files that changed from the base of the PR and between f92f12e and ce8ec83.

📒 Files selected for processing (5)
  • Casks/orca.rb
  • Casks/orca@rc.rb
  • config/electron-builder.config.cjs
  • resources/linux/packaging/after-install.sh
  • resources/linux/packaging/after-remove.sh

Comment on lines +18 to +19
if [ ! -e "$link" ] || [ -L "$link" ]; then
ln -sf "$shim" "$link"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Avoid overwriting unrelated existing symlinks at /usr/bin/orca-ide.

Current logic force-replaces any symlink target, so an unrelated symlink at the same path gets clobbered. That contradicts the script’s own safety contract.

Suggested fix
-    if [ ! -e "$link" ] || [ -L "$link" ]; then
-      ln -sf "$shim" "$link"
-    fi
+    if [ ! -e "$link" ]; then
+      ln -s "$shim" "$link"
+    elif [ -L "$link" ]; then
+      current_target="$(readlink "$link" || true)"
+      case "$current_target" in
+        /opt/Orca/*|/opt/orca-ide/*|/opt/orca/*)
+          ln -sf "$shim" "$link"
+          ;;
+      esac
+    fi
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
if [ ! -e "$link" ] || [ -L "$link" ]; then
ln -sf "$shim" "$link"
if [ ! -e "$link" ]; then
ln -s "$shim" "$link"
elif [ -L "$link" ]; then
current_target="$(readlink "$link" || true)"
case "$current_target" in
/opt/Orca/*|/opt/orca-ide/*|/opt/orca/*)
ln -sf "$shim" "$link"
;;
esac
fi

@Jinwoo-H
Jinwoo-H merged commit c9460ed into main Jun 19, 2026
7 checks passed
@Jinwoo-H
Jinwoo-H deleted the Jinwoo-H/cli-on-path-headless branch June 19, 2026 22:46
@coderabbitai coderabbitai Bot mentioned this pull request Jul 13, 2026
5 tasks
@AmethystLiang AmethystLiang added the orca-remote-server Remote Orca Server / orca serve / paired remote runtime label Jul 22, 2026
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

orca-remote-server Remote Orca Server / orca serve / paired remote runtime

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants