Commands
Wrangler offers a number of commands to manage your Cloudflare Workers.
docs
- Open this page in your default browser.init
- Create a new project from a variety of web frameworks and templates. (Deprecated — usenpm create cloudflare@latest
instead)generate
- Create a Wrangler project using an existing Workers template ↗.d1
- Interact with D1.vectorize
- Interact with Vectorize indexes.hyperdrive
- Manage your Hyperdrives.deploy
- Deploy your Worker to Cloudflare.dev
- Start a local server for developing your Worker.publish
- Publish your Worker to Cloudflare.delete
- Delete your Worker from Cloudflare.kv namespace
- Manage Workers KV namespaces.kv key
- Manage key-value pairs within a Workers KV namespace.kv bulk
- Manage multiple key-value pairs within a Workers KV namespace in batches.r2 bucket
- Manage Workers R2 buckets.r2 object
- Manage Workers R2 objects.secret
- Manage the secret variables for a Worker.secret:bulk
- Manage multiple secret variables for a Worker.tail
- Start a session to livestream logs from a deployed Worker.pages
- Configure Cloudflare Pages.queues
- Configure Workers Queues.login
- Authorize Wrangler with your Cloudflare account using OAuth.logout
- Remove Wrangler’s authorization for accessing your account.whoami
- Retrieve your user information and test your authentication configuration.versions
- Retrieve details for recent versions.deployments
- Retrieve details for recent deployments.rollback
- Rollback to a recent deployment.dispatch-namespace
- Interact with a dispatch namespace.mtls-certificate
- Manage certificates used for mTLS connections.types
- Generate types from bindings and module rules in configuration.
This page provides a reference for Wrangler commands.
Since Cloudflare recommends installing Wrangler locally in your project(rather than globally), the way to run Wrangler will depend on your specific setup and package manager.
You can add Wrangler commands that you use often as scripts in your project’s package.json
file:
You can then run them using your package manager of choice:
Open the Cloudflare developer documentation in your default browser.
COMMAND
string optional- The Wrangler command you want to learn more about. This opens your default browser to the section of the documentation that describes the command.
Create a new project via the create-cloudflare-cli (C3) tool. A variety of web frameworks are available to choose from as well as templates. Dependencies are installed by default, with the option to deploy your project immediately.
NAME
string optional (default: name of working directory)- The name of the Workers project. This is both the directory name and
name
property in the generatedwrangler.toml
configuration file.
- The name of the Workers project. This is both the directory name and
--yes
boolean optional- Answer yes to any prompts for new projects.
--from-dash
string optional- Fetch a Worker initialized from the dashboard. This is done by passing the flag and the Worker name.
wrangler init --from-dash <WORKER_NAME>
. - The
--from-dash
command will not automatically sync changes made to the dashboard after the command is used. Therefore, it is recommended that you continue using the CLI.
- Fetch a Worker initialized from the dashboard. This is done by passing the flag and the Worker name.
Create a new project using an existing Workers template ↗.
NAME
string optional (default: name of working directory)- The name of the Workers project. This is both the directory name and
name
property in the generatedwrangler.toml
configuration file.
- The name of the Workers project. This is both the directory name and
TEMPLATE
string optional- The URL of a GitHub template, with a default worker-template ↗. Browse a list of available templates on the cloudflare/workers-sdk ↗ repository.
Interact with Cloudflare’s D1 service.
Creates a new D1 database, and provides the binding and UUID that you will put in your wrangler.toml
file.
DATABASE_NAME
string required- The name of the new D1 database.
--location
string optional- Provide an optional location hint for your database leader.
- Available options include
weur
(Western Europe),eeur
(Eastern Europe),apac
(Asia Pacific),oc
(Oceania),wnam
(Western North America), andenam
(Eastern North America).
Get information about a D1 database, including the current database size and state.
DATABASE_NAME
string required- The name of the D1 database to get information about.
--json
boolean optional- Return output as JSON rather than a table.
List all D1 databases in your account.
--json
boolean optional- Return output as JSON rather than a table.
Delete a D1 database.
DATABASE_NAME
string required- The name of the D1 database to delete.
-y, --skip-confirmation
boolean optional- Skip deletion confirmation prompt.
Execute a query on a D1 database.
DATABASE_NAME
string required- The name of the D1 database to execute a query on.
--command
string optional- The SQL query you wish to execute.
--file
string optional- Path to the SQL file you wish to execute.
-y, --yes
boolean optional- Answer
yes
to any prompts.
- Answer
--local
boolean (default: true) optional- Execute commands/files against a local database for use with wrangler dev.
--remote
boolean (default: false) optional- Execute commands/files against a remote D1 database for use with wrangler dev —remote.
--persist-to
string optional- Specify directory to use for local persistence (for use in combination with
--local
).
- Specify directory to use for local persistence (for use in combination with
--json
boolean optional- Return output as JSON rather than a table.
--preview
boolean optional- Execute commands/files against a preview D1 database (as defined by
preview_database_id
in Wrangler.toml).
- Execute commands/files against a preview D1 database (as defined by
--batch-size
number optional- Number of queries to send in a single batch.
Export a D1 database or table’s schema and/or content to a .sql
file.
DATABASE_NAME
string required- The name of the D1 database to export.
--remote
boolean (default: false) optional- Execute commands/files against a remote D1 database for use with wrangler dev —remote.
--output
string optional- Path to the SQL file for your export.
--table
string optional- The name of the table within a D1 database to export.
--no-data
boolean (default: false) optional- Controls whether export SQL file contains database data. Note that
--no-data=true
is not recommended due to a known wrangler limitation that intreprets the value as false.
- Controls whether export SQL file contains database data. Note that
--no-schema
boolean (default: false) optional- Controls whether export SQL file contains database schema. Note that
--no-schema=true
is not recommended due to a known wrangler limitation that intreprets the value as false.
- Controls whether export SQL file contains database schema. Note that
Restore a database to a specific point-in-time using Time Travel.
DATABASE_NAME
string required- The name of the D1 database to execute a query on.
--bookmark
string optional- A D1 bookmark representing the state of a database at a specific point in time.
--timestamp
string optional- A UNIX timestamp or JavaScript date-time
string
within the last 30 days.
- A UNIX timestamp or JavaScript date-time
--json
boolean optional- Return output as JSON rather than a table.
Inspect the current state of a database for a specific point-in-time using Time Travel.
DATABASE_NAME
string required- The name of the D1 database to execute a query on.
--timestamp
string optional- A UNIX timestamp or JavaScript date-time
string
within the last 30 days.
- A UNIX timestamp or JavaScript date-time
--json
bboolean optional- Return output as JSON rather than a table.
Initiate a D1 backup.
DATABASE_NAME
string required- The name of the D1 database to backup.
List all available backups.
DATABASE_NAME
string required- The name of the D1 database to list the backups of.
Restore a backup into a D1 database.
DATABASE_NAME
string required- The name of the D1 database to restore the backup into.
BACKUP_ID
string required- The ID of the backup you wish to restore.
Download existing data to your local machine.
DATABASE_NAME
string required- The name of the D1 database you wish to download the backup of.
BACKUP_ID
string required- The ID of the backup you wish to download.
--output
string optional- The
.sqlite3
file to write to (defaults to'<DB_NAME>.<SHORT_BACKUP_ID>.sqlite3'
).
- The
Create a new migration.
This will generate a new versioned file inside the migrations
folder. Name your migration file as a description of your change. This will make it easier for you to find your migration in the migrations
folder. An example filename looks like:
0000_create_user_table.sql
The filename will include a version number and the migration name you specify below.
DATABASE_NAME
string required- The name of the D1 database you wish to create a migration for.
MIGRATION_NAME
string required- A descriptive name for the migration you wish to create.
View a list of unapplied migration files.
DATABASE_NAME
string required- The name of the D1 database you wish to list unapplied migrations for.
--local
boolean optional- Show the list of unapplied migration files on your locally persisted D1 database.
--remote
boolean (default: false) optional- Show the list of unapplied migration files on your remote D1 database.
--persist-to
string optional- Specify directory to use for local persistence (for use in combination with
--local
).
- Specify directory to use for local persistence (for use in combination with
--preview
boolean optional- Show the list of unapplied migration files on your preview D1 database (as defined by
preview_database_id
inwrangler.toml
).
- Show the list of unapplied migration files on your preview D1 database (as defined by
Apply any unapplied migrations.
This command will prompt you to confirm the migrations you are about to apply. Confirm that you would like to proceed. After, a backup will be captured.
The progress of each migration will be printed in the console.
When running the apply command in a CI/CD environment or another non-interactive command line, the confirmation step will be skipped, but the backup will still be captured.
If applying a migration results in an error, this migration will be rolled back, and the previous successful migration will remain applied.
DATABASE_NAME
string required- The name of the D1 database you wish to apply your migrations on.
--local
boolean (default: true) optional- Execute any unapplied migrations on your locally persisted D1 database.
--remote
boolean (default: false) optional- Execute any unapplied migrations on your remote D1 database.
--persist-to
string optional- Specify directory to use for local persistence (for use in combination with
--local
).
- Specify directory to use for local persistence (for use in combination with
--preview
boolean optional- Execute any unapplied migrations on your preview D1 database (as defined by
preview_database_id
inwrangler.toml
).
- Execute any unapplied migrations on your preview D1 database (as defined by
--batch-size
number optional- Number of queries to send in a single batch.
Manage Hyperdrive database configurations.
Create a new Hyperdrive configuration.
CONFIG_NAME
string required- The name of the Hyperdrive configuration to create.
--connection-string
string optional- The database connection string in the form
postgres://user:password@hostname:port/database
.
- The database connection string in the form
--host
string optional- The hostname or IP address Hyperdrive should connect to.
--port
number optional- The database port to connect to.
--scheme
string optional- The scheme used to connect to the origin database, for example, postgresql or postgres.
--database
string optional- The database (name) to connect to. For example, Postgres or defaultdb.
--user
string optional- The username used to authenticate to the database.
--password
string optional- The password used to authenticate to the database.
--access-client-id
string optional- The Client ID of the Access token to use when connecting to the origin database, must be set with a Client Access Secret. Mutually exclusive with
port
.
- The Client ID of the Access token to use when connecting to the origin database, must be set with a Client Access Secret. Mutually exclusive with
--access-client-secret
string optional- The Client Secret of the Access token to use when connecting to the origin database, must be set with a Client Access ID. Mutually exclusive with
port
.
- The Client Secret of the Access token to use when connecting to the origin database, must be set with a Client Access ID. Mutually exclusive with
--caching-disabled
boolean optional- Disables the caching of SQL responses.
--max-age
number optional- Specifies max duration for which items should persist in the cache, cannot be set when caching is disabled.
--swr
number optional- Stale While Revalidate - Indicates the number of seconds cache may serve the response after it becomes stale, cannot be set when caching is disabled.
Update an existing Hyperdrive configuration.
ID
string required- The ID of the Hyperdrive configuration to update.
--name
string optional- The new name of the Hyperdrive configuration.
--origin-host
string optional- The new database hostname or IP address Hyperdrive should connect to.
--origin-port
string optional- The new database port to connect to.
--database
string optional- The new database (name) to connect to. For example, Postgres or defaultdb.
--origin-user
string optional- The new username used to authenticate to the database.
--origin-password
string optional- The new password used to authenticate to the database.
--access-client-id
string optional- The Client ID of the Access token to use when connecting to the origin database, must be set with a Client Access Secret. Mutually exclusive with
origin-port
.
- The Client ID of the Access token to use when connecting to the origin database, must be set with a Client Access Secret. Mutually exclusive with
--access-client-secret
string optional- The Client Secret of the Access token to use when connecting to the origin database, must be set with a Client Access ID. Mutually exclusive with
origin-port
.
- The Client Secret of the Access token to use when connecting to the origin database, must be set with a Client Access ID. Mutually exclusive with
--caching-disabled
boolean optional- Disables the caching of SQL responses.
--max-age
number optional- Specifies max duration for which items should persist in the cache, cannot be set when caching is disabled.
--swr
number optional- Stale While Revalidate - Indicates the number of seconds cache may serve the response after it becomes stale, cannot be set when caching is disabled.
List all Hyperdrive configurations.
Delete an existing Hyperdrive configuration.
ID
string required- The name of the Hyperdrive configuration to delete.
Get an existing Hyperdrive configuration.
ID
string required- The name of the Hyperdrive configuration to get.
Interact with a Vectorize vector database.
Creates a new vector index, and provides the binding and name that you will put in your wrangler.toml
file.
INDEX_NAME
string required- The name of the new index to create. Must be unique for an account and cannot be changed after creation or reused after the deletion of an index.
--dimensions
number required- The vector dimension width to configure the index for. Cannot be changed after creation.
--metric
string required- The distance metric to use for calculating vector distance. Must be one of
cosine
,euclidean
, ordot-product
.
- The distance metric to use for calculating vector distance. Must be one of
--description
string optional- A description for your index.
--deprecated-v1
boolean optional- Create a legacy Vectorize index. Please note that legacy Vectorize indexes are on a deprecation path.
List all Vectorize indexes in your account, including the configured dimensions and distance metric.
--deprecated-v1
boolean optional- List legacy Vectorize indexes. Please note that legacy Vectorize indexes are on a deprecation path.
Get details about an individual index, including its configuration.
INDEX_NAME
string required- The name of the index to fetch details for.
--deprecated-v1
boolean optional- Get a legacy Vectorize index. Please note that legacy Vectorize indexes are on a deprecation path.
Get some additional information about an individual index, including the vector count and details about the last processed mutation.
INDEX_NAME
string required- The name of the index to fetch details for.
Delete a Vectorize index.
INDEX_NAME
string required- The name of the Vectorize index to delete.
--force
boolean optional- Skip confirmation when deleting the index (Note: This is not a recoverable operation).
--deprecated-v1
boolean optional- Delete a legacy Vectorize index. Please note that legacy Vectorize indexes are on a deprecation path.
Insert vectors into an index.
INDEX_NAME
string required- The name of the Vectorize index to upsert vectors in.
--file
string required- A file containing the vectors to insert in newline-delimited JSON (JSON) format.
--batch-size
number optional- The number of vectors to insert at a time (default:
1000
).
- The number of vectors to insert at a time (default:
--deprecated-v1
boolean optional- Insert into a legacy Vectorize index. Please note that legacy Vectorize indexes are on a deprecation path.
Upsert vectors into an index. Existing vectors in the index would be overwritten.
INDEX_NAME
string required- The name of the Vectorize index to upsert vectors in.
--file
string required- A file containing the vectors to insert in newline-delimited JSON (JSON) format.
--batch-size
number optional- The number of vectors to insert at a time (default:
5000
).
- The number of vectors to insert at a time (default:
Query a Vectorize index for similar vectors.
INDEX_NAME
string required- The name of the Vectorize index to query.
--vector
array required- Vector against which the Vectorize index is queried.
--top-k
number optional- The number of vectors to query (default:
5
).
- The number of vectors to query (default:
--return-values
boolean optional- Enable to return vector values in the response (default:
false
).
- Enable to return vector values in the response (default:
--return-metadata
string optional- Enable to return vector metadata in the response. Must be one of
none
,indexed
, orall
(default:none
).
- Enable to return vector metadata in the response. Must be one of
--namespace
string optional- Query response to only include vectors from this namespace.
--filter
string optional- Filter vectors based on this metadata filter. Example:
'{ 'p1': 'abc', 'p2': { '$ne': true }, 'p3': 10, 'p4': false, 'nested.p5': 'abcd' }'
- Filter vectors based on this metadata filter. Example:
Fetch vectors from a Vectorize index using the provided ids.
INDEX_NAME
string required- The name of the Vectorize index from which vectors need to be fetched.
--ids
array required- List of ids for which vectors must be fetched.
Delete vectors in a Vectorize index using the provided ids.
INDEX_NAME
string required- The name of the Vectorize index from which vectors need to be deleted.
--ids
array required- List of ids corresponding to the vectors that must be deleted.
Enable metadata filtering on the specified property.
INDEX_NAME
string required- The name of the Vectorize index for which metadata index needs to be created.
--property-name
string required- Metadata property for which metadata filtering should be enabled.
--type
string required- Data type of the property. Must be one of
string
,number
, orboolean
.
- Data type of the property. Must be one of
List metadata properties on which metadata filtering is enabled.
INDEX_NAME
string required- The name of the Vectorize index for which metadata indexes needs to be fetched.
Disable metadata filtering on the specified property.
INDEX_NAME
string required- The name of the Vectorize index for which metadata index needs to be disabled.
--property-name
string required- Metadata property for which metadata filtering should be disabled.
Start a local server for developing your Worker.