Orca Cli
Drive Orca worktrees, terminals, automations, and in-editor browser actions through the official `orca` CLI instead of raw git or Playwright.
Overview
orca-cli is an agent skill most often used in Build (also Ship, Operate) that routes worktree, terminal, automation, and in-Orca browser tasks through the `orca` CLI instead of raw git, shell PTYs, or Playwright.
Install
npx skills add https://github.com/stablyai/orca --skill orca-cliWhat is this skill?
- Orchestrate Orca worktrees and refresh worktree comments at meaningful checkpoints
- Create, read, run, stop, and wait on Orca-managed shell terminals (non-agent PTYs)
- Create and manage scheduled Orca automations and list Orca-known repos
- Automate Orca's built-in browser (snapshot, click, fill, screenshot, tabs)
- Explicit boundary: use orchestration skill for terminal I/O to other AI agents, not orca-cli writes
Adoption & trust: 2.4k installs on skills.sh; 4.4k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are working inside Orca but your agent keeps using raw git, unmanaged shells, or external browser drivers and loses worktree context, automations, and the correct hand-off path to other agents.
Who is it for?
Solo builders who standardize on the Orca editor and want one CLI contract for worktrees, checkpoints, CI-like terminal runs, and light browser checks without leaving Orca's plane.
Skip if: Repos with no Orca app running, pure one-off git workflows outside Orca, or sending tasks or nudges to Claude/Gemini/Codex worker terminals—use orchestration for those writes.
When should I use this skill?
Task should go through Orca's control plane (worktrees, terminals, automations, browser) rather than direct git, shell PTYs, or ad hoc filesystem access; not when the terminal recipient is another AI agent.
What do I get? / Deliverables
Tasks run through Orca's APIs so worktrees stay annotated, terminals and automations stay managed, and agent-to-agent messaging is deferred to orchestration while shells and builds stay on orca-cli.
- Orca CLI commands executed for worktree, terminal, automation, or browser goals
- Updated worktree comment at checkpoints when applicable
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Coding agents running inside Orca worktrees need a first-class control plane for checkpoints and execution—canonical shelf is Build because that is where agent tooling and repo orchestration live. agent-tooling is the facet for skills that extend how agents interact with editors, terminals, and repo state rather than shipping a user-facing feature.
Where it fits
Refresh the worktree comment after each implemented milestone so Orca's UI reflects agent progress.
Start a test command in an Orca-managed terminal and wait for completion without spawning a detached local shell.
Inspect or stop a stuck long-running process Orca already tracks instead of guessing PIDs on the host.
Snapshot and click through an in-Orca browser flow for a quick UI smoke check before merge.
How it compares
Use instead of raw `git worktree`, ad hoc PTYs, or Playwright when Orca already owns the repo, terminals, and browser session.
Common Questions / FAQ
Who is orca-cli for?
Indie developers and small teams who run coding agents inside Orca and want predictable CLI commands for worktrees, terminals, automations, and browser steps aligned with Orca's model.
When should I use orca-cli?
During Build for worktree checkpoints and agent tooling; during Ship when driving build or test commands in Orca terminals; during Operate when reading or waiting on long-running Orca processes—always when the task touches Orca state, not generic git alone.
Is orca-cli safe to install?
Treat it like any skill that can drive shells and browser actions: review the Security Audits panel on this Prism page and scope Orca permissions before enabling network or filesystem-heavy automations.
SKILL.md
READMESKILL.md - Orca Cli
# Orca CLI Use this skill when the task should go through Orca's control plane rather than directly through `git`, shell PTYs, or ad hoc filesystem access. ## When To Use Use `orca` for: - worktree orchestration inside a running Orca app - updating the current worktree comment with meaningful progress checkpoints - reading Orca-managed terminals and sending input to non-agent terminals - stopping or waiting on Orca-managed terminals - creating and managing scheduled Orca automations - accessing repos known to Orca Do not use `orca` when plain shell tools are simpler and Orca state does not matter. Examples: - creating one Orca worktree per GitHub issue - updating the current worktree comment after a significant checkpoint, such as reproducing a bug, validating a fix, or handing off for review - finding the Claude Code terminal for a worktree and reading its status - checking which Orca worktrees have live terminal activity - creating a scheduled automation that runs a prompt against a known repo or worktree ## Preconditions - Prefer the public `orca` command first - Orca editor/runtime should already be running, or the agent should start it with `orca open` - Do not begin by inspecting Orca source files just to decide how to invoke the CLI. The first step is to check whether the installed `orca` command exists. - Do not assume a generic shell environment variable proves the agent is "inside Orca". For normal agent flows, the public CLI is the supported surface, but avoid wasting a round trip on probe-only checks when a direct Orca action would answer the question. First verify the public CLI is installed: ```bash command -v orca ``` Then use the public command: ```bash orca status --json ``` If the task is about Orca worktrees or Orca terminals, do this before any codebase exploration: ```bash command -v orca orca status --json ``` If the agent truly needs to confirm that the current directory is inside an Orca-managed worktree, use: ```bash orca worktree current --json ``` If `orca` is not on PATH, say so explicitly and stop or ask the user to install/register the CLI before continuing. ## Core Workflow 1. Confirm Orca runtime availability: ```bash orca status --json ``` If Orca is not running yet: ```bash orca open --json orca status --json ``` 2. Discover current Orca state: ```bash orca worktree ps --json orca terminal list --json ``` 3. Resolve a target worktree or terminal handle. 4. Act through Orca: - `worktree create/set/rm` - `automations list/show/create/edit/remove/run/runs` - `terminal read/send/wait/stop` 5. When the agent reaches a significant checkpoint in the current worktree, update the Orca worktree comment so the UI reflects the latest work-in-progress: ```bash orca worktree set --worktree active --comment "reproduced auth failure with aws sts; testing credential-chain fix" --json ``` Why: the worktree comment is Orca's lightweight, agent-writable status field. Keeping it current gives the user an at-a-glance summary of what the agent most re