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.
vercel listUsing the vercel list command to retrieve information
about multiple deployments for the currently-linked Vercel Project.
vercel list [project-name]Using the vercel list command to retrieve information
about deployments for a specific Vercel Project.
vercel list [project-name] [--status READY,BUILDING]Using the vercel list command to retrieve information
about deployments filtered by status.
vercel list [project-name] [--meta foo=bar]Using the vercel list command to retrieve information
about deployments filtered by metadata.
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.
vercel list --meta key1=value1 --meta key2=value2Using 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:
vercel list --meta githubCommitSha=de8b89f13b2bc164cf07e735921bf5513e17951dFind deployments by Git commit SHA using the
githubCommitSha metadata key.
The --policy option can be used to display expiration based on Vercel project deployment retention policy.
vercel list --policy canceled=6m --policy errored=6m --policy preview=6m --policy production=6mUsing the vercel list command with the
--policy option.
The --status option can be used to filter deployments by their status.
vercel list --status READYUsing 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:
vercel list --status READY,BUILDINGUsing the vercel list command to filter by multiple
status values.
The supported status values are:
BUILDING- Deployments currently being builtERROR- Deployments that failed during build or runtimeINITIALIZING- Deployments in the initialization phaseQUEUED- Deployments waiting to be builtREADY- Successfully deployed and availableCANCELED- Deployments that were canceled before completionBLOCKED- 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.
vercel list my-app --environment=stagingTo list only production deployments, pass production:
vercel list --environment productionUsing 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:
vercel list --allUsing 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:
vercel list --limit 100Using 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:
vercel list --next 1584722256178Using 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:
vercel list --jsonUsing 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.
Was this helpful?