sling disks
disks list and disks presets — see the StarSling Disks an org keeps, and browse the presets a workflow step can name
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.
| 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.
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
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.
| 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
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. |
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:
- uses: actions/checkout@v4
- uses: starslingdev/disks@v0
with:
preset: "cargo-target"
publish: on-changeThe 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
--jsonor--agent, or a flag with no value. --basewith anything buthomeorworkspace.--repothat is notowner/name, or an empty--org.--orgtogether with--repo.--baseonlist, or--organd--repoonpresets.- 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 for the full table.