orca/skill-guides/orca-cli/references/plugins.md

Plugin commands

Use these to make, check, load, install and manage Orca plugins (themes, terminal themes, icon themes, syntaxes, language packs, custom editors, panels, TSX component panels). All commands take --json; branch on error.code, not on wording.

ORCA plugin create <dir> --template <theme|terminal-theme|icon-theme|syntax|language-pack|editor|panel|components|worker-panel> [--id <id>] [--name <name>] --json
ORCA plugin types <dir> --json
ORCA plugin validate <dir|orca-plugin.json|orca-catalog.json> --json
ORCA plugin inspect <dir> --json
ORCA plugin release-entry <dir> --json
ORCA plugin test [dir] --json
ORCA plugin check [dir] --json
ORCA plugin dev watch <dir> [--check] [--shot <out-dir> [--shot-panel <id>]] [--approve <fingerprint>] --json
ORCA plugin dev load <dir> [--approve <fingerprint>] --json
ORCA plugin dev reload [<dir>] [--approve <fingerprint>] --json
ORCA plugin dev emit <dir|plugin-key> <event> [--data <json>] --json
ORCA plugin dev request <dir|plugin-key> <name> [--data <json>] [--panel <id>] [--timeout-ms <ms>] --json
ORCA plugin dev unload <dir|plugin-key> --json
ORCA plugin list --json
ORCA plugin logs <plugin-key> --json
ORCA plugin enable <plugin-key> [--approve <fingerprint>] --json
ORCA plugin disable <plugin-key> --json
ORCA plugin system on|off --json
ORCA plugin restart <plugin-key> --json
ORCA plugin open <plugin-key> [--panel <id> | --editor <file>] --json
ORCA plugin shot <plugin-key> [--panel <id>] [--theme light|dark] [--width <px>] [--act '<json>'] [--out <file.png>] --json
ORCA plugin shot <dir> --scenario <name> [--panel <id>] [--theme light|dark] [--width <px>] [--out <file.png>] --json
ORCA plugin install <publisher.id|owner/repo[@ref]|git-url|page-url|dir> [--ref <ref>] [--catalog <name>] [--approve <fingerprint>] --json
ORCA plugin update <plugin-key|--all> [--approve <fingerprint>] --json
ORCA plugin uninstall <plugin-key> --json
ORCA plugin catalog list --json
ORCA plugin catalog add <owner/repo|git-url> [--ref <branch>] [--approve <fingerprint>] --json
ORCA plugin catalog rm <id|name|url> --json   # alias: catalog remove

Exit codes: 0 ok, 1 error, 2 plugin_invalid, 3 approval_required or approval_stale.

Make and load a plugin

1. plugin create into a new folder. Leave out --publisher: Orca names the publisher after the repository owner (local for a folder); an orca- id prefix is reserved. components is a TSX panel with no build step; .ts/.tsx files load as written, importing only orca and relative files. plugin types <dir> (also run by plugin dev load) writes the typings to .orca/types/, which the plugin's tsconfig.json extends.
2. Edit the files. Field rules: docs/reference/plugin-manifest.md, plugin-themes.md, plugin-theme-tokens.md, plugin-syntax.md and plugin-authoring.md in the Orca repository.
3. plugin validate until it passes. It is offline and never runs plugin code. For components panels, plugin check also renders each panel once in Node and reports runtime errors with file:line, and plugin test runs the plugin's *.test.ts(x) files with orca/testing (see docs/reference/plugin-declarative-ui.md, "Testing"). Both run the plugin's code unsandboxed on this machine: use them only on code you trust.
4. plugin dev load <dir> adds the folder to Settings → Plugins → Development folders on the Orca host and loads it. Orca reloads it, and restarts its worker, when its files change; run plugin dev reload <dir> if a change was missed. plugin restart <plugin-key> stops a worker so its next command or event reruns its startup code. plugin logs shows what a worker printed and a panel's or editor's console errors, warnings and uncaught exceptions as [frame] <file>:<line> <message>. plugin dev inspect <plugin-key> opens DevTools windows for its open frames; run it only when the user asks. plugin dev watch <dir> --json does the load, then stays running and prints one JSON object per line (type: loaded, log, reloaded, status, approval, check, shot, shot_skipped, warning, disconnected, unloaded) as logs arrive and saves reload it; run it in a background terminal and read its output. Ctrl-C unloads the folder it loaded. plugin dev emit <dir|plugin-key> <event> --data '<json>' fires a test event at a development plugin's worker (if it lists the event in contributes.events) and its open panels that subscribed with orca.on; the payload is checked against the event's schema. Handler errors show in plugin logs and the watch. plugin dev request <dir|plugin-key> <name> --data '<json>' calls the worker's orca.panels.handle(name) handler as a panel's plugin.request would and prints { pluginKey, name, result }; a handler failure is plugin_request_failed with the worker's code in error.data.requestCode.
5. See what you built: plugin shot <plugin-key> --json writes a PNG of a panel exactly as Orca draws it (default .orca/shots/<plugin-key>-<panel>.png, in the plugin folder when run inside one; --width applies to that capture only, and --theme too but only while Orca's window is hidden or minimized, else themeApplied: false with a themeReason) and lists the errors the panel showed or logged; read the image file. A components panel's shot also waits for its host calls (plugin.request) to answer, at most 3s; pendingRequests counts any still out. --act '[{"type":{"label":"New task"},"text":"Ship"},{"press":{"text":"Add"}}]' first drives a components panel with the test kit's verbs (press, type, select, toggle, slide, Table sort/selectRows/activateRow/loadMore, Tree expand/collapse/selectItem/activateItem; at most 20) and reports actions: [{ ok, error? }]; it needs Orca's window hidden or minimized and never counts as a user gesture. Afterwards the panel's atoms are put back (restored); worker-side effects stay. plugin shot <dir> --scenario <name> shoots one <entry>.check.ts scenario instead: it renders it here like plugin check (unsandboxed, the worker on a stand-in host), and Orca draws that tree apart from the plugin, so the live panel, storage and worker are never touched. It returns replay: true and scenario; a still frame (images placeholder, no --act), local only, window hidden or minimized; an unknown name lists the scenarios. plugin dev watch <dir> --shot <out-dir> opens one panel once (the first, or --shot-panel <id>) and captures it after every reload while it stays on screen; when the user shows something else it skips (shot_skipped) and never switches back. plugin open <plugin-key> shows a panel to the user (--editor <file> opens a file in its custom editor). Both need the desktop app with a workspace showing and never raise the window.
6. plugin dev unload <dir> when done.

Paths are on the machine that runs Orca. With --environment <server>, pass an absolute path on that server. From an SSH or WSL shell that forwards orca to another machine, the authoring and dev commands refuse; work on the Orca host instead.

plugin_system_disabled means plugins are off on that host. Ask the user to click "Turn on plugins" in Settings → Plugins, or on a host with no window (orca serve) to run plugin system on with the same --environment. It approves nothing; only plugins approved earlier start.

Install, update and remove

plugin install accepts:

• a catalog id such as acme.dusk (from Orca's official, the community or an added catalog; --catalog picks one when several list it),
• owner/repo or owner/repo@v1.2.0 on GitHub,
• any https:// or ssh:// Git URL or git@host:owner/repo.git, with #ref for a version,
• a GitHub or GitLab release, tag or tree page URL (.../releases/tag/v1.2.0, .../-/tree/main),
• a plugin folder (a path on the Orca host).

With no version, Orca installs the newest version tag (vX.Y.Z), else the default branch, and always pins the exact commit. The result names the version, commit, publisher and repository.

ORCA plugin install acme/dusk-theme --json                     # content only: installs and enables
ORCA plugin install acme/notes-panel@v1.4.0 --json             # code: exits 3 with approval_required
ORCA plugin install acme/notes-panel@v1.4.0 --approve ap1-… --json
ORCA plugin update --all --json
ORCA plugin uninstall acme.notes-panel --json

plugin update moves catalog installs to the release their catalog offers now, Git installs from a version tag to the newest version tag and from a branch to its newest commit; a commit pin stays. An update from the same repository that asks for no new access keeps its approval. One that adds capabilities, a higher execution level, commands, shortcuts or panels, or that comes from another repository (even a theme or language pack), fails with approval_required listing exactly what changes; the running version keeps working until it is approved. --all updates everything it can and exits 3 with one --approve command per plugin still waiting.

plugin uninstall and plugin catalog rm never need approval. plugin catalog add always does: a catalog decides which repositories Orca installs and auto-updates from, so the first run returns approval_required with a cat1-… fingerprint for that exact URL and branch.

Private repositories

Git runs on the Orca host (the --environment server when given) with that machine's own Git credentials and never prompts. Nothing to pass to orca; set up Git there once:

• HTTPS on GitHub: gh auth login then gh auth setup-git. GitLab: glab auth login. Elsewhere: any credential helper (Git Credential Manager, osxkeychain, libsecret).
• SSH: a key in ssh-agent that the server accepts, with its host key in known_hosts, then install with git@github.com:owner/repo.git.

ORCA plugin install git@github.com:acme/private-panel.git --json
ORCA plugin install https://github.com/acme/private-panel --json

If that host's Git cannot read the repository, the command fails with git_auth_failed. error.data has executionHost, transport (https or ssh), gitHost and nextSteps for that host. Never put a token or password in the URL; Orca refuses it.

Approval

• Content-only plugins (themes, terminal themes, icon themes, syntaxes, language packs) load, install and enable without approval.
• Anything that runs code or acts in Orca (panels, editors, commands, shortcuts, workers, capabilities) fails with approval_required (exit 3). error.message and error.data say exactly what it would be granted, why approval is needed, and error.data.command, the same command with --approve <fingerprint>.
• The fingerprint is bound to that plugin, version, files and access. A different plugin, version, set of files, or more access gets approval_stale with the new grants and a new fingerprint.
• Approving grants real access on the user's machine or server. Ask your user before re-running with --approve unless they already asked for exactly this plugin and this access. Never pass a fingerprint you did not get from Orca for this exact command. Each approval is written to the plugin audit log as approved via CLI.
• install and update decide approval before writing anything: without it nothing is installed and the running version is untouched. For anything not from Orca's official catalog the message also names the publisher (the repository owner) and the source repository; show that to your user, since Orca has not checked that code.
• Without approval a development folder stays loaded but nothing in it runs.
• For an approved development folder, later code edits run without asking again; new capabilities, a higher execution level, or changed commands and shortcuts need a new approval.
• disable, restart, uninstall, dev unload and catalog rm never need approval.

Publish

There is no publish command. Use Git and gh with the user's own credentials:

1. plugin validate . must pass, and the work must be committed and pushed to the GitHub repository that will own it (its owner becomes the publisher).
2. Set version in orca-plugin.json, commit, then tag that commit v<version> and push the tag: git tag -a v1.2.0 -m v1.2.0 && git push origin v1.2.0.
3. Add the orca-plugin topic to the repository: gh repo edit <owner>/<repo> --add-topic orca-plugin.
4. Check the listing status at https://www.onorca.dev/plugins/<owner>/<repo>.

For a catalog (orca-catalog.json), commit the plugin and run plugin release-entry <dir>: it prints the releases entry for HEAD (and the source.path for a plugin in a subdirectory) to paste into the catalog, newest first.

Publishing is public and acts under the user's GitHub identity; do it only when the user asked to publish.