vercel blob

The vercel blob command is used to interact with Vercel Blob storage, providing functionality to upload, download, list, delete, and copy files in public and private stores, store optimized images, and manage Blob stores.

For more information about Vercel Blob, see the Vercel Blob documentation and Vercel Blob SDK reference.

Usage

The vercel blob command supports the following operations:

list - List all files in the Blob store
put - Upload a file to the Blob store
put-image - Optimize an image and store the result in the Blob store
del - Delete a file from the Blob store
copy - Copy a file in the Blob store
get - Download a blob from the Blob store
create-store - Create a new Blob store
delete-store - Delete a Blob store
get-store - Get a Blob store
list-stores - List all Blob stores
empty-store - Delete all blobs in a Blob store

In a linked project with a connected Blob store, the CLI authenticates using OIDC by default: Vercel auto-populates VERCEL_OIDC_TOKEN and pairs it with BLOB_STORE_ID. If OIDC is not available, the CLI falls back to reading BLOB_READ_WRITE_TOKEN from your env file, or you can supply it directly with the --rw-token option. For example, this can happen for an unlinked project, outside of Vercel, or during local development.

list (ls)

terminal

vercel blob list

Using the vercel blob list command to list all files in the Blob store.

put

terminal

vercel blob put [path-to-file] --access private

Using the vercel blob put command to upload a file to the Blob store.

put-image

terminal

vercel blob put-image [path-to-file-or-url] --pathname [pathname] --width [width] --access private

Using the vercel blob put-image command to run an image through Image Optimization and store only the optimized output in the Blob store. The source can be a local file or a public http(s) URL, which Vercel fetches and optimizes server-side. The command prints the URL of the stored blob to stdout, so scripts and agents can read the result back. Use --json to print the full blob object instead.

The transformation is controlled with the --width (required), --quality, and --format options:

terminal

vercel blob put-image https://example.com/hero.png --pathname images/hero.webp --width 512 --quality 60 --format webp --access public

Fetching a remote image, converting it to a 512 pixel wide WebP, and storing it in the Blob store.

The command requires OIDC credentials: pass --oidc-token and --store-id, or set the VERCEL_OIDC_TOKEN and BLOB_STORE_ID environment variables (available in .env.local after vercel env pull). Read-write tokens are not accepted.

Each upload is billed as one image transformation plus a regular blob upload at standard Vercel Blob pricing.

If the transformed image would be larger than the source image, the source image is stored unchanged and the command prints a warning. The --content-type and --multipart options are not available: the stored content type always comes from the optimizer output, so use --format to control it, and optimized uploads cannot be split into parts.

del

This action is permanent and cannot be undone.

terminal

vercel blob del [url-or-pathname]

Using the vercel blob del command to delete a file from the Blob store.

copy (cp)

terminal

vercel blob copy [from-url-or-pathname] [to-pathname] --access private

Using the vercel blob copy command to copy a file in the Blob store.

get

terminal

vercel blob get [url-or-pathname] --access private

Using the vercel blob get command to download a blob. Works with both public and private stores. Content is printed to stdout by default, or saved to a file with --output.

create-store

terminal

vercel blob create-store [name] --access <access> [--region <region>] [--yes] [--environment <env>]

Using the vercel blob create-store command to create a new Blob store. The default region is set to iad1 when not specified. Use --yes to auto-connect to the linked project (defaults to all environments). Use --environment to specify which environments to connect (repeatable).

delete-store

This action is permanent and cannot be undone.

terminal

vercel blob delete-store [store-id] [--yes]

Using the vercel blob delete-store command to delete a Blob store. Use --yes to skip the confirmation prompt in CI environments.

get-store

terminal

vercel blob get-store [store-id]

Using the vercel blob get-store command to get a Blob store.

list-stores (ls-stores)

terminal

vercel blob list-stores [--all]

Using the vercel blob list-stores command to list all Blob stores. When run in a linked project directory, only stores connected to that project are shown. Use --all to list all team stores regardless of project. In a terminal, an interactive selector lets you browse store details.

empty-store

This action is permanent and cannot be undone.

terminal

vercel blob empty-store [store-id] [--yes]

Using the vercel blob empty-store command to delete all blobs in a Blob store. Use --yes to skip the confirmation prompt in CI environments.

Unique Options

These are options that only apply to the vercel blob command.

Rw token

You can use the --rw-token option to specify your Blob read-write token. This is a fallback authentication method for cases where OIDC is not available such as unlinked projects, environments outside of Vercel, or local development.

terminal

vercel blob put image.jpg --rw-token [rw-token]

Using the vercel blob put command with the --rw-token option.

Limit

You can use the --limit option to specify the number of results to return per page when using list. The default value is 10 and the maximum is 1000.

terminal

vercel blob list --limit 100

Using the vercel blob list command with the --limit option.

Cursor

You can use the --cursor option to specify the cursor from a previous page to start listing from.

terminal

vercel blob list --cursor [cursor-value]

Using the vercel blob list command with the --cursor option.

Prefix

You can use the --prefix option to filter Blobs by a specific prefix.

terminal

vercel blob list --prefix images/

Using the vercel blob list command with the --prefix option.

Mode

You can use the --mode option to filter Blobs by either folded or expanded mode. The default is expanded.

terminal

vercel blob list --mode folded

Using the vercel blob list command with the --mode option.

Add Random Suffix

You can use the --add-random-suffix option to add a random suffix to the file name when using put, put-image, or copy.

terminal

vercel blob put image.jpg --add-random-suffix

Using the vercel blob put command with the --add-random-suffix option.

Pathname

You can use the --pathname option to specify the pathname to upload the file to. For put, the default is the filename. For put-image, this option is required: the command takes a separate input (a file or URL, possibly a blob already in your store) and output, so it needs an explicit pathname for the result.

terminal

vercel blob put image.jpg --pathname assets/images/hero.jpg

Using the vercel blob put command with the --pathname option.

Width

You can use the --width option to set the width of the optimized image in pixels, between 1 and 8192. The aspect ratio of the source image is preserved. This option is required and only applies to the put-image command.

terminal

vercel blob put-image photo.png --pathname images/photo.png --width 1200 --access public

Using the vercel blob put-image command with the --width option.

Quality

You can use the --quality option to set the quality of the optimized image, between 1 (lowest quality) and 100 (highest quality). The default is 75. This option only applies to the put-image command.

terminal

vercel blob put-image photo.png --pathname images/photo.png --width 1200 --quality 60 --access public

Using the vercel blob put-image command with the --quality option.

Format

You can use the --format option to convert the optimized image to jpeg, png, webp, or avif. The source image format is preserved when omitted. This option only applies to the put-image command.

terminal

vercel blob put-image photo.png --pathname images/photo.webp --width 1200 --format webp --access public

Using the vercel blob put-image command with the --format option.

JSON

You can use the --json option to print the stored blob as JSON, including its url, downloadUrl, pathname, and contentType, instead of only the URL. This option only applies to the put-image command.

terminal

vercel blob put-image photo.png --pathname images/photo.png --width 1200 --access public --json

Using the vercel blob put-image command with the --json option.

Content Type

You can use the --content-type option to overwrite the content-type when using put or copy. It will be inferred from the file extension if not provided.

terminal

vercel blob put data.txt --content-type application/json

Using the vercel blob put command with the --content-type option.

Cache Control Max Age

You can use the --cache-control-max-age option to set the max-age of the cache-control header directive when using put, put-image, or copy. The default is 2592000 (30 days).

terminal

vercel blob put image.jpg --cache-control-max-age 86400

Using the vercel blob put command with the --cache-control-max-age option.

Allow Overwrite

You can use the --allow-overwrite option to overwrite the file if it already exists when uploading with put or put-image. The default is false.

terminal

vercel blob put image.jpg --allow-overwrite

Using the vercel blob put command with the --allow-overwrite option.

Multipart

You can use the --multipart option to upload the file in multiple small chunks for performance and reliability. The default is true.

terminal

vercel blob put large-file.zip --multipart false

Using the vercel blob put command with the --multipart option.

Region

You can use the --region option to specify the region where your Blob store should be created. The default is iad1. This option is only applicable when using the create-store command.

terminal

vercel blob create-store my-store --region sfo1

Using the vercel blob create-store command with the --region option.

Access

The --access option is required and specifies whether the store or blob should use public or private storage. This option applies to the put, put-image, copy, get, and create-store commands.

terminal

vercel blob put image.jpg --access private

Using the vercel blob put command with the --access option.

Output

You can use the --output option to save the blob content to a file instead of printing it to stdout. This option only applies to the get command.

terminal

vercel blob get image.jpg --output ./local-image.jpg

Using the vercel blob get command with the --output option.

If Match

You can use the --if-match option to only perform the operation if the blob's ETag matches the provided value. This option applies to the put, del, and copy commands.

terminal

vercel blob put image.jpg --if-match "etag-value"

Using the vercel blob put command with the --if-match option.

If None Match

You can use the --if-none-match option to only return content if the blob's ETag does not match the provided value. If unchanged, the server returns a 304 response. This option applies to the get command.

terminal

vercel blob get image.jpg --if-none-match "etag-value"

Using the vercel blob get command with the --if-none-match option.

Global Options

The following global options can be passed when using the vercel blob command:

For more information on global options and their usage, refer to the options section.

Last updated August 13, 2026

Cross-link map: vercel blob (/docs/cli/blob)

From the Vercel docs graph (built 2026-08-28T09:34:23.960Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

Managing Vercel Blob storage from the CLI — Create blob stores, upload files, list contents, and manage storage using the CLI.
Public Storage — Learn how to use public Vercel Blob storage to serve files accessible to anyone with the URL
The Complete Guide to Vercel Blob — Vercel Blob stores and serves files of any size through Vercel's global network. Learn how Blob works, what it costs, an
Vercel Blob examples — Examples on how to use Vercel Blob in your applications
@vercel/blob — Learn how to use the Vercel Blob SDK to access your blob store from your apps.

This page links to (6)

Limits and Pricing for Image Optimization — This page outlines information on the limits that are applicable when using Image Optimization, and the costs they can i
Vercel Blob — Vercel Blob is a scalable, cost-effective object storage service with private and public access modes for files up to 5
Private Storage — Learn how to use private Vercel Blob storage to serve files with authentication
Public Storage — Learn how to use public Vercel Blob storage to serve files accessible to anyone with the URL
Vercel Blob Pricing — Learn about the pricing for Vercel Blob.
@vercel/blob — Learn how to use the Vercel Blob SDK to access your blob store from your apps.

Pages that link here (10)

By site: vercel-changelog (2) · vercel-docs (8)

From vercel-changelog

From vercel-docs

Vercel CLI Overview — Learn how to use the Vercel command-line interface \(CLI\) to manage and configure your Vercel Projects from the command
Image Optimization with Vercel — Transform and optimize images to improve page load performance.
Vercel Documentation Sitemap — Browse Vercel documentation pages with summaries, prerequisites, and topics.
Vercel Blob — Vercel Blob is a scalable, cost-effective object storage service with private and public access modes for files up to 5
Managing Vercel Blob storage from the CLI — Create blob stores, upload files, list contents, and manage storage using the CLI.
Private Storage — Learn how to use private Vercel Blob storage to serve files with authentication
Public Storage — Learn how to use public Vercel Blob storage to serve files accessible to anyone with the URL
@vercel/blob — Learn how to use the Vercel Blob SDK to access your blob store from your apps.

vercel bisect

vercel build

Was this helpful?