> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# run CLI

> The in-machine run command: call any connected integration from the shell, connect new ones, and start and operate automations.

Every machine has `run` pre-installed. It calls the tools of your [connected integrations](/guides/integrations/connections) from the shell, connects new ones, and runs and operates [automations](/guides/integrations/overview). There is nothing to install, start or log in to. It works the moment you have a shell.

```text theme={"theme":"github-dark"}
$ 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.
```

<Note>
  `run` is not available on **isolated** machines (`boxd machine new --isolated`), which have no integrations at all.
</Note>

## Start here: what's enabled

Bare `run` shows the integrations enabled for your team and whether each is connected for you:

```text theme={"theme":"github-dark"}
$ 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 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.

## Discover tools

Integration and tool names are per team and change over time, so look them up rather than guessing:

```bash theme={"theme":"github-dark"}
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
```

```text theme={"theme":"github-dark"}
$ 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 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.

## Call a tool

```bash theme={"theme":"github-dark"}
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` → `--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

```bash theme={"theme":"github-dark"}
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
```

```text theme={"theme":"github-dark"}
$ 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. Disconnecting is done on the console's Integrations page.

Calls use your **personal** connection unless you say otherwise:

```bash theme={"theme":"github-dark"}
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
```

```text theme={"theme":"github-dark"}
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:

```text theme={"theme":"github-dark"}
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:

```text theme={"theme":"github-dark"}
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:

```text theme={"theme":"github-dark"}
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 [GitHub](/guides/integrations/connections#the-github-app).

## Scripts and jobs

```bash theme={"theme":"github-dark"}
run init [dir]              # tsconfig.json (editor types) + hello.run.ts
run my-script.run.ts        # run it; long-runners go to the background as a 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:

```text theme={"theme":"github-dark"}
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 rather than failing:

```text theme={"theme":"github-dark"}
a3f01: waiting on github (personal) - it will start on its own once connected
```

Everything about states, retries and the console is on the [Jobs](/guides/automations/jobs) page. The SDK a script imports is on [Scripts](/guides/automations/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:

```bash theme={"theme":"github-dark"}
eval "$(COMPLETE=bash run)"     # or COMPLETE=zsh
```