# sling disks (/sling-cli/commands/disks)



Two read-only commands for [StarSling Disks](https://docs.starsling.dev/runners/disks). `sling disks list` shows the disks your repositories already keep. `sling disks presets` shows the preset catalog and prints a ready-to-paste workflow step. Neither command creates, changes, or deletes a disk.

Both commands show whether a disk auto-mounts. Auto-mount means the runner mounts a published disk under the job user's home before the steps of a trusted job: one with `id-token: write` whose code comes from the repository itself, not from a fork or a Dependabot run. Every other disk, including every workspace disk, needs a step to mount it. See [Auto-mount and paths](https://docs.starsling.dev/runners/disks#auto-mount-and-paths).

<Callout type="info">
  Both commands need `sling` 0.1.138 or later. Run `sling --version` to check, and run the [installer](https://docs.starsling.dev/sling-cli/installation) again to update.
</Callout>

## `sling disks list`

```text
sling disks list [--org <slug> | --repo <owner/name>] [--json | --agent]
```

Lists the disks in one org, or in one repository. With no flag it uses your default org. Set that default with [`sling org switch`](https://docs.starsling.dev/sling-cli/commands/auth#sling-org-switch); if you belong to a single org it is used automatically.

| Flag                  | Meaning                                                                                |
| --------------------- | -------------------------------------------------------------------------------------- |
| `--org <slug>`        | The org to list. Defaults to your default org. A blank value is rejected.              |
| `--repo <owner/name>` | Only the disks of one repository. The owner is the org. Must be a GitHub `owner/name`. |
| `--json`, `--agent`   | Machine mode: the API response on stdout, with no local envelope.                      |

`--org` and `--repo` cannot be combined. Passing both prints `Use --org or --repo, not both.` and exits `2` before any request is made. `--repo` already names its org through the owner.

`--repo` must use the repository's current name. A name from before a rename, or a repository StarSling's GitHub app cannot see, prints `No disks found.` and exits `0`.

```console
$ sling disks list --org acme
StarSling Disks
REPO          DISK          PLATFORM            PRESET        SIZE / CAP      PUBLISHED   AUTO-MOUNT  DISABLED
id:892174354  pnpm-store    ubuntu-24.04/x64    pnpm-store    1.2 GB / 20 GB  3 days ago  yes         —
id:77         cargo-target  ubuntu-24.04/arm64  cargo-target  0 GB / 120 GB   never       no          —

⚠ Repository names are temporarily unavailable from GitHub, so disks show repository ids. The disks themselves are complete.
```

Example output, with a fictional org. The warning appears only when GitHub cannot name the repositories; otherwise the `REPO` column shows `owner/name`. With no disks the command prints `No disks found.`

### Columns

| Column       | Meaning                                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `REPO`       | The repository that keeps the disk, as `owner/name`. Shows `id:<repository id>` when GitHub names are unavailable.                         |
| `DISK`       | The disk's name, the value a step gives as `name`.                                                                                         |
| `PLATFORM`   | The runner platform the disk belongs to.                                                                                                   |
| `PRESET`     | The preset the last publisher used, or `—` when none.                                                                                      |
| `SIZE / CAP` | What the disk currently holds, then its size cap. Decimal GB (1 GB = 1,000,000,000 bytes); a non-empty disk under 10 MB prints `<0.01 GB`. |
| `PUBLISHED`  | When the current contents were published, as a relative time such as `3 days ago`, or `never`.                                             |
| `AUTO-MOUNT` | `yes` if the disk's last publication allowed auto-mount, `no` if a step must mount it.                                                     |
| `DISABLED`   | `DISABLED` for a disabled disk, `—` otherwise.                                                                                             |

### JSON output

```bash
sling disks list --org acme --json | jq -c '{n: (.disks|length), warnings: [.warnings[]?.code]}'
```

The body is the [`GET /api/disks`](https://docs.starsling.dev/api/disks/list-disks) response, printed as-is.

| Field                                              | Meaning                                                                                                                             |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `disks[].repository_id`                            | The repository's GitHub id, as a string.                                                                                            |
| `disks[].repository`                               | `owner/name`. Omitted when GitHub cannot name the repository.                                                                       |
| `disks[].name`, `disks[].platform`, `disks[].path` | The disk's name, platform, and mount path.                                                                                          |
| `disks[].preset`                                   | The preset name. Omitted when none.                                                                                                 |
| `disks[].size_bytes`, `disks[].size_cap_bytes`     | Current contents and cap, in bytes.                                                                                                 |
| `disks[].change_test`                              | `content-only` or `content-and-mtime`.                                                                                              |
| `disks[].auto_mount`                               | Whether the disk auto-mounts.                                                                                                       |
| `disks[].published_at`                             | When the contents were published. Omitted if never published.                                                                       |
| `disks[].disabled`                                 | Whether the disk is disabled.                                                                                                       |
| `warnings[]`                                       | Omitted when empty. Each has a `code` and a `message`; `REPOSITORY_NAMES_UNAVAILABLE` means `repository` is missing from the disks. |

## `sling disks presets`

```text
sling disks presets [<name>] [--base home|workspace] [--json | --agent]
```

Browses the preset catalog. A preset is a named directory a step can mount with `preset: <name>`. The catalog is the same for every caller.

| Argument or flag         | Meaning                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `<name>`                 | One preset. Also prints a ready-to-paste step for it.                                                   |
| `--base home\|workspace` | Only presets rooted in the job user's home directory, or in the workspace. Any other value is rejected. |
| `--json`, `--agent`      | Machine mode: the preset catalog (filtered by `<name>` and `--base`) on stdout.                         |

```console
$ sling disks presets --base workspace
StarSling Disks presets
PRESET              BASE       PATH             CAP     CHANGE TEST        AUTO-MOUNT
cargo-target        workspace  ./target         120 GB  content-and-mtime  no
mix-deps            workspace  ./deps           20 GB   content-and-mtime  no
…
Limits: default cap 200 GB; max cap 200 GB; 32 disks per repository.
```

The rows above are an excerpt. Run the command for the full catalog. The catalog comes from StarSling, not from the CLI, so it includes presets added after your `sling` release.

| Column        | Meaning                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------- |
| `PRESET`      | The name a step gives as `preset`.                                                       |
| `BASE`        | `home` or `workspace`.                                                                   |
| `PATH`        | Where it mounts: `~/` plus the path for `home`, `./` plus the path for `workspace`.      |
| `CAP`         | The preset's size cap, in decimal GB.                                                    |
| `CHANGE TEST` | How a publication decides a file changed: `content-only` or `content-and-mtime`.         |
| `AUTO-MOUNT`  | The preset's auto-mount default: `yes` for `home` presets, `no` for `workspace` presets. |

The `Limits` line is the default cap, the largest cap allowed, and the maximum disks per repository. The default cap applies only when a step names neither a preset nor a `size-cap`, unless StarSling has set a different limit for that disk; a preset brings its own cap, shown in the `CAP` column. Filters that match nothing print `No presets match these filters.`

### One preset, with its step

Naming a preset adds the job requirements and a step to paste. The step includes `publish: on-change`, because the default, `never`, would leave the disk empty. A `workspace` preset does not auto-mount, so the step follows checkout and the output says so. The step is built from the CLI's step template:

```yaml
- uses: actions/checkout@v4
- uses: starslingdev/disks@v0
  with:
    preset: "cargo-target"
    publish: on-change
```

The output also reminds you that the job must grant `permissions: id-token: write`, and that only a successful default-branch job publishes. For what each preset is for and how publication works, see [Disks](https://docs.starsling.dev/runners/disks#presets).

### An unknown name

A name that is not in the catalog exits `3` and names the three closest presets:

```console
$ sling disks presets pnpm-stor
Unknown preset "pnpm-stor". Closest presets: pnpm-store, npm-npx, cabal-store.
```

The JSON output is the [`GET /api/disks/presets`](https://docs.starsling.dev/api/disks/get-disk-presets) response with `presets` filtered. `limits` carries `default_size_cap_bytes`, `max_size_cap_bytes`, and `max_disks_per_repository`. Each preset has `name`, `base`, `path`, `size_cap_bytes`, `change_test`, and `auto_mount`.

## Mistakes caught before sign-in

Both commands check their flags before they look at your credentials, so a malformed call exits `2` whether or not you are signed in. These all exit `2`:

* An unknown flag, a value on `--json` or `--agent`, or a flag with no value.
* `--base` with anything but `home` or `workspace`.
* `--repo` that is not `owner/name`, or an empty `--org`.
* `--org` together with `--repo`.
* `--base` on `list`, or `--org` and `--repo` on `presets`.
* More than one preset name, or an extra word after the subcommand. The command prints its usage.
* Anything after a bare `--`, which counts as extra words.

## Exit codes

| Code | Meaning                                                                                  |
| ---- | ---------------------------------------------------------------------------------------- |
| `0`  | Success, including an empty list.                                                        |
| `2`  | Usage error, or no default org could be chosen (no org, or several orgs and no `--org`). |
| `3`  | `presets` was given a name that is not in the catalog.                                   |
| `4`  | Not signed in (run `sling login`), or `--org` names an org you are not a member of.      |
| `5`  | The control plane or the GitHub repository lookup failed. Try again shortly.             |

See [exit codes](https://docs.starsling.dev/sling-cli/configuration#exit-codes) for the full table.
