Skip to content
Docs

vercel list

The vercel list command provides a list of recent deployments for the currently-linked Vercel Project. When the current directory is not linked to a Vercel Project, the command lists deployments across all projects in the current scope.

terminal
vercel list

Using the vercel list command to retrieve information about multiple deployments for the currently-linked Vercel Project.

terminal
vercel list [project-name]

Using the vercel list command to retrieve information about deployments for a specific Vercel Project.

terminal
vercel list [project-name] [--status READY,BUILDING]

Using the vercel list command to retrieve information about deployments filtered by status.

terminal
vercel list [project-name] [--meta foo=bar]

Using the vercel list command to retrieve information about deployments filtered by metadata.

terminal
vercel list [project-name] [--policy errored=6m]

Using the vercel list command to retrieve information about deployments including retention policy.

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

The --meta option can be used to filter results based on Vercel deployment metadata. Repeat the flag to filter by multiple metadata pairs.

terminal
vercel list --meta key1=value1 --meta key2=value2

Using the vercel list command with the --meta option. Repeat the flag for each key/value pair.

A common use case is filtering by the Git commit SHA that created a deployment:

terminal
vercel list --meta githubCommitSha=de8b89f13b2bc164cf07e735921bf5513e17951d

Find deployments by Git commit SHA using the githubCommitSha metadata key.

To see the meta values for a deployment, use GET /deployments/{idOrUrl} .

The --policy option can be used to display expiration based on Vercel project deployment retention policy.

terminal
vercel list --policy canceled=6m --policy errored=6m --policy preview=6m --policy production=6m

Using the vercel list command with the --policy option.

The --status option can be used to filter deployments by their status.

terminal
vercel list --status READY

Using the vercel list command with the --status option to filter by a single status.

You can filter by multiple status values using comma-separated values:

terminal
vercel list --status READY,BUILDING

Using the vercel list command to filter by multiple status values.

The supported status values are:

  • BUILDING - Deployments currently being built
  • ERROR - Deployments that failed during build or runtime
  • INITIALIZING - Deployments in the initialization phase
  • QUEUED - Deployments waiting to be built
  • READY - Successfully deployed and available
  • CANCELED - Deployments that were canceled before completion
  • BLOCKED - Deployments that Vercel blocked from building

Use the --environment option to list the deployments for a specific environment. This could be production, preview, or a custom environment.

terminal
vercel list my-app --environment=staging

To list only production deployments, pass production:

terminal
vercel list --environment production

Using the vercel list command with the --environment option to show only production deployments.

Use the --all option to list deployments across all projects in the current scope, even when the current directory is linked to a Vercel Project:

terminal
vercel list --all

Using the vercel list command with the --all option.

Use the --limit option to change how many deployments the command lists. The default is 20 and the maximum is 100:

terminal
vercel list --limit 100

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

The --next option enables pagination when listing deployments. When more deployments remain, the output ends with the command for the next page, which passes a cursor to --next:

terminal
vercel list --next 1584722256178

Using the vercel list command with the --next option for pagination.

Use the --json option to output the list as JSON, for example to read it in a script:

terminal
vercel list --json

Using the vercel list command with the --json option.

When more deployments remain, pagination.next in the JSON output has the cursor for --next.

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

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

Last updated August 11, 2026

Was this helpful?

supported.