run CLI

Every machine except isolated ones 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.

$ run --help
Run automations and call third-party tools from inside a boxd machine

Scripts & jobs:
  run <file>.run.ts        register and run an automation
  run jobs                 registered automations and their state
  run logs <job-id> [-f]   an automation's log (-f follows it live)
  run stop <job-id>        stop one (its triggers unmount; the row stays)
  run restart <job-id>     stop + re-register it from the file
  run remove <job-id>      stop and forget it everywhere (alias: rm)

Connections:
  run auth                 what is connected
  run auth <toolkit>       connect one (add --scope <name> to share with your org)

Discovery:
  run list [--all]         every toolkit - connected and available
  run search <words>       find a tool across every toolkit
  run init [dir]           scaffold tsconfig + an example script

`--json` on jobs/list/search/auth prints machine-readable output.

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 organization and whether each is connected for you:

$ run
Enabled for this team:
  ✓ linear             personal, ops
  ✗ github             not connected - `run auth github`

Call a tool:  run <toolkit> <tool> --help
More:         run list · run search <words> · run <file>.run.ts · run jobs

An integration is enabled for the organization 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.

Discover tools

Integration and tool names are per organization and change over time, so look them up instead of guessing:

run list                          # everything connected, plus the catalog you can add (--all prints the whole catalog)
run search "create a pull request"   # semantic search across every tool; prints runnable lines
run linear                        # an integration's common commands
run linear --all                  # every command (large integrations curate their list)
run linear create-issue --help    # one command's parameters

$ run search "post a message to a channel"
run slack send-message
    Sends a message to a Slack channel.
run slack schedule-message
    Schedules a message for later.

run list marks integrations other members of your org 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 instead of from a fixed list (Granola, for example). run <integration> on one of those prints <integration> - N tools (served live by the connection) and the tools are called the same way.

Call a tool

run linear get-current-user
run linear get-issue --issue-id ENG-123
run github create-issue --owner acme --repo widgets --title "Bug" --labels '["p1"]'
run linear get-issue --issue-id ENG-123 --json

The result prints as YAML by default, or JSON with --json. Parameters:

Flags are the parameter names in kebab-case: issue_id becomes --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

run auth                        # every connection: integration, scope, who connected it
run auth linear                 # connect your own Linear; prints a URL to approve
run auth linear --scope ops     # connect a SHARED connection named "ops" for the whole org

$ run auth linear
Open this to connect linear:

  https://app.boxd.sh/integrations/connect/linear?org=…

Waiting for you to finish in the browser… (Ctrl-C to stop waiting)
✓ linear connected

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. To disconnect, use the console’s Integrations page or run boxd manage integrations disconnect <name>, with --scope <name> for a shared connection. Calls use your personal connection unless you say otherwise:

run linear list-issues --scope ops       # act as the org's shared "ops" connection
run linear list-issues --scope personal  # the explicit default
run linear list-issues --scope           # list the scopes available for this integration

Scopes for linear:
  personal         by Alice Example
  ops              by Bob Example

Use one with --scope <name>; personal is the default.

Calling an integration that isn’t connected at the scope you asked for fails immediately with the link that fixes it:

run: list-issues failed: not connected: linear (scope: ops)

Connect it here:

  https://app.boxd.sh/integrations/connect/linear?org=…&scope=ops

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:

run: list-issues failed: linear has 2 connections here and no default - re-run with --scope <name>: billing, ops

  --scope billing
  --scope ops

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:

run: get-issue failed: not connected: linear - this is a SHARED machine, so it uses the team's shared connections, never a member's personal one

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 the GitHub App.

Scripts and jobs

run init [dir]              # tsconfig.json (editor types) + hello.run.ts
run my-script.run.ts        # run it; a script with a trigger or schedule becomes a background job
run jobs                    # ID · STATE · SCHEDULE · STARTED · PATH
run logs <id> [-f]          # a job's log, -f to follow live
run stop <id>               # stop; the row stays, restartable
run restart <id>            # stop and re-register from the file
run remove <id>             # stop and forget (alias: rm)

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:

a3f01: running in the background - `run logs a3f01` to follow

Re-running the same file replaces its job under the same id. A script whose integrations aren’t all connected waits instead of failing:

a3f01: waiting on github (personal) - it will start on its own once connected

For states, retries and the console, see Jobs. For the SDK a script imports, see Scripts.

Global flags

Flag	Effect
`--json`	JSON output for tool results, and for `jobs`, `list`, `search`, `auth` and bare `run`
`--all`	List every command of an integration, or the whole catalog with `run list`
`--scope <name>`	Act as the org’s shared connection of that name. Bare `--scope` lists them

Shell completion

run completes integration names, tool names and flags dynamically, and *.run.ts paths. Add to your shell profile inside the machine:

eval "$(COMPLETE=bash run)"     # or COMPLETE=zsh

Getting started

Guides

Integrations and automations

Use cases

References

Start here: what’s enabled

Discover tools

Call a tool

Connections and scopes

Scripts and jobs

Global flags

Shell completion

​Start here: what’s enabled

​Discover tools

​Call a tool

​Connections and scopes

​Scripts and jobs

​Global flags

​Shell completion

Start here: what’s enabled

Discover tools

Call a tool

Connections and scopes

Scripts and jobs

Global flags

Shell completion