Skip to main content
For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.

npx convex deployment

Manage deployments in your project.

Syntax​

npx convex deployment [options] [command]

Subcommands​

npx convex deployment select​

Select the deployment to use when running commands.

The deployment will be used by all npx convex commands, except npx convex deploy. You can also run individual commands on another deployment by using the --deployment flag on that command.

  • Select your personal cloud dev deployment in the current project: npx convex deployment select dev
  • Select your local deployment: npx convex deployment select local
  • Select a deployment in the same project by its reference: npx convex deployment select dev/james
  • Select a deployment in another project in the same team: npx convex deployment select some-project:dev/james
  • Select a deployment in a particular team/project: npx convex deployment select some-team:some-project:dev/james

Syntax​

npx convex deployment select [options] <deployment>

Arguments​

<deployment>

The deployment to use

npx convex deployment create​

Create a new deployment for a project.

  • Create a dev deployment and select it: npx convex deployment create dev/my-new-feature --type dev --select
  • Create a prod deployment named “staging”: npx convex deployment create staging --type prod

Syntax​

npx convex deployment create [options] [reference]

Arguments​

[reference]

The reference for the new deployment, e.g. staging or dev/my-feature. Use local to create a local deployment. You can specify a team and project with team-slug:project-slug:ref (e.g. my-team:my-project:staging or my-team:my-project:local). Can be omitted when using --default.

Options​

--type <type>

Deployment type

--region <region>

Deployment region

--select

Select the new deployment. This will update the Convex environment variables in .env.local. Subsequent npx convex commands will run against this deployment.

--default

Make the new deployment your default production deployment (used by npx convex deploy) or your personal dev deployment.

--expiration <value>

When the deployment expires (e.g. "none", "in 7 days", "2026-04-01T00:00:00Z", or a UNIX timestamp in seconds or milliseconds)

npx convex deployment token​

Create and delete access tokens. Currently supports deploy keys.

Syntax​

npx convex deployment token [options] [command]

npx convex deployment token create​

Creates a deploy key that, when set as CONVEX_DEPLOY_KEY, scopes all commands to the target deployment.

  • Print a new deploy key to stdout: npx convex deployment token create my-token
  • Save a new deploy key in .env.local: npx convex deployment token create my-token --save-env
  • Save a new deploy key in a custom env file: npx convex deployment token create ci-token --save-env .env.production
  • Create a key for the project's prod: npx convex deployment token create ci-token --deployment prod

Syntax​

npx convex deployment token create [options] <name>

Arguments​

<name>

Name for the new deploy key

Options​

--save-env [path]

Save the new key as CONVEX_DEPLOY_KEY in an env file instead of printing it. Defaults to .env.local.

--prod

Create a deploy key for this project's default production deployment.

--deployment <deployment>

Create a deploy key for a specific deployment. Accepts:

  • a deployment name (e.g. joyful-capybara-123)
  • a deployment reference (e.g. dev/james, staging)
  • dev (for your personal dev deployment)
  • prod (for your project’s default production deployment)
  • local (for your local dev deployment). You can also select deployments in other projects with project-slug:reference or team-slug:project-slug:reference.

npx convex deployment token delete​

Delete an access token. Currently only deploy keys (deployment-scoped access tokens) are supported.

The positional <nameOrToken> can be the unique name of the deploy key (as passed to token create) or the deploy key value itself. The target deployment defaults to the currently-selected one; pass --deployment to target a different deployment.

  • Delete by name: npx convex deployment token delete my-token
  • Delete by value: npx convex deployment token delete 'dev:happy-animal-123|ey...'
  • Target prod: npx convex deployment token delete ci-token --deployment prod

Syntax​

npx convex deployment token delete [options] <nameOrToken>

Arguments​

<nameOrToken>

The unique name of the deploy key, or the deploy key value itself.

Options​

--prod

Delete a deploy key for this project's default production deployment.

--deployment <deployment>

Delete a deploy key for a specific deployment. Accepts:

  • a deployment name (e.g. joyful-capybara-123)
  • a deployment reference (e.g. dev/james, staging)
  • dev (for your personal dev deployment)
  • prod (for your project’s default production deployment)
  • local (for your local dev deployment). You can also select deployments in other projects with project-slug:reference or team-slug:project-slug:reference.

npx convex deployment usage​

Show usage so far in the current day and calendar month for every metric.

  • Show current usage: npx convex deployment usage
  • Print as JSON: npx convex deployment usage --json

Syntax​

npx convex deployment usage [options]

Options​

--json

Output the usage as JSON.

--prod

Show current usage for this project's default production deployment.

--deployment <deployment>

Show current usage for a specific deployment. Accepts:

  • a deployment name (e.g. joyful-capybara-123)
  • a deployment reference (e.g. dev/james, staging)
  • dev (for your personal dev deployment)
  • prod (for your project’s default production deployment)
  • local (for your local dev deployment). You can also select deployments in other projects with project-slug:reference or team-slug:project-slug:reference.

npx convex deployment usage-limits​

List and configure usage limits on your deployment.

A usage limit either warns or pauses your deployment when a metric (function calls, database bandwidth, …) crosses a threshold within a daily or monthly window. Each limit is identified by its (metric, window, type).

  • List usage limits: npx convex deployment usage-limits list
  • Create or update one: npx convex deployment usage-limits set --metric functionCalls --window day --type disable --limit 1000000
  • Delete one: npx convex deployment usage-limits remove --metric functionCalls --window day --type disable

Syntax​

npx convex deployment usage-limits [options] [command]

Options​

--prod

List and configure usage limits on this project's default production deployment.

--deployment <deployment>

List and configure usage limits on a specific deployment. Accepts:

  • a deployment name (e.g. joyful-capybara-123)
  • a deployment reference (e.g. dev/james, staging)
  • dev (for your personal dev deployment)
  • prod (for your project’s default production deployment)
  • local (for your local dev deployment). You can also select deployments in other projects with project-slug:reference or team-slug:project-slug:reference.

npx convex deployment usage-limits list​

List the usage limits configured on your deployment.

  • List all usage limits: npx convex deployment usage-limits list
  • Print as JSON: npx convex deployment usage-limits list --json

Syntax​

npx convex deployment usage-limits list [options]

Options​

--json

Output the usage limits as JSON.

npx convex deployment usage-limits set​

Create a usage limit, or update the existing one for the same (metric, window, type). At most one limit exists per combination.

  • Set the amount (creates or replaces it):
    • npx convex deployment usage-limits set --metric functionCalls --window day --type disable --limit 1000000
  • Deactivate without deleting: add --inactive (use --active to re-enable).
  • Toggle active state without changing the amount: omit --limit.

Syntax​

npx convex deployment usage-limits set [options]

Options​

--metric <metric>

The metric to limit.

--window <window>

The window the limit is measured over.

--type <type>

warning only notifies; disable pauses the deployment when exceeded.

--limit <limit>

The limit amount, in the metric's native units. Required when creating; kept as-is when omitted while updating.

--active

Enforce the limit (the default for a new limit).

--inactive

Create or leave the limit unenforced.

npx convex deployment usage-limits remove​

Delete a usage limit, identified by its (metric, window, type).

  • npx convex deployment usage-limits remove --metric functionCalls --window day --type warning

Syntax​

npx convex deployment usage-limits remove [options]

Aliases​

  • rm
  • delete

Options​

--metric <metric>

The metric to limit.

--window <window>

The window the limit is measured over.

--type <type>

warning only notifies; disable pauses the deployment when exceeded.