docs(cloudflare): add a section for CLI commands (#184)

Co-authored-by: James Anderson <[email protected]>

Author: vicb

pages/cloudflare/_meta.json

@@ -1,6 +1,7 @@
 {
   "index": "Overview",
   "get-started": "",
+  "cli": "CLI (opennextjs-cloudflare)",
   "bindings": "",
   "caching": "",
   "howtos": "How-Tos",

pages/cloudflare/bindings.mdx

@@ -53,8 +53,7 @@ To ensure that your types are always up-to-date, make sure to run `wrangler type
 
 ## Local access to bindings
 
-As presented in the [getting started](/cloudflare/get-started#12-develop-locally) your application can be both developed (`next dev`) and
-previewed (`opennextjs-cloudflare preview`) locally, in both cases bindings will be accessible from your application's code.
+As presented in the [getting started](/cloudflare/get-started#12-develop-locally) your application can be both developed (`next dev`) and [previewed locally](/cloudflare/cli#preview-command), in both cases bindings will be accessible from your application's code.
 
 Such bindings are by default local simulation that mimic the behavior of the actual Cloudflare resources.
 

pages/cloudflare/caching.mdx

@@ -585,25 +585,7 @@ export default defineCloudflareConfig({
 
 In order for the cache to be properly initialised with the build-time revalidation data, you need to run a command as part of your deploy step. This should be run as part of each deployment to ensure that the cache is being populated with each build's data.
 
-To populate remote bindings and create a new [version](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/#versions) of your application at the same time, you can use either the `deploy` command or the `upload` command. Similarly, the `preview` command will populate your local bindings and start a Wrangler dev server.
-
-```sh
-# Populate remote and deploy the worker immediately.
-opennextjs-cloudflare deploy
-
-# Populate remote and upload a new version of the worker.
-opennextjs-cloudflare upload
-
-# Populate local and start dev server.
-opennextjs-cloudflare preview
-```
-
-It is possible to only populate the cache without any other steps with the `populateCache` command.
-
-```sh
-# The target is passed as an option, either `local` or `remote`.
-opennextjs-cloudflare populateCache local
-```
+To populate remote bindings and create a new [version](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/#versions) of your application at the same time, you can use either the [`deploy`](/cloudflare/cli#deploy-command) command or the [`upload`](/cloudflare/cli#upload-command) command. Similarly, the [`preview`](/cloudflare/cli#preview-command) command will populate your local bindings and start a Wrangler dev server.
 
 </Tabs.Tab>
 <Tabs.Tab>

pages/cloudflare/cli.mdx

@@ -0,0 +1,35 @@
+import { Callout } from "nextra/components";
+
+## `opennextjs-cloudflare` CLI
+
+The Cloudflare adapter provides a `opennextjs-cloudflare` CLI to develop, build, and deploy your application. You should not use `wrangler` commands directly unless documented otherwise or if you know what you are doing.
+
+## commands
+
+`opennextjs-cloudflare` support multiple commands, invoked via `opennextjs-cloudflare <command>`.
+
+The currently supported commands are `build`, `populateCache`, `preview`, `deploy`, and `upload`.
+
+You can list the commands by invoking `pnpm opennextjs-cloudflare` and get help with a given command by invoking `pnpm opennextjs-cloudflare <command> --help`.
+
+Most commands take command specific options (i.e. `pnpm opennextjs-cloudflare build --skipNextBuild --noMinify`) and also accept wrangler options (i.e. `pnpm opennextjs-cloudflare build --config=/path/to/wrangler.jsonc --env=prod`).
+
+### `build` command
+
+It first builds the Next.js application by invoking the `build` script of the `package.json` - which typically execute `next build`. It then runs the Cloudflare specific build step to update the built files to run on the Cloudflare runtime.
+
+### `populateCache` command
+
+It populates the configured [Open Next cache components](/cloudflare/caching) so that caching works at runtime. It can populate the local bindings (`populateCache local`) used during development on your local machine or the remote bindings (`populateCache remote`) used by the deployed application. Note that this command is implicitly called by the `preview`, `deploy`, and `upload` commands so there is no need to explicitly call `populateCache` when one of those is used.
+
+### `preview` command
+
+It starts by populating the local cache and then launches a local development server (via `wrangler dev`) so that you can preview the application locally.
+
+### `deploy` command
+
+It starts by populating the remote cache and then deploys your application to Cloudflare (via `wrangler deploy`). The application will start serving as soon as it is deployed.
+
+### `upload` command
+
+It starts by populating the remote cache and then uploads a version of your application to Cloudflare (via `wrangler upload`). Note that the application will not automatically be served on uploads. See [Gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/) to learn more about how to serve an uploaded version.

pages/cloudflare/get-started.mdx

@@ -134,7 +134,7 @@ Add the following to the scripts field of your `package.json` file:
 "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts",
 ```
 
-- The `build` script must invoke the Next.js build command, it will be invoke by `opennextjs-cloudflare build`.
+- The `build` script must invoke the Next.js build command, it will be invoked by [`opennextjs-cloudflare build`](/cloudflare/cli#build-command).
 - `npm run preview`: Builds your app and serves it locally, allowing you to quickly preview your app running locally in the Workers runtime, via a single command.
 - `npm run deploy`: Builds your app, and then immediately deploys it to Cloudflare.
 - `npm run upload`: Builds your app, and then uploads a new [version](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/#versions) of it to Cloudflare.

pages/cloudflare/howtos/dev-deploy.mdx

@@ -42,15 +42,15 @@ initOpenNextCloudflareForDev();
 
 #### Use `opennextjs-cloudflare` to build and test on the Workers runtime
 
-After you've finished iterating on your Next.js application with `next dev`, you can convert it to a Cloudflare Worker by running the `opennextjs-cloudflare build` command. This will generate the Worker code in the `.open-next` directory.
+After you've finished iterating on your Next.js application with `next dev`, you can convert it to a Cloudflare Worker by running the [`opennextjs-cloudflare build` command](/cloudflare/cli#build-command). This will generate the Worker code in the `.open-next` directory.
 
 You can then preview the app locally in the Cloudflare Workers runtime.
 
-To preview your worker locally, run the `opennextjs-cloudflare preview` command. This will populate the cache and create a local server that runs your worker in the Cloudflare Workers runtime. Testing your worker is important to ensure that it has been properly built and is working as expected.
+To preview your worker locally, run the [`opennextjs-cloudflare preview` command](/cloudflare/cli#preview-command). This will populate the cache and create a local server that runs your worker in the Cloudflare Workers runtime. Testing your worker is important to ensure that it has been properly built and is working as expected.
 
 ### Deploy your application to Cloudflare Workers
 
-Both the `deploy` and `upload` commands of `opennextjs-cloudflare` can be used to deploy your application to cloudflare Workers. Both commands will initialize the remote cache and upload your application to the Cloudflare infrastructure.
+Both the [`deploy`](/cloudflare/cli#deploy-command) and [`upload`](/cloudflare/cli#upload-command) commands of `opennextjs-cloudflare` can be used to deploy your application to cloudflare Workers. Both commands will initialize the remote cache and upload your application to the Cloudflare infrastructure.
 
 While `deploy` will start serving your application as soon as it is uploaded, `upload` only creates a new version of the application so that you can use [gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/).
 
@@ -76,13 +76,3 @@ In the Build settings:
 
 - The "Build command" should be set to `npx opennextjs-cloudflare build`.
 - The "Deploy command" should be set to `npx opennextjs-cloudflare deploy` (or `upload` to use gradual deployments).
-
-<Callout type="info">
-  The `deploy`, `upload`, and `populateCache` commands of `opennextjs-cloudflare` invoke `wrangler`.
-  You can pass arguments to `wrangler` by specifying them after `--`:
-
-```sh
-opennextjs-cloudflare deploy -- --env=prod
-```
-
-</Callout>