StarSling
CLICommands

sling disks

disks list and disks presets — see the StarSling Disks an org keeps, and browse the presets a workflow step can name

View Markdown

Two read-only commands for StarSling 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.

Both commands need sling 0.1.138 or later. Run sling --version to check, and run the installer again to update.

sling disks list

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; if you belong to a single org it is used automatically.

FlagMeaning
--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, --agentMachine 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.

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

ColumnMeaning
REPOThe repository that keeps the disk, as owner/name. Shows id:<repository id> when GitHub names are unavailable.
DISKThe disk's name, the value a step gives as name.
PLATFORMThe runner platform the disk belongs to.
PRESETThe preset the last publisher used, or — when none.
SIZE / CAPWhat 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.
PUBLISHEDWhen the current contents were published, as a relative time such as 3 days ago, or never.
AUTO-MOUNTyes if the disk's last publication allowed auto-mount, no if a step must mount it.
DISABLEDDISABLED for a disabled disk, — otherwise.

JSON output

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

The body is the GET /api/disks response, printed as-is.

FieldMeaning
disks[].repository_idThe repository's GitHub id, as a string.
disks[].repositoryowner/name. Omitted when GitHub cannot name the repository.
disks[].name, disks[].platform, disks[].pathThe disk's name, platform, and mount path.
disks[].presetThe preset name. Omitted when none.
disks[].size_bytes, disks[].size_cap_bytesCurrent contents and cap, in bytes.
disks[].change_testcontent-only or content-and-mtime.
disks[].auto_mountWhether the disk auto-mounts.
disks[].published_atWhen the contents were published. Omitted if never published.
disks[].disabledWhether 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

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 flagMeaning
<name>One preset. Also prints a ready-to-paste step for it.
--base home|workspaceOnly presets rooted in the job user's home directory, or in the workspace. Any other value is rejected.
--json, --agentMachine mode: the preset catalog (filtered by <name> and --base) on stdout.
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.

ColumnMeaning
PRESETThe name a step gives as preset.
BASEhome or workspace.
PATHWhere it mounts: ~/ plus the path for home, ./ plus the path for workspace.
CAPThe preset's size cap, in decimal GB.
CHANGE TESTHow a publication decides a file changed: content-only or content-and-mtime.
AUTO-MOUNTThe 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:

- 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.

An unknown name

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

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 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

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

See exit codes for the full table.

On this page