The orbital command

Use the orbital command to run Orbital’s server, open it in a window, validate and migrate workflows, start runs, change settings and install the bundled skills. Run it with no arguments to print its help:

orbital

Every subcommand takes --version, which prints the version the command is running and exits with 0. orbital --version does the same.

A usage error, such as an unknown flag or a missing required flag, prints the problem and the help, and exits with 2.

Install the command from the desktop app

The macOS app carries the orbital command. To use it in a terminal, do one of these:

• Open Settings > Command line and skills and choose Install.
• Choose Orbital > Install Command Line Tool.

Both link /usr/local/bin/orbital to the command inside the app. The app asks for an administrator password only when that folder needs one. After the app updates, the command runs the new release without being installed again.

orbital serve

Runs the server and the browser app on one port.

orbital serve [--bind <address>] [--port <port>] [--open | --no-open]

It prints its address and opens it in your browser. It reads nothing from the directory you start it in.

Flag	What it does	Default
--bind <address>	address to bind	127.0.0.1
--port <port>	port to bind (default 42121, or “port” in the config file; 0 takes a free one)	42121, or port in ~/.orbital/config.json
--open	open the browser once the server is bound (default)	On
--no-open	leave the browser closed, as setting ORBITAL_NO_OPEN does	Off
--version	print the version this command is running and exit

A server whose output is redirected never opens a browser. The address it opens is always the loopback one, whatever --bind says.

The API of orbital serve has no secret. When you bind it to a network address, protecting that network is up to you. HTTP API describes which requests the server refuses.

Example:

orbital serve --port 0 --no-open

Exit codes:

Code	Meaning
0	The server stopped.
1	The server could not start. For example, the port is taken or run-history.db cannot be opened. The message says why.
2	Usage error.

When the port is taken, the message suggests --port <port> or the port key in ~/.orbital/config.json. When an Orbital server whose process is alive already runs on the same home, serve refuses before it recovers any run and names that server’s URL and process. A record a crashed server left does not block.

orbital app

Opens Orbital in a window. When the home already has a running server, such as orbital serve, the window opens on that server; otherwise it runs its own.

orbital app [--bind <address>] [--port <port>]

Closing the window stops a server the window started. A server it opened on keeps running. If the server the home records answers as another home’s, the window refuses to open and says so; --bind and --port apply only when the window starts the server.

The window makes a new secret at each start. Its server refuses any request without that secret, so only the window, and scripts that read the secret from ~/.orbital/server.json, can use it. The first start downloads the Electron runtime once, about 110 MB.

Flag	What it does	Default
--bind <address>	address the window’s server binds	127.0.0.1
--port <port>	port the window’s server binds (default: a free one)	A free port
--version	print the version this command is running and exit

Example:

orbital app

Exit codes:

Code	Meaning
0	The window closed normally.
1	The window could not open. The message says why and nothing is left running. orbital serve still works in a browser.
2	Usage error.

Otherwise the command exits with the code the window’s process exited with.

orbital validate

Checks a workflow without running it.

orbital validate [workflow]

It starts neither the server nor an agent.

The argument is a workflow name or a path. A name is looked up the way the server looks it up, with the folder you run the command from as the project folder. With no argument, the command checks the default workflow set in Settings > General.

A valid workflow prints Workflow <path> is valid. Each warning is printed first, on its own line, starting with warning:.

Flag	What it does	Default
[workflow]	workflow name or path	The default workflow
--version	print the version this command is running and exit

Examples:

orbital validate implement-ticket
orbital validate /absolute/path/to/workflow.toml

Exit codes:

Code	Meaning
0	The workflow is valid. Warnings do not change this.
1	The workflow was not found or is not valid. The message names the problem.
2	Usage error.

orbital migrate

Converts workflows written in DOT, the format before version 3, into TOML workflows.

orbital migrate [paths...] [--dry-run]

Each path is a DOT workflow file or a folder of them. With no path, the command converts the DOT workflows in the .orbital folder of the repository you run it from and in your home library, ~/.orbital/workflows. It starts neither the server nor an agent.

It writes each .toml file beside its .dot file and leaves the .dot file where it is, so delete the DOT file once the TOML workflow works for you. A workflow a file imports converts with it, and the import then names the .toml file. A file that already has a .toml file beside it is left alone.

Version 3 has no place for some DOT settings, such as tool limits. The command drops each one and prints a note: line under the file it wrote, naming the step. A step that limited its tools now has every tool, so say in its prompt what it must not change. A file the command cannot convert is printed with the step and the reason, and nothing is written for it.

The Convert to TOML button on the Workflows page does the same for the project’s folders and your home library. Orbital converts your saved custom workflows and your edits to built-in workflows by itself when it starts.

Flag	What it does	Default
[paths...]	DOT workflow files or folders to convert	The repository’s .orbital folder and ~/.orbital/workflows
--dry-run	print what would be converted without writing anything
--version	print the version this command is running and exit

Examples:

orbital migrate --dry-run
orbital migrate
orbital migrate ~/.orbital/workflows/review.dot

Exit codes:

Code	Meaning
0	Every DOT workflow found was converted, or none needed converting.
1	A file could not be converted, or a named path does not exist. The message names the file and the step.
2	Usage error.

orbital run start

Queues a run on the server running on this machine, the desktop app’s or orbital serve’s.

orbital run start --project <id> [--workflow <name>] [--input <name=value>]... [--goal <text>] [--title <text>] [--harness <name>] [--server <url>]

It prints the run’s id and then the address of its page.

The command reads the server’s address and secret from ~/.orbital/server.json, so it works with the desktop app with no extra flags. The run queues like any other run. It starts when a slot is free, under the cap in Settings > General.

Flag	What it does	Default
--project <id>	project the run works in (GET /api/projects lists them)	Required
--workflow <name>	workflow to run (default: the project’s default workflow)	The project’s default workflow
--input <name=value>	value for one of the workflow’s inputs; repeat for more	None
--goal <text>	goal for the run (default: the title, else the first input)	The title, else the first input
--title <text>	title the run is listed under, instead of a generated one	A generated title
--harness <name>	harness to run with: claude, codex, opencode, pi or another registered harness	The workflow’s choice
--server <url>	server to start the run on, instead of the one ~/.orbital/server.json names; ORBITAL_URL does the same	The server ~/.orbital/server.json names
--version	print the version this command is running and exit

A run needs a goal. Without --goal, --title or an --input, the command refuses.

For a server on another host, give its address with --server or ORBITAL_URL, and its secret with ORBITAL_TOKEN. The secret in ~/.orbital/server.json is never sent to a server that the file does not name.

Example:

orbital run start --workflow implement-ticket --project proj_r3tQMqBPBB5p \
  --input ticket_url=https://linear.app/acme/issue/IE-3770 --title "Pay invoices from the portal"

It prints:

2026-09-24-npn6fk
http://127.0.0.1:52011/runs/2026-09-24-npn6fk/workflow

Exit codes:

Code	Meaning
0	The run was queued.
1	No run was started. The message says why: no server is running, ~/.orbital/server.json was left by a server that stopped, the server wants a secret (set ORBITAL_TOKEN), or the server refused the run.
2	Usage error, such as a missing --project or an --input without =.

orbital settings set

Changes one setting on the server running on this machine, the desktop app’s or orbital serve’s.

orbital settings set <setting> <value> [--server <url>]

It finds the server the way orbital run start does. Settings > Recent changes lists the change with the command’s words as its source.

Setting	Value
runs-at-once	How many runs run at once: a whole number of 1 or more, or default.
public-address	Where people reach Orbital, which links it hands out use: an http or https URL with no path, such as https://orbital.example.com, or default to use the address the server listens on.
delivery-lead-feature	on or off.
triggers-feature	on or off.
accounts-feature	on or off. Only a development build offers it.

Flag	What it does	Default
--server <url>	server to change, instead of the one ~/.orbital/server.json names; ORBITAL_URL does the same	The server ~/.orbital/server.json names
--version	print the version this command is running and exit

Example:

orbital settings set runs-at-once 4

It prints:

Set runs-at-once to 4 on http://127.0.0.1:52011/.

Exit codes:

Code	Meaning
0	The setting was changed.
1	Nothing was changed. The message says why: the setting or value is not one the command knows, no server is running, the server wants a secret (set ORBITAL_TOKEN), or the server refused the value.
2	Usage error, such as a missing value.

orbital skill install

Installs every skill that ships with Orbital, for agents and for Claude.

orbital skill install [--replace <name>]...

It installs these skills:

• orbital-create-workflow designs Orbital workflows.
• orbital-delivery-lead delivers tickets through Orbital runs.

Each skill is copied to ~/.agents/skills/<name> and linked from ~/.claude/skills/<name>.

The command prints one line for each skill:

Line	Meaning
Installed <name>.	The skill was not installed before, and now is.
Updated <name> to the version this release ships.	An earlier release installed the skill and nobody changed it since. The command replaced it.
<name> is already up to date.	Nothing changed.
Kept <name>: <path> differs from the bundled skill and was not changed.	Someone changed the installed copy or link. The command left it as it is. The line suggests --replace.
Replaced <name> with the bundled skill; the old one is now <backup>.	--replace moved the old copy aside and installed the bundled one.
Could not install <name>: <reason>	The skill failed. The other skills still install.

--replace <name> moves the installed copy or link aside as a dated backup and installs the bundled skill. Backups go to ~/.agents/skill-backups for a copy and ~/.claude/skill-backups for a link.

When an earlier release installed a skill under a name Orbital no longer uses, the command removes that old copy once the new skill is in place, unless someone changed it; a changed copy is kept and reported.

Flag	What it does	Default
--replace <name>	move the installed copy of this skill aside as a dated backup and install the bundled one; repeat for more	None

Settings > Command line and skills in the app shows each skill’s state and installs, updates or replaces it the same way.

Example:

orbital skill install --replace orbital-delivery-lead

Exit codes:

Code	Meaning
0	Every skill is installed, updated, up to date, replaced or kept.
1	At least one skill could not be installed, or --replace named a skill Orbital does not ship. In the second case nothing is installed.
2	Usage error.

Environment variables

Variable	What it does
ORBITAL_HOME	Takes the place of your home directory for Orbital’s data. The data directory becomes $ORBITAL_HOME/.orbital. Skills still install under your own home directory.
ORBITAL_NO_OPEN	When set, orbital serve leaves the browser closed, as --no-open does.
ORBITAL_URL	The server orbital run start uses, as --server does. --server wins when both are given.
ORBITAL_TOKEN	The secret orbital run start sends. It replaces the secret in ~/.orbital/server.json, and it is the only secret sent to a server that file does not name.
OPENROUTER_API_KEY	Lets OpenCode use OpenRouter models. Export it in the shell that starts the server. A server that was already running does not see a later export, so restart it.

The server sets ORBITAL_HOME to ~/.orbital/turn-home for every agent it starts. An orbital command an agent runs then uses its own data, not yours.

Where Orbital keeps its data

Orbital keeps its data in ~/.orbital, or in $ORBITAL_HOME/.orbital when ORBITAL_HOME is set.

Path	Holds
run-history.db	Every run’s progress and transcript, the settings change record, and every saved secret, encrypted: the GitHub token, the Linear and OpenRouter keys and the MCP endpoint token.
master-key	The key that encrypts the saved secrets, only on a computer with no OS secret store and no ORBITAL_SECRET_KEY. Only you can read it.
config.json	Settings.
server.json	Where the running server listens, and a window’s secret. Only you can read it. The server removes it when it stops.
workflows/	Your workflow library.
exports/	Run exports written by the MCP tool export_run.
attachments/	Files attached in chats.
delivery-lead/	The folder the delivery lead’s chats work in.
worktrees/	The worktrees runs work in.
turn-home/	The data directory of the agents Orbital starts.
logs/server/orbital.log	The server’s log. The desktop app’s Help > Show Logs opens its folder.

The first start after an upgrade updates run-history.db. An older release refuses to open the file once a newer one has updated it. To go back to an older release, move run-history.db aside rather than deleting it.

Related

• Command line: when to use each subcommand, with worked examples
• Settings: every setting, and the settings file the command changes
• HTTP API: call the running server from a script
• Use the shipped skills: what the skills orbital skill install installs do