# vercel list

The `vercel list` command, which can be shortened to `vercel ls`, provides a list of recent deployments for the currently-linked Vercel Project.

## Usage

```bash filename="terminal"
vercel list
```

## Extended Usage

```bash filename="terminal"
vercel list [project-name]
```

```bash filename="terminal"
vercel list [project-name] [--status READY,BUILDING]
```

```bash filename="terminal"
vercel list [project-name] [--meta foo=bar]
```

```bash filename="terminal"
vercel list [project-name] [--policy errored=6m]
```

## Unique Options

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

### Meta

The `--meta` option, shorthand `-m`, can be used to filter results based on Vercel deployment metadata.

```bash filename="terminal"
vercel list --meta key1=value1 key2=value2
```

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

```bash filename="terminal"
vercel ls -m githubCommitSha=de8b89f13b2bc164cf07e735921bf5513e17951d
```

> **💡 Note:** To see the meta values for a deployment, use [GET /deployments/{idOrUrl}
> ](https://vercel.com/docs/rest-api/reference/endpoints/deployments/get-a-deployment-by-id-or-url).

### Policy

The `--policy` option, shorthand `-p`, can be used to display expiration based on [Vercel project deployment retention policy](/docs/security/deployment-retention).

```bash filename="terminal"
vercel list --policy canceled=6m -p errored=6m -p preview=6m -p production=6m
```

### Yes

The `--yes` option can be used to skip questions you are asked when setting up a new Vercel Project.
The questions will be answered with the default scope and current directory for the Vercel Project name and location.

```bash filename="terminal"
vercel list --yes
```

### Status

The `--status` option, shorthand `-s`, can be used to filter deployments by their status.

```bash filename="terminal"
vercel list --status READY
```

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

```bash filename="terminal"
vercel list --status READY,BUILDING
```

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

### environment

Use the `--environment` option to list the deployments for a specific environment. This could be production, preview, or a [custom environment](/docs/deployments/environments#custom-environments).

```bash filename="terminal"
vercel list my-app --environment=staging
```

### Next

The `--next` option enables pagination when listing deployments. Pass the timestamp (in milliseconds since the UNIX epoch) from a previous response to get the next page of results.

```bash filename="terminal"
vercel list --next 1584722256178
```

### Prod

The `--prod` option filters the list to show only production deployments.

```bash filename="terminal"
vercel list --prod
```


--------------------------------------------------------------------------------
title: "vercel login"
description: "Learn how to login into your Vercel account using the vercel login CLI command."
last_updated: "2026-02-03T02:58:38.268Z"
source: "https://vercel.com/docs/cli/login"
--------------------------------------------------------------------------------