vercel alias

The vercel alias command allows you to apply custom domains to your deployments.

When a new deployment is created (with our Git Integration, Vercel CLI, or the REST API), the platform will automatically apply any custom domains configured in the project settings.

Any custom domain that doesn't have a custom preview branch configured (there can only be one Production Branch and it's configured separately in the project settings) will be applied to production deployments created through any of the available sources.

Branch-specific domains require a deployment associated with the configured Git branch. Git integrations supply this association automatically. For CLI deployments, check the Git metadata, especially when deploying from CI or a detached checkout.

Use vercel alias when you need to assign a domain manually, independently of automatic branch assignment.

The vercel alias command is not the recommended way to promote production deployments to specific domains. Instead, you can use the following commands:

• vercel --prod --skip-domain: Use to skip custom domain assignment when deploying to production and creating a staged deployment
• vercel promote [deployment-id or url]: Use to promote your staged deployment to your custom domains
• vercel rollback [deployment-id or url]: Use to alias an earlier production deployment to your custom domains

In general, the command allows for assigning custom domains to any deployment.

Make sure to not include the HTTP protocol (e.g. https://) for the [custom-domain] parameter.

vercel alias set [deployment-url] [custom-domain]

vercel alias remove [custom-domain]

vercel alias list

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

The --yes option can be used to bypass the confirmation prompt when removing an alias.

vercel alias remove [custom-domain] --yes

The --limit option can be used to specify the maximum number of aliases returned when using list. The default value is 20 and the maximum is 100.

vercel alias list --limit 100

The --next option shows the next page of aliases when using list. When there are more aliases than the limit, the output includes the command for the next page. Pass the --next value from that command:

vercel alias list --next 1234567890123

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

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --token
• --version

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

You might encounter one of these errors:

• The chosen alias <xyz>.vercel.app is already in use.
• To move the domain, remove existing aliases associated with <domain>.

Check which team owns the alias before changing it. List aliases in each team you can access, using vercel switch or an explicit scope:

vercel alias list --scope your_team_slug --limit 100

The list shows aliases and their target deployments. The default limit is 20 and the maximum is 100, so an alias missing from this list isn't proof that it's available. To see the next page of aliases, add the --next option to the same command. Check the owning project's domains and deployments in the dashboard, especially for teams with more aliases than the list limit.

If you own the conflicting alias and intend to detach it, remove the alias in its owning scope:

vercel alias remove your-project.vercel.app --scope your_team_slug

Review the confirmation prompt. Removing an alias stops that hostname from serving its current deployment; you don't need to delete the deployment to remove its alias. Then retry the assignment or domain move.

If a custom domain belongs to an account you can't access, follow claiming domain ownership. You can't claim another team's vercel.app alias through DNS verification. Choose another alias or contact support if a conflict persists after removal or account deletion.