CFSQL-1406 update `wrangler d1 ... --help` output from Cloudflare Docs site #11393

alsuren · 2025-11-24T15:57:01Z

Fixes CFSQL-1406.

Describe your change...

The intention is to use the output of this in @Oxyjun's cloudflare/cloudflare-docs#26602

There are 3 commits:

copy some wrangler d1 help text from cloudflare docs site
- Specifically https://developers.cloudflare.com/d1/wrangler-commands
- I used my judgement here about which descriptions were best. Some descriptions were a bit too wordy. The output you want from --help ideally wants to be slightly more terse than what you want for a website, but compromises need to be made.
- there were a few links that I didn't copy. I will add screenshots below. I added a few to the epilogue, but I will decide whether to do the same for the rest
reorder D1 commands to match cloudflare docs site
- This is pretty un-controversial. The order on the docs site is much more sensible
- I dragged the experimental wrangler d1 insights down to the bottom.
explicitly state whether D1 commands act on local/remote by default
- I thought about doing this as "(default)" on the --local and --remote flags themselves, but that looked a bit strange, because a bunch of flags require you to also specify --local. In the end, I did this on the epilogue as a cop-out.
- paste a screenshot below of what this looks like

wrangler d1 migrations apply --help epilogue (as an example) is wrapped to 80 chars with paragraphs:

add a changeset

screenshots of things that don't look quite right (mostly relevant to @Oxyjun's other PR rather than this one)

Some of these are things that I saw when comparing https://developers.cloudflare.com/d1/wrangler-commands against the preview output of cloudflare/cloudflare-docs#26602 (I didn't manage to

The options on Cloudflare Docs renders quite nicely, but the rendered docs don't look that great (not changed in this PR)

Link to "wrangler dev". I will probably leave this as not a link.

(delete this one?)

I'm not going to tell people where the "Wrangler configuration file" is. Bit of a shame. I should check that I have been consistent.

I added For more information about Time Travel, see https://developers.cloudflare.com/d1/reference/time-travel/. I need to check how it will render in the docs.

more Wrangler configuration file

The longer descriptions are not wrapped by the CLI library, so they look a bit naff. Not sure what to do here.

the "experimental" tag is not rendered on wrangler d1 insights on Jun's PR. Probably an easy fix.
there is a duplicated wrangler d1 insights on Jun's PR. Probably leftover code that just needs to be deleted.

Tests
- Tests included
- Tests not necessary because: just docs
Public documentation
- Cloudflare docs PR(s): [D1] Using WranglerNamespace component for D1 Wrangler commands cloudflare-docs#26602
- Documentation not necessary because:
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: This is just a help text cleanup. It will also incur a whole bunch of conflicts, because of the factor to use createCommand() rather than using yargs directly. I have added the skip-v3-pr label. I can get opencode to backport the changes if you want though.

changeset-bot · 2025-11-24T15:57:06Z

🦋 Changeset detected

Latest commit: 5ef4694

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-11-24T16:01:11Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@11393

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@11393

miniflare

npm i https://pkg.pr.new/miniflare@11393

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@11393

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@11393

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@11393

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@11393

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@11393

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@11393

wrangler

npm i https://pkg.pr.new/wrangler@11393

commit: 5ef4694

…y default

github-actions · 2025-12-02T10:47:16Z

Failed to automatically backport this PR's changes to Wrangler v3. Please manually create a PR targeting the v3-maintenance branch with your changes. Thank you for helping us keep Wrangler v3 supported!

Depending on your changes, running git rebase --onto v3-maintenance main dlaban/CFSQL-1406-wrangler-docs might be a good starting point.

Notes:

your PR branch should be named v3-backport-11393
add the skip-v3-pr label to the current PR to stop this workflow from failing

Oxyjun · 2025-12-03T15:11:27Z

Nice, LTGM - thanks @alsuren ! Will tackle docs + iterate the rendering.

penalosa

I agree that this doesn't need a v3 backport, given 1) the complexity, 2) the fact there's no functional impact, and 3) we'll be stopping backports in a month or so anyway

penalosa · 2025-12-03T16:20:27Z

packages/wrangler/src/__tests__/d1/d1.test.ts


 			COMMANDS
-			  wrangler d1 list                List D1 databases
+			  wrangler d1 create <name>       Creates a new D1 database, and provides the binding and UUID that you will put in your Wrangler file.


Suggested change

wrangler d1 create <name> Creates a new D1 database, and provides the binding and UUID that you will put in your Wrangler file.

wrangler d1 create <name> Creates a new D1 database, and provides the binding and UUID that you will put in your config file

penalosa · 2025-12-03T16:20:45Z

packages/wrangler/src/__tests__/d1/d1.test.ts

 			  wrangler d1 export <name>       Export the contents or schema of your database as a .sql file
 			  wrangler d1 time-travel         Use Time Travel to restore, fork or copy a database at a specific point-in-time
 			  wrangler d1 migrations          Interact with D1 migrations
+			  wrangler d1 insights <name>     Get information about the queries run on a D1 database. [experimental]


Suggested change

wrangler d1 insights <name> Get information about the queries run on a D1 database. [experimental]

wrangler d1 insights <name> Get information about the queries run on a D1 database [experimental]

penalosa · 2025-12-03T16:21:25Z

packages/wrangler/src/d1/migrations/apply.ts

+		This command will prompt you to confirm the migrations you are about to apply.
+		Confirm that you would like to proceed. After applying, 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.
+
+		This command acts on local D1 Databases by default.


nit, but maybe indent the text by another tab for readability?

penalosa · 2025-12-03T16:22:40Z

packages/wrangler/src/d1/migrations/list.ts

+		description: "View a list of unapplied migration files",
 		status: "stable",
 		owner: "Product: D1",
+		epilogue: "This command acts on local D1 Databases by default.",


Do we want this text? Most resource commands in Wrangler are local by default, and they should all print a banner at the top of the command output saying whether it's executing locally or remotely

Quite a lot of D1 commands act remotely by default, or only remotely, so I initially added this to every command. I have now removed it from everything that says This command acts on local D1 Databases by default.

[aside: It would be nice if we could make the --local and --remote flags document themselves, but there are a bunch of strange interactions between flags where --local is kind-of the default, but then wrangler d1 execute --persist-to bombs out with Error: can't use --persist-to without --local, and I didn't want to wade into that mess right now.]

alsuren added 2 commits November 24, 2025 15:39

CFSQL-1406 copy some wrangler d1 help text from cloudflare docs site

a5bff17

CFSQL-1406 reorder D1 commands to match cloudflare docs site

950df6f

workers-devprod added this to workers-sdk Nov 24, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Nov 24, 2025

CFSQL-1406 explicitly state whether D1 commands act on local/remote b…

201ba3f

…y default

alsuren changed the title ~~Dlaban/cfsql 1406 wrangler docs~~ CFSQL-1406 update wrangler d1 ... --help output from Cloudflare Docs site Nov 24, 2025

alsuren mentioned this pull request Nov 24, 2025

[D1] Using WranglerNamespace component for D1 Wrangler commands cloudflare/cloudflare-docs#26602

Open

4 tasks

alsuren added 3 commits December 2, 2025 09:42

CFSQL-1406 use ts-dedent and wrap to 80 chars with paragraphs

8545074

CFSQL-1406 annotate local vs remote for the last 2 D1 subcommands

1211dc7

CFSQL-1406 add changeset

7e1b9dd

alsuren self-assigned this Dec 2, 2025

alsuren requested a review from Oxyjun December 2, 2025 10:31

alsuren marked this pull request as ready for review December 2, 2025 10:31

alsuren requested review from a team as code owners December 2, 2025 10:31

CFSQL-1406 update d1 --help snapshot

99a8b66

alsuren added the skip-v3-pr Skip validation of presence of a v3 backport PR label Dec 2, 2025

Oxyjun approved these changes Dec 3, 2025

View reviewed changes

joshthoward self-requested a review December 3, 2025 15:51

joshthoward approved these changes Dec 3, 2025

View reviewed changes

penalosa approved these changes Dec 3, 2025

View reviewed changes

github-project-automation bot moved this from Untriaged to Approved in workers-sdk Dec 3, 2025

alsuren added 2 commits December 3, 2025 17:23

CFSQL-1406 code review feedback

59a9716

CFSQL-1406 fix lint

5ef4694

alsuren merged commit 45480b1 into main Dec 4, 2025
40 of 44 checks passed

github-project-automation bot moved this from Approved to Done in workers-sdk Dec 4, 2025

alsuren deleted the dlaban/CFSQL-1406-wrangler-docs branch December 4, 2025 10:54

workers-devprod mentioned this pull request Dec 4, 2025

Version Packages #11511

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CFSQL-1406 update `wrangler d1 ... --help` output from Cloudflare Docs site #11393

CFSQL-1406 update `wrangler d1 ... --help` output from Cloudflare Docs site #11393

Uh oh!

alsuren commented Nov 24, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Nov 24, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Nov 24, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Dec 2, 2025

Uh oh!

Oxyjun commented Dec 3, 2025

Uh oh!

penalosa left a comment

Uh oh!

penalosa Dec 3, 2025

Uh oh!

penalosa Dec 3, 2025

Uh oh!

penalosa Dec 3, 2025

Uh oh!

penalosa Dec 3, 2025

Uh oh!

alsuren Dec 3, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	wrangler d1 create <name> Creates a new D1 database, and provides the binding and UUID that you will put in your Wrangler file.
	wrangler d1 create <name> Creates a new D1 database, and provides the binding and UUID that you will put in your config file

	wrangler d1 insights <name> Get information about the queries run on a D1 database. [experimental]
	wrangler d1 insights <name> Get information about the queries run on a D1 database [experimental]

CFSQL-1406 update wrangler d1 ... --help output from Cloudflare Docs site #11393

CFSQL-1406 update wrangler d1 ... --help output from Cloudflare Docs site #11393

Uh oh!

Conversation

alsuren commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 2, 2025

Uh oh!

Oxyjun commented Dec 3, 2025

Uh oh!

penalosa left a comment

Choose a reason for hiding this comment

Uh oh!

penalosa Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

penalosa Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

penalosa Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

penalosa Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

alsuren Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CFSQL-1406 update `wrangler d1 ... --help` output from Cloudflare Docs site #11393

CFSQL-1406 update `wrangler d1 ... --help` output from Cloudflare Docs site #11393

alsuren commented Nov 24, 2025 •

edited

Loading

changeset-bot bot commented Nov 24, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 24, 2025 •

edited

Loading