# 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. ```text ORCA plugin create --template [--id ] [--name ] --json ORCA plugin types --json ORCA plugin validate --json ORCA plugin inspect --json ORCA plugin release-entry --json ORCA plugin test [dir] --json ORCA plugin check [dir] --json ORCA plugin dev watch [--check] [--shot [--shot-panel ]] [--approve ] --json ORCA plugin dev load [--approve ] --json ORCA plugin dev reload [] [--approve ] --json ORCA plugin dev emit [--data ] --json ORCA plugin dev request [--data ] [--panel ] [--timeout-ms ] --json ORCA plugin dev unload --json ORCA plugin list --json ORCA plugin logs --json ORCA plugin enable [--approve ] --json ORCA plugin disable --json ORCA plugin system on|off --json ORCA plugin restart --json ORCA plugin open [--panel | --editor ] --json ORCA plugin shot [--panel ] [--theme light|dark] [--width ] [--act ''] [--out ] --json ORCA plugin shot --scenario [--panel ] [--theme light|dark] [--width ] [--out ] --json ORCA plugin install [--ref ] [--catalog ] [--approve ] --json ORCA plugin update [--approve ] --json ORCA plugin uninstall --json ORCA plugin catalog list --json ORCA plugin catalog add [--ref ] [--approve ] --json ORCA plugin catalog rm --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 ` (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 ` 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 ` if a change was missed. `plugin restart ` 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] : `. `plugin dev inspect ` opens DevTools windows for its open frames; run it only when the user asks. `plugin dev watch --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 --data ''` 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 --data ''` 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 --json` writes a PNG of a panel exactly as Orca draws it (default `.orca/shots/-.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 --scenario ` shoots one `.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 --shot ` opens one panel once (the first, or `--shot-panel `) 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 ` shows a panel to the user (`--editor ` 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 ` when done. Paths are on the machine that runs Orca. With `--environment `, 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. ```text 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`. ```text 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 `. - 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` 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 / --add-topic orca-plugin`. 4. Check the listing status at `https://www.onorca.dev/plugins//`. For a catalog (`orca-catalog.json`), commit the plugin and run `plugin release-entry `: 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.