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

# Manage Blob Storage files from the CLI

> List, upload, delete and link the files in your Square Cloud Blob Storage with squarecloud blob, and check how much of your plan's storage you use.

`squarecloud blob` manages the files in your [Blob Storage](https://docs.squarecloud.app/en/services/blob.md). A file is identified by its ID, which `blob list` and `blob upload` print.

The commands need an API key with the `blob:read` and `blob:write` [scopes](https://docs.squarecloud.app/en/blob-reference/authentication.md#scopes). The browser login asks for both. A key from a browser login before version 3.2.0 lacks them: the first Blob command then asks you to run `squarecloud auth login` again. A key in `SQUARECLOUD_API_KEY` needs both scopes too.

## `squarecloud blob list`

```bash Usage theme={"system"}
squarecloud blob list [prefix] [--json]
```

Prints the ID, size, creation date and URL of every file, or only of the files under `prefix`. A private file shows `(private)` instead of a URL.

```bash theme={"system"}
squarecloud blob list avatars/
# Only the files under avatars/.
```

With `--json`, it prints the files as a JSON array.

## `squarecloud blob upload`

```bash Usage theme={"system"}
squarecloud blob upload <file> [--name <name>] [--private] [--json]
```

| Flag | Description |
| - | - |
| `--name <name>` | Stores the file under this name, without the extension. By default, the name is the file name without its extension. |
| `--private` | Stores the file as private: it has no public URL and is reachable only through temporary links. |

Uploads one file and prints its ID and URL. The service keeps the extension of the file. In the default name, characters the service doesn't accept are replaced with `_`. To send a folder, zip it first with [`squarecloud zip`](https://docs.squarecloud.app/en/cli-reference/deploy#squarecloud-zip).

```bash theme={"system"}
squarecloud blob upload ./video.mp4
```

```bash Output theme={"system"}
Uploading video.mp4 (1.20 GB)...
Sent part 77 of 77
✓ Uploaded as <ID>
  <URL>
```

* **Large files:** a file above 90 MiB goes up in parts, six at a time, sized from the limits the service sends. The progress goes to stderr, so stdout carries only the result.
* **Failures:** a failed or canceled (`Ctrl+C`) upload is aborted, so it doesn't hold one of your open upload slots. Only reads and parts are retried, never a rate limit.
* **Private files:** instead of a URL, the CLI shows the command that makes a temporary link, [`blob url`](#squarecloud-blob-url).

With `--json`, stdout carries only the stored file (ID, visibility, URL and size, plus the number of parts for an upload in parts) as JSON.

## `squarecloud blob url`

```bash Usage theme={"system"}
squarecloud blob url <id> [--json]
```

Prints a download link for a file: its public URL, or a temporary link for a private file. Only the link goes to stdout, so it works inside `$(...)`. For a temporary link, the CLI says on stderr until when it is valid.

```bash theme={"system"}
curl -o report.pdf "$(squarecloud blob url <ID>)"
# Downloads a file, public or private.
```

With `--json`, it prints the link with its expiry, visibility, size and content type.

## `squarecloud blob delete`

```bash Usage theme={"system"}
squarecloud blob delete <id> [-y]
```

| Flag | Description |
| - | - |
| `-y`, `--yes` | Skips the confirmation prompt. |

> [!WARNING]
>
> Deleting a file is permanent: there is no trash.

Asks `Delete <ID> for good? There is no trash [y/N]` before deleting. `delete` has no JSON output.

## `squarecloud blob stats`

```bash Usage theme={"system"}
squarecloud blob stats [--json]
```

Shows how many files you store and how much of your plan's storage they use.

```bash Output theme={"system"}
Files: <count>
Storage: <used> used of the <included> in your plan
```

With `--json`, it prints your full usage record as JSON.

## Related

| Command | API | Blob SDK |
| - | - | - |
| `list` | [`GET /v1/objects`](https://docs.squarecloud.app/en/blob-reference/endpoint/list) | [`blob.list()`](https://docs.squarecloud.app/en/sdks/blob/objects#listing) |
| `upload` | [`POST /v1/objects`](https://docs.squarecloud.app/en/blob-reference/endpoint/post), [chunked upload](https://docs.squarecloud.app/en/blob-reference/endpoint/chunked-init.md) | [`blob.put()`](https://docs.squarecloud.app/en/sdks/blob/uploads) |
| `url` | [`GET /v1/objects/download`](https://docs.squarecloud.app/en/blob-reference/endpoint/download) | [`blob.downloadUrl()`](https://docs.squarecloud.app/en/sdks/blob/objects#download-links) |
| `delete` | [`DELETE /v1/objects`](https://docs.squarecloud.app/en/blob-reference/endpoint/delete) | [`blob.delete()`](https://docs.squarecloud.app/en/sdks/blob/objects#deleting) |
| `stats` | [`GET /v1/account/stats`](https://docs.squarecloud.app/en/blob-reference/endpoint/stats) | [`blob.stats()`](https://docs.squarecloud.app/en/sdks/blob/rules_and_stats#stats) |

To use Blob Storage from your own code, start with the [Blob SDK](https://docs.squarecloud.app/en/sdks/blob/client.md).


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