Every machine has run pre-installed. It calls the tools of your connected integrations from the shell, connects new ones, and runs and operates automations. There is nothing to install, start or log in to. It works the moment you have a shell.
run is not available on isolated machines (boxd machine new --isolated), which have no integrations at all.
Start here: what’s enabled
Bare run shows the integrations enabled for your team and whether each is connected for you:
An integration is enabled for the team once anyone in your org connects it or an automation uses it. You get its commands and completion either way, and connect it yourself when you need it.
Integration and tool names are per team and change over time, so look them up rather than guessing:
run list marks integrations your teammates already use with a ★ and shows the first 40 of the rest, with a trailer pointing at run list --all and run search. Names are the integration’s id in kebab-case (google-maps, microsoft-teams, googlesheets). An underscore spelling is accepted and redirected.
A few integrations serve their tools live from the connection rather than from a fixed list (Granola, for example). run <toolkit> on one of those prints <toolkit> - N tools (served live by the connection) and the tools are called the same way.
The result prints as YAML by default, or JSON with --json. Parameters:
- Flags are the parameter names in kebab-case:
issue_id → --issue-id.
- Object and array parameters take a JSON string:
--labels '["p1","bug"]'.
- Boolean parameters are bare flags:
--force. Omitting one sends nothing.
- Enumerated parameters are validated and listed in
--help.
- Required parameters are shown without brackets in
--help. A missing one is reported before anything is sent.
A failed call prints run: <command> failed: <reason> and exits non-zero.
Connections and scopes
A human completes the browser step. run auth waits up to three minutes and then reminds you the connection takes effect on its own once you finish. Disconnecting is done on the console’s Integrations page.
Calls use your personal connection unless you say otherwise:
Calling an integration that isn’t connected at the scope you asked for fails immediately with the link that fixes it:
An unscoped call uses your personal connection, or the org’s single shared one if that is the only option. With several shared connections and no personal one, the call stops and lists them as runnable lines:
On a shared machine only the org’s shared connections are available. An unscoped call that can’t be resolved there says so and links to a shared connect:
The GitHub App, when your org has installed it, is also callable. run github-app prints what it offers, and run github-app get-token mints a short-lived installation token. See GitHub.
Scripts and jobs
Each verb confirms what it did: a3f01: stopped - \run my-script.run.ts` or `run restart a3f01` starts it again, a3f01: restarted - `run logs a3f01 -f` to follow, a3f01: removed`.
A script that registers no trigger or schedule runs in the foreground and returns. One that does is moved to the background once its top level settles:
Re-running the same file replaces its job under the same id. A script whose integrations aren’t all connected waits rather than failing:
Everything about states, retries and the console is on the Jobs page. The SDK a script imports is on Scripts.
Global flags
Shell completion
run completes integration names, tool names and flags dynamically, and *.run.ts paths. Add to your shell profile inside the machine:
