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

# Folders

> CLI reference for creating, inspecting, listing, and removing shared folders (alpha).

<Warning>
  Folders are an **alpha** feature. The `folders` commands are hidden by
  default — set `USE_EXPERIMENTAL_FEATURES=true` in your environment to enable
  them. See [Folders](/platform/folders) for concepts, consistency semantics,
  and the quickstart.
</Warning>

## folders new

Create a folder. Provisioning takes a few seconds.

```bash theme={"theme":"css-variables"}
machine0 folders new <name>
```

```bash theme={"theme":"css-variables"}
$ machine0 folders new code
✓ Folder "code" is ready (25 GiB)
```

Folder names use lowercase letters, numbers, and hyphens (max 31 characters).
Each account can have up to 5 folders; every folder has a 25 GiB quota during
the alpha.

***

## folders ls

List your folders.

```bash theme={"theme":"css-variables"}
machine0 folders ls
```

| Flag     | Description | Default |
| -------- | ----------- | ------- |
| `--json` | Output JSON | off     |

```bash theme={"theme":"css-variables"}
$ machine0 folders ls
┌──────┬────────┬────────┬────────┬────────────┐
│ Name │ Status │ Size   │ Mounts │ Created    │
├──────┼────────┼────────┼────────┼────────────┤
│ code │ READY  │ 25 GiB │ 1      │ 2026-07-08 │
└──────┴────────┴────────┴────────┴────────────┘
```

A folder in `ERRORED` state failed to provision or to fully tear down — run
`folders rm <name>` to clean it up (it can be retried safely).

***

## folders get

Show a folder's details — status, size, space used, and which VMs mount it —
and list the files inside it, without mounting it on a VM.

```bash theme={"theme":"css-variables"}
machine0 folders get <name> [path]
```

| Flag              | Description                                                | Default |
| ----------------- | ---------------------------------------------------------- | ------- |
| `--after <token>` | Continuation token printed by a previous truncated listing | —       |
| `--json`          | Output JSON                                                | off     |

```bash theme={"theme":"css-variables"}
$ machine0 folders get code
FOLDERS > code

  Status   READY
  Size     25 GiB
  Used     1.2 GiB
  Mounts   webserver:/data
  Created  2026-07-08

┌────────────┬──────┬─────────┐
│ Name       │ Type │ Size    │
├────────────┼──────┼─────────┤
│ dataset    │ dir  │ --      │
│ notes.md   │ file │ 4.1 KiB │
└────────────┴──────┴─────────┘
```

Pass a path (relative to the folder root — `.` and `..` are not allowed) to
list a subdirectory:

```bash theme={"theme":"css-variables"}
machine0 folders get code dataset/images
```

Listings show one directory level at a time, sorted by name, up to 1,000
entries per page — a truncated listing prints the continuation token to pass
via `--after`. Contents are read from the folder's metadata directly, so a
file written on a VM moments ago may take a short while to appear (see
[consistency](/platform/folders)).

***

## folders rm

Remove a folder and **all of its data**, permanently. Refused while any VM
still mounts the folder.

```bash theme={"theme":"css-variables"}
machine0 folders rm <name>
```

| Flag        | Description                  | Default |
| ----------- | ---------------------------- | ------- |
| `-y, --yes` | Skip the confirmation prompt | off     |

```bash theme={"theme":"css-variables"}
$ machine0 folders rm code -y
✓ Folder "code" destroyed
```

Removing a folder also revokes its access credentials, including on any VM,
image, or snapshot that still carries them.

***

## Mounting folders: `new --mount`

Mount folders when creating a VM with the repeatable `--mount` flag on
[`machine0 new`](/cli/machines#new). Each use takes two values: the folder and
the absolute path to mount it at.

```bash theme={"theme":"css-variables"}
machine0 new <vm> --mount folder:<name> path:</abs/path>
```

```bash theme={"theme":"css-variables"}
# one folder
machine0 new dev1 --mount folder:code path:/data

# multiple folders
machine0 new dev1 \
  --mount folder:code path:/data \
  --mount folder:models path:/mnt/models
```

Mount paths must be absolute (letters, numbers, `/`, `_`, `-`) and cannot be
inside system directories (`/etc`, `/usr`, `/var`, ...). Mounts survive
reboots and suspend/resume, and are set only at VM creation in the alpha.