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

# Manage CI runners from the CLI

> Create and manage CI runners, attach sandboxes, and read job logs with the brimble ci command.

`brimble ci` manages [CI runners](https://paper.brimble.io/sandboxes/ci-runners.md), the Brimble sandboxes that run your GitHub organization's Actions jobs.

```bash theme={null}
brimble ci list
brimble ci create
brimble ci jobs my-runner
brimble ci logs my-runner <job-id>
```

The command is also available as `ci-runner` and `runners`.

## Before you start

CI runners need a GitHub organization connected to your account and a plan that includes CI runners. Each organization has one runner. See [CI runners](https://paper.brimble.io/sandboxes/ci-runners.md) for the full setup, including the GitHub App permission an organization owner must accept.

## Create a runner

```bash theme={null}
brimble ci create
```

The command asks for the GitHub organization, a name, and how jobs should run. For a runner that starts a fresh sandbox per job, it also asks for a size and region.

For scripts, pass the values:

```bash theme={null}
brimble ci create --account acme --name ci --mode per_job --size sbx.micro --region us-east-1
brimble ci create --account acme --mode reuse
```

| Flag | Meaning |
| - | - |
| `--account` | The GitHub organization, by username or name |
| `--name` | Runner name |
| `--mode` | `per_job` for a fresh sandbox per job, `reuse` for long-lived sandboxes |
| `--size` | Sandbox size, for `per_job` mode |
| `--region` | Sandbox region, for `per_job` mode |
| `--max-concurrency` | Maximum concurrent jobs |
| `-y, --yes` | Skip the confirmation prompt |

In a script, `--account` and `--name` are required, and `--mode` defaults to `per_job`.

## List and inspect

```bash theme={null}
brimble ci list
brimble ci get
brimble ci get my-runner
```

`get` is also `show` and `info`. `list` is also `ls`.

## Change or delete a runner

```bash theme={null}
brimble ci update my-runner --name ci-2
brimble ci update my-runner --disable
brimble ci delete my-runner
```

`update` with no flags asks what to change. It also accepts `--mode`, `--size`, `--region`, `--max-concurrency`, and `--enable` to turn a runner back on.

Deleting a runner detaches its sandboxes and removes the runner. The sandboxes are not deleted.

## Jobs and logs

```bash theme={null}
brimble ci jobs my-runner
brimble ci logs my-runner <job-id>
```

`jobs` lists the GitHub Actions jobs that asked for this runner, newest first, with `--page` and `--limit` to page through them. `logs` prints one job's log; with no job ID it asks you to pick from the list.

## Sandboxes on a reuse runner

A `reuse` runner needs at least one attached sandbox to run jobs.

```bash theme={null}
brimble ci sandbox list my-runner
brimble ci sandbox attach my-runner
brimble ci sandbox detach my-runner
```

`attach` offers an existing ready sandbox or a new one. Pass `--sandbox <name-or-id>` to attach an existing sandbox, or `--new --size sbx.micro --region us-east-1` to create one. `detach` asks which sandbox to remove. Detaching stops the runner in that sandbox and returns the sandbox to its normal expiry.

## See also

* [CI runners](https://paper.brimble.io/sandboxes/ci-runners.md), the concept, the setup, and the `runs-on` label in a workflow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.