wrangler 0.0.0-ece06ea → 0.0.0-edc4b53

package/src/index.tsx

@@ -1,10 +1,9 @@
 import React from "react";
 import { render } from "ink";
-import { Dev } from "./dev";
+import Dev from "./dev";
 import { readFile } from "node:fs/promises";
 import makeCLI from "yargs";
-import { hideBin } from "yargs/helpers";
-import type yargs from "yargs";
+import type Yargs from "yargs";
 import { findUp } from "find-up";
 import TOML from "@iarna/toml";
 import type { Config } from "./config";
@@ -25,11 +24,13 @@ import {
   putKeyValue,
   putBulkKeyValue,
   deleteBulkKeyValue,
+  createNamespace,
+  isValidNamespaceBinding,
 } from "./kv";
 
 import { pages } from "./pages";
 
-import cfetch from "./cfetch";
+import { fetchResult, fetchRaw } from "./cfetch";
 
 import publish from "./publish";
 import path from "path/posix";
@@ -42,15 +43,15 @@ import { setTimeout } from "node:timers/promises";
 import * as fs from "node:fs";
 import { execa } from "execa";
 
-async function readConfig(path?: string): Promise<Config> {
+async function readConfig(configPath?: string): Promise<Config> {
   const config: Config = {};
-  if (!path) {
-    path = await findUp("wrangler.toml");
+  if (!configPath) {
+    configPath = await findUp("wrangler.toml");
     // TODO - terminate this early instead of going all the way to the root
   }
 
-  if (path) {
-    const tml: string = await readFile(path, "utf-8");
+  if (configPath) {
+    const tml: string = await readFile(configPath, "utf-8");
     const parsed = TOML.parse(tml) as Config;
     Object.assign(config, parsed);
   }
@@ -66,7 +67,6 @@ async function readConfig(path?: string): Promise<Config> {
     "route",
     "jsx_factory",
     "jsx_fragment",
-    "polyfill_node",
     "site",
     "triggers",
     "usage_model",
@@ -80,13 +80,18 @@ async function readConfig(path?: string): Promise<Config> {
     });
   });
 
-  const mirroredFields = ["vars", "kv_namespaces", "durable_objects"];
+  const mirroredFields = [
+    "vars",
+    "kv_namespaces",
+    "durable_objects",
+    "experimental_services",
+  ];
   Object.keys(config.env || {}).forEach((env) => {
     mirroredFields.forEach((field) => {
-      // if it exists on top level, it should exist on env defns
+      // if it exists on top level, it should exist on env definitions
       Object.keys(config[field] || {}).forEach((fieldKey) => {
         if (!(fieldKey in config.env[env][field])) {
-          console.error(
+          console.warn(
             `In your configuration, "${field}.${fieldKey}" exists at a top level, but not on "env.${env}". This is not what you probably want, since the field "${field}" is not inherited by environments. Please add "${field}.${fieldKey}" to "env.${env}".`
           );
         }
@@ -94,11 +99,17 @@ async function readConfig(path?: string): Promise<Config> {
     });
   });
 
+  if ("experimental_services" in config) {
+    console.warn(
+      "The experimental_services field is only for cloudflare internal usage right now, and is subject to change. Please do not use this on production projects"
+    );
+  }
+
   // todo: validate, add defaults
   // let's just do some basics for now
 
   // @ts-expect-error we're being sneaky here for now
-  config.__path__ = path;
+  config.__path__ = configPath;
 
   return config;
 }
@@ -106,18 +117,18 @@ async function readConfig(path?: string): Promise<Config> {
 // a helper to demand one of a set of options
 // via https://github.com/yargs/yargs/issues/1093#issuecomment-491299261
 function demandOneOfOption(...options: string[]) {
-  return function (argv: yargs.Arguments) {
+  return function (argv: Yargs.Arguments) {
     const count = options.filter((option) => argv[option]).length;
     const lastOption = options.pop();
 
     if (count === 0) {
-      throw new Error(
+      throw new CommandLineArgsError(
         `Exactly one of the arguments ${options.join(
           ", "
         )} and ${lastOption} is required`
       );
     } else if (count > 1) {
-      throw new Error(
+      throw new CommandLineArgsError(
         `Arguments ${options.join(
           ", "
         )} and ${lastOption} are mutually exclusive`
@@ -128,30 +139,49 @@ function demandOneOfOption(...options: string[]) {
   };
 }
 
+class CommandLineArgsError extends Error {}
+class DeprecationError extends Error {}
+class NotImplementedError extends Error {}
+
 export async function main(argv: string[]): Promise<void> {
-  const yargs = makeCLI(hideBin(process.argv))
-    .command(
-      // the default is to simply print the help menu
-      ["*"],
-      false,
-      () => {},
-      () => {
-        yargs.showHelp("log");
+  const wrangler = makeCLI(argv)
+    // We handle errors ourselves in a try-catch around `yargs.parse`.
+    // If you want the "help info" to be displayed then throw an instance of `CommandLineArgsError`.
+    // Otherwise we just log the error that was thrown without any "help info".
+    .showHelpOnFail(false)
+    .fail((msg, error) => {
+      if (!error) {
+        // If there is only a `msg` then this came from yargs own validation, so wrap in a `CommandLineArgsError`.
+        error = new CommandLineArgsError(msg);
       }
-    )
+      throw error;
+    })
     .scriptName("wrangler")
     .wrap(null);
 
-  // you will note that we use the form for all commands where we use the builder function
-  // to define options and subcommands. Further we return the result of this builder even
-  // tho it's not completely necessary. The reason is that it's required for type inference
-  // of the args in the handle function.I wish we could enforce this pattern, but this
-  // comment will have to do for now.
+  // the default is to simply print the help menu
+  wrangler.command(
+    ["*"],
+    false,
+    () => {},
+    (args) => {
+      if (args._.length > 0) {
+        throw new CommandLineArgsError(`Unknown command: ${args._}.`);
+      } else {
+        wrangler.showHelp("log");
+      }
+    }
+  );
 
-  // also annoying that choices[] doesn't get inferred as an enum. bleh.
+  // You will note that we use the form for all commands where we use the builder function
+  // to define options and subcommands.
+  // Further we return the result of this builder even though it's not completely necessary.
+  // The reason is that it's required for type inference of the args in the handle function.
+  // I wish we could enforce this pattern, but this comment will have to do for now.
+  // (It's also annoying that choices[] doesn't get inferred as an enum. 🤷‍♂.)
 
   // [DEPRECATED] generate
-  yargs.command(
+  wrangler.command(
     // we definitely want to move away from us cloning github templates
     // we can do something better here, let's see
     "generate [name] [template]",
@@ -169,14 +199,14 @@ export async function main(argv: string[]): Promise<void> {
     },
     () => {
       // "👯 [DEPRECATED]. Scaffold a Cloudflare Workers project from a public GitHub repository.",
-      console.error(
+      throw new DeprecationError(
         "`wrangler generate` has been deprecated, please refer to TODO://some/path for alternatives"
       );
     }
   );
 
   // init
-  yargs.command(
+  wrangler.command(
     "init [name]",
     "📥 Create a wrangler.toml configuration file",
     (yargs) => {
@@ -185,26 +215,42 @@ export async function main(argv: string[]): Promise<void> {
         type: "string",
       });
     },
-    async () => {
+    async (args) => {
+      if ("type" in args) {
+        let message = "The --type option is no longer supported.";
+        if (args.type === "webpack") {
+          message +=
+            "\nIf you wish to use webpack then you will need to create a custom build.";
+          // TODO: Add a link to docs
+        }
+        throw new CommandLineArgsError(message);
+      }
+
       const destination = path.join(process.cwd(), "wrangler.toml");
       if (fs.existsSync(destination)) {
-        console.error(`${destination} already exists.`);
-      } else {
-        const compatibilityDate = new Date().toISOString().substring(0, 10);
-        try {
-          await writeFile(
-            destination,
-            `compatibility_date = "${compatibilityDate}"` + "\n"
-          );
-          console.log(`✨ Succesfully created wrangler.toml`);
-          // TODO: suggest next steps?
-        } catch (err) {
-          console.error(`Failed to create wrangler.toml`);
-          console.error(err);
-          throw err;
+        console.warn(`${destination} file already exists!`);
+        const result = await confirm(
+          "Do you want to continue initializing this project?"
+        );
+        if (!result) {
+          return;
         }
       }
 
+      const compatibilityDate = new Date().toISOString().substring(0, 10);
+      try {
+        await writeFile(
+          destination,
+          `compatibility_date = "${compatibilityDate}"` + "\n"
+        );
+        console.log(`✨ Successfully created wrangler.toml`);
+        // TODO: suggest next steps?
+      } catch (err) {
+        throw new Error(
+          `Failed to create wrangler.toml.\n${err.message ?? err}`
+        );
+      }
+
       // if no package.json, ask, and if yes, create one
       let pathToPackageJson = await findUp("package.json");
 
@@ -241,9 +287,17 @@ export async function main(argv: string[]): Promise<void> {
             JSON.stringify(
               {
                 compilerOptions: {
-                  target: "ES2020",
-                  module: "CommonJS",
-                  lib: ["ES2020"],
+                  target: "esnext",
+                  module: "esnext",
+                  moduleResolution: "node",
+                  esModuleInterop: true,
+                  allowJs: true,
+                  allowSyntheticDefaultImports: true,
+                  isolatedModules: true,
+                  noEmit: true,
+                  lib: ["esnext"],
+                  jsx: "react",
+                  resolveJsonModule: true,
                   types: ["@cloudflare/workers-types"],
                 },
               },
@@ -266,7 +320,7 @@ export async function main(argv: string[]): Promise<void> {
   );
 
   // build
-  yargs.command(
+  wrangler.command(
     "build",
     false,
     (yargs) => {
@@ -276,14 +330,14 @@ export async function main(argv: string[]): Promise<void> {
     },
     () => {
       // "[DEPRECATED] 🦀 Build your project (if applicable)",
-      console.error(
+      throw new DeprecationError(
         "`wrangler build` has been deprecated, please refer to TODO://some/path for alternatives"
       );
     }
   );
 
   // login
-  yargs.command(
+  wrangler.command(
     // this needs scopes as an option?
     "login",
     false, // we don't need to show this in the menu
@@ -320,13 +374,13 @@ export async function main(argv: string[]): Promise<void> {
       await login();
 
       // TODO: would be nice if it optionally saved login
-      // creds inside node_modules/.cache or something
+      // credentials inside node_modules/.cache or something
       // this way you could have multiple users on a single machine
     }
   );
 
   // logout
-  yargs.command(
+  wrangler.command(
     // this needs scopes as an option?
     "logout",
     false, // we don't need to show this in the menu
@@ -338,7 +392,7 @@ export async function main(argv: string[]): Promise<void> {
   );
 
   // whoami
-  yargs.command(
+  wrangler.command(
     "whoami",
     false, // we don't need to show this the menu
     // "🕵️  Retrieve your user info and test your auth config",
@@ -349,20 +403,20 @@ export async function main(argv: string[]): Promise<void> {
   );
 
   // config
-  yargs.command(
+  wrangler.command(
     "config",
     false,
     () => {},
     () => {
       // "🕵️  Authenticate Wrangler with a Cloudflare API Token",
-      console.error(
+      throw new DeprecationError(
         "`wrangler config` has been deprecated, please refer to TODO://some/path for alternatives"
       );
     }
   );
 
   // dev
-  yargs.command(
+  wrangler.command(
     "dev <filename>",
     "👂 Start a local server for developing your worker",
     (yargs) => {
@@ -381,6 +435,20 @@ export async function main(argv: string[]): Promise<void> {
           type: "string",
           // TODO: get choices for the toml file?
         })
+        .option("compatibility-date", {
+          describe: "Date to use for compatibility checks",
+          type: "string",
+        })
+        .option("compatibility-flags", {
+          describe: "Flags to use for compatibility checks",
+          type: "array",
+          alias: "compatibility-flag",
+        })
+        .option("latest", {
+          describe: "Use the latest version of the worker runtime",
+          type: "boolean",
+          default: true,
+        })
         .option("ip", {
           describe: "IP address to listen on",
           type: "string",
@@ -401,7 +469,7 @@ export async function main(argv: string[]): Promise<void> {
           describe: "Protocol to listen to requests on, defaults to http.",
           choices: ["http", "https"],
         })
-        .option("public", {
+        .option("experimental-public", {
           describe: "Static assets to be served",
           type: "string",
         })
@@ -422,16 +490,24 @@ export async function main(argv: string[]): Promise<void> {
         .option("jsx-fragment", {
           describe: "The function that is called for each JSX fragment",
           type: "string",
-        })
-        .option("polyfill-node", {
-          describe: "Try to polyfill node builtins",
-          type: "boolean",
         });
     },
     async (args) => {
       const { filename, format } = args;
       const config = args.config as Config;
 
+      if (args["experimental-public"]) {
+        console.warn(
+          "🚨  The --experimental-public field is experimental and will change in the future."
+        );
+      }
+
+      if (args.public) {
+        throw new Error(
+          "🚨  The --public field has been renamed to --experimental-public, and will change behaviour in the future."
+        );
+      }
+
       // -- snip, extract --
 
       if (!args.local) {
@@ -444,8 +520,7 @@ export async function main(argv: string[]): Promise<void> {
         if (!config.account_id) {
           config.account_id = await getAccountId();
           if (!config.account_id) {
-            console.error("No account id found, quitting...");
-            return;
+            throw new Error("No account id found, quitting...");
           }
         }
       }
@@ -454,17 +529,22 @@ export async function main(argv: string[]): Promise<void> {
 
       const envRootObj = args.env ? config.env[args.env] || {} : config;
 
-      const polyfillNode = args["polyfill-node"] ?? config.polyfill_node;
-      if (polyfillNode) {
-        console.warn(
-          "Using polyfills for node builtin modules. These are not meant to be completely reliable, and have serious tradeoffs. Please see https://github.com/ionic-team/rollup-plugin-node-polyfills/ for more details."
-        );
+      // TODO: this error shouldn't actually happen,
+      // but we haven't fixed it internally yet
+      if ("durable_objects" in envRootObj) {
+        if (!(args.name || config.name)) {
+          console.warn(
+            'A worker with durable objects needs to be named, or it may not work as expected. Add a "name" into wrangler.toml, or pass it in the command line with --name.'
+          );
+        }
+        // TODO: if not already published, publish a draft worker
       }
 
-      render(
+      const { waitUntilExit } = render(
         <Dev
           name={args.name || config.name}
-          entry={filename}
+          entry={path.relative(process.cwd(), filename)}
+          buildCommand={config.build || {}}
           format={format}
           initialMode={args.local ? "local" : "remote"}
           jsxFactory={args["jsx-factory"] || envRootObj?.jsx_factory}
@@ -472,40 +552,51 @@ export async function main(argv: string[]): Promise<void> {
           accountId={config.account_id}
           site={args.site || config.site?.bucket}
           port={args.port || config.dev?.port}
-          polyfillNode={polyfillNode}
-          public={args.public}
-          compatibilityDate={config.compatibility_date}
-          compatibilityFlags={config.compatibility_flags}
+          public={args["experimental-public"]}
+          compatibilityDate={
+            args["compatibility-date"] ||
+            config.compatibility_date ||
+            new Date().toISOString().substring(0, 10)
+          }
+          compatibilityFlags={
+            (args["compatibility-flags"] as string[]) ||
+            config.compatibility_flags
+          }
           usageModel={config.usage_model}
-          variables={{
-            ...(envRootObj?.vars || {}),
-            ...(envRootObj?.kv_namespaces || []).reduce(
-              (obj, { binding, preview_id }) => {
+          bindings={{
+            kv_namespaces: envRootObj.kv_namespaces?.map(
+              ({ binding, preview_id, id: _id }) => {
+                // In `dev`, we make folks use a separate kv namespace called
+                // `preview_id` instead of `id` so that they don't
+                // break production data. So here we check that a `preview_id`
+                // has actually been configured.
+                // This whole block of code will be obsoleted in the future
+                // when we have copy-on-write for previews on edge workers.
                 if (!preview_id) {
                   // TODO: This error has to be a _lot_ better, ideally just asking
                   // to create a preview namespace for the user automatically
                   throw new Error(
-                    "kv namespaces need a preview id during dev mode"
-                  );
+                    `In development, you should use a separate kv namespace than the one you'd use in production. Please create a new kv namespace with "wrangler kv:namespace create <name> --preview" and add its id as preview_id to the kv_namespace "${binding}" in your wrangler.toml`
+                  ); // Ugh, I really don't like this message very much
                 }
-                return { ...obj, [binding]: { namespaceId: preview_id } };
-              },
-              {}
-            ),
-            ...(envRootObj?.durable_objects?.bindings || []).reduce(
-              (obj, { name, class_name, script_name }) => {
-                return { ...obj, [name]: { class_name, script_name } };
-              },
-              {}
+                return {
+                  binding,
+                  id: preview_id,
+                };
+              }
             ),
+            vars: envRootObj.vars,
+            durable_objects: envRootObj.durable_objects,
+            services: envRootObj.experimental_services,
           }}
         />
       );
+      await waitUntilExit();
     }
   );
 
   // publish
-  yargs.command(
+  wrangler.command(
     "publish [script]",
     "🆙 Publish your Worker to Cloudflare.",
     (yargs) => {
@@ -522,7 +613,21 @@ export async function main(argv: string[]): Promise<void> {
           describe: "name to use when uploading",
           type: "string",
         })
-        .option("public", {
+        .option("compatibility-date", {
+          describe: "Date to use for compatibility checks",
+          type: "string",
+        })
+        .option("compatibility-flags", {
+          describe: "Flags to use for compatibility checks",
+          type: "array",
+          alias: "compatibility-flag",
+        })
+        .option("latest", {
+          describe: "Use the latest version of the worker runtime",
+          type: "boolean",
+          default: false,
+        })
+        .option("experimental-public", {
           describe: "Static assets to be served",
           type: "string",
         })
@@ -553,19 +658,34 @@ export async function main(argv: string[]): Promise<void> {
         .option("jsx-fragment", {
           describe: "The function that is called for each JSX fragment",
           type: "string",
-        })
-        .option("polyfill-node", {
-          describe: "Try to polyfill node builtins",
-          type: "boolean",
         });
     },
     async (args) => {
       if (args.local) {
-        console.error("🚫  Local publishing is not yet supported");
-        return;
+        throw new NotImplementedError(
+          "🚫  Local publishing is not yet supported"
+        );
+      }
+
+      if (args["experimental-public"]) {
+        console.warn(
+          "🚨  The --experimental-public field is experimental and will change in the future."
+        );
+      }
+      if (args.public) {
+        throw new Error(
+          "🚨  The --public field has been renamed to --experimental-public, and will change behaviour in the future."
+        );
       }
+
       const config = args.config as Config;
 
+      if (args.latest) {
+        console.warn(
+          "⚠️  Using the latest version of the Workers runtime. To silence this warning, please choose a specific version of the runtime with --compatibility-date, or add a compatibility_date to your wrangler.toml.\n"
+        );
+      }
+
       // -- snip, extract --
       if (!args.local) {
         const loggedIn = await loginOrRefreshIfRequired();
@@ -577,39 +697,34 @@ export async function main(argv: string[]): Promise<void> {
         if (!config.account_id) {
           config.account_id = await getAccountId();
           if (!config.account_id) {
-            console.error("No account id found, quitting...");
-            return;
+            throw new Error("No account id found, quitting...");
           }
         }
       }
 
       // -- snip, end --
 
-      const polyfillNode = args["polyfill-node"] ?? config.polyfill_node;
-      if (polyfillNode) {
-        console.warn(
-          "Using polyfills for node builtin modules. These are not meant to be completely reliable, and have serious tradeoffs. Please see https://github.com/ionic-team/rollup-plugin-node-polyfills/ for more details."
-        );
-      }
-
       await publish({
         config: args.config as Config,
         name: args.name,
         script: args.script,
         env: args.env,
+        compatibilityDate: args.latest
+          ? new Date().toISOString().substring(0, 10)
+          : args["compatibility-date"],
+        compatibilityFlags: args["compatibility-flags"] as string[],
         triggers: args.triggers,
         jsxFactory: args["jsx-factory"],
         jsxFragment: args["jsx-fragment"],
-        polyfillNode: args["polyfill-node"],
         routes: args.routes,
-        public: args.public,
+        public: args["experimental-public"],
         site: args.site,
       });
     }
   );
 
   // tail
-  yargs.command(
+  wrangler.command(
     "tail [name]",
     "🦚 Starts a log tailing session for a deployed Worker.",
     (yargs) => {
@@ -656,8 +771,7 @@ export async function main(argv: string[]): Promise<void> {
       const config = args.config as Config;
 
       if (!(args.name || config.name)) {
-        console.error("Missing script name");
-        return;
+        throw new Error("Missing script name");
       }
       const scriptName = `${args.name || config.name}${
         args.env ? `-${args.env}` : ""
@@ -675,8 +789,7 @@ export async function main(argv: string[]): Promise<void> {
         if (!config.account_id) {
           config.account_id = await getAccountId();
           if (!config.account_id) {
-            console.error("No account id found, quitting...");
-            return;
+            throw new Error("No account id found, quitting...");
           }
         }
       }
@@ -700,9 +813,9 @@ export async function main(argv: string[]): Promise<void> {
         `successfully created tail, expires at ${expiration.toLocaleString()}`
       );
 
-      onExit(() => {
+      onExit(async () => {
         tail.terminate();
-        deleteTail();
+        await deleteTail();
       });
 
       tail.on("message", (data) => {
@@ -727,7 +840,7 @@ export async function main(argv: string[]): Promise<void> {
   );
 
   // preview
-  yargs.command(
+  wrangler.command(
     "preview [method] [body]",
     false,
     (yargs) => {
@@ -753,20 +866,20 @@ export async function main(argv: string[]): Promise<void> {
         });
     },
     () => {
-      // "🔬 [DEPRECATED] Preview your code temporarily on cloudflareworkers.com"
-      console.error(
+      // "🔬 [DEPRECATED] Preview your code temporarily on https://cloudflareworkers.com"
+      throw new DeprecationError(
         "`wrangler preview` has been deprecated, please refer to TODO://some/path for alternatives"
       );
     }
   );
 
   // route
-  yargs.command(
+  wrangler.command(
     "route",
     false, // I think we want to hide this command
     // "➡️  List or delete worker routes",
-    (yargs) => {
-      return yargs
+    (routeYargs) => {
+      return routeYargs
         .command(
           "list",
           "List a route associated with a zone",
@@ -790,11 +903,10 @@ export async function main(argv: string[]): Promise<void> {
             // TODO: use environment (current wrangler doesn't do so?)
             const zone = args.zone || (args.config as Config).zone_id;
             if (!zone) {
-              console.error("missing zone id");
-              return;
+              throw new Error("missing zone id");
             }
 
-            console.log(await cfetch(`/zones/${zone}/workers/routes`));
+            console.log(await fetchResult(`/zones/${zone}/workers/routes`));
           }
         )
         .command(
@@ -824,7 +936,7 @@ export async function main(argv: string[]): Promise<void> {
             }
 
             console.log(
-              await cfetch(`/zones/${zone}/workers/routes/${args.id}`, {
+              await fetchResult(`/zones/${zone}/workers/routes/${args.id}`, {
                 method: "DELETE",
               })
             );
@@ -834,7 +946,7 @@ export async function main(argv: string[]): Promise<void> {
   );
 
   // subdomain
-  yargs.command(
+  wrangler.command(
     "subdomain [name]",
     false,
     // "👷 Create or change your workers.dev subdomain.",
@@ -842,18 +954,18 @@ export async function main(argv: string[]): Promise<void> {
       return yargs.positional("name", { type: "string" });
     },
     () => {
-      console.error(
+      throw new DeprecationError(
         "`wrangler subdomain` has been deprecated, please refer to TODO://some/path for alternatives"
       );
     }
   );
 
   // secret
-  yargs.command(
+  wrangler.command(
     "secret",
     "🤫 Generate a secret that can be referenced in the worker script",
-    (yargs) => {
-      return yargs
+    (secretYargs) => {
+      return secretYargs
         .command(
           "put <key>",
           "Create or update a secret variable for a script",
@@ -875,16 +987,16 @@ export async function main(argv: string[]): Promise<void> {
           },
           async (args) => {
             if (args.local) {
-              console.error("--local not implemented for this command yet");
-              return;
+              throw new NotImplementedError(
+                "--local not implemented for this command yet"
+              );
             }
             const config = args.config as Config;
 
             // TODO: use environment (how does current wrangler do it?)
             const scriptName = args.name || config.name;
             if (!scriptName) {
-              console.error("Missing script name");
-              return;
+              throw new Error("Missing script name");
             }
 
             // -- snip, extract --
@@ -899,8 +1011,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -912,7 +1023,7 @@ export async function main(argv: string[]): Promise<void> {
               "password"
             );
             async function submitSecret() {
-              return await cfetch(
+              return await fetchResult(
                 `/accounts/${config.account_id}/workers/scripts/${scriptName}/secrets/`,
                 {
                   method: "PUT",
@@ -931,7 +1042,7 @@ export async function main(argv: string[]): Promise<void> {
             } catch (e) {
               if (e.code === 10007) {
                 // upload a draft worker
-                await cfetch(
+                await fetchResult(
                   `/accounts/${config.account_id}/workers/scripts/${scriptName}`,
                   {
                     method: "PUT",
@@ -942,7 +1053,11 @@ export async function main(argv: string[]): Promise<void> {
                         content: `export default { fetch() {} }`,
                         type: "esm",
                       },
-                      variables: {},
+                      bindings: {
+                        kv_namespaces: [],
+                        vars: {},
+                        durable_objects: { bindings: [] },
+                      },
                       modules: [],
                     }),
                   }
@@ -976,8 +1091,9 @@ export async function main(argv: string[]): Promise<void> {
           },
           async (args) => {
             if (args.local) {
-              console.error("--local not implemented for this command yet");
-              return;
+              throw new NotImplementedError(
+                "--local not implemented for this command yet"
+              );
             }
             const config = args.config as Config;
 
@@ -999,8 +1115,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -1013,7 +1128,7 @@ export async function main(argv: string[]): Promise<void> {
               );
 
               console.log(
-                await cfetch(
+                await fetchResult(
                   `/accounts/${config.account_id}/workers/scripts/${scriptName}/secrets/${args.key}`,
                   { method: "DELETE" }
                 )
@@ -1038,16 +1153,16 @@ export async function main(argv: string[]): Promise<void> {
           },
           async (args) => {
             if (args.local) {
-              console.error("--local not implemented for this command yet");
-              return;
+              throw new NotImplementedError(
+                "--local not implemented for this command yet"
+              );
             }
             const config = args.config as Config;
 
             // TODO: use environment (how does current wrangler do it?)
             const scriptName = args.name || config.name;
             if (!scriptName) {
-              console.error("Missing script name");
-              return;
+              throw new Error("Missing script name");
             }
 
             // -- snip, extract --
@@ -1062,8 +1177,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -1071,7 +1185,7 @@ export async function main(argv: string[]): Promise<void> {
             // -- snip, end --
 
             console.log(
-              await cfetch(
+              await fetchResult(
                 `/accounts/${config.account_id}/workers/scripts/${scriptName}/secrets`
               )
             );
@@ -1082,11 +1196,11 @@ export async function main(argv: string[]): Promise<void> {
 
   // kv
   // :namespace
-  yargs.command(
+  wrangler.command(
     "kv:namespace",
     "🗂️  Interact with your Workers KV Namespaces",
-    (yargs) => {
-      return yargs
+    (namespaceYargs) => {
+      return namespaceYargs
         .command(
           "create <namespace>",
           "Create a new namespace",
@@ -1106,13 +1220,19 @@ export async function main(argv: string[]): Promise<void> {
               });
           },
           async (args) => {
-            if (args._.length !== 2) {
-              throw new Error(
-                `Did you forget to add quotes around "${
-                  args.namespace
-                } ${args._.slice(2).join(" ")}"?`
+            if (args._.length > 2) {
+              const extraArgs = args._.slice(2).join(" ");
+              throw new CommandLineArgsError(
+                `Unexpected additional positional arguments "${extraArgs}".`
               );
             }
+
+            if (!isValidNamespaceBinding(args.namespace)) {
+              throw new CommandLineArgsError(
+                `The namespace binding name "${args.namespace}" is invalid. It can only have alphanumeric and _ characters, and cannot begin with a number.`
+              );
+            }
+
             const config = args.config as Config;
             if (!config.name) {
               console.warn(
@@ -1120,13 +1240,10 @@ export async function main(argv: string[]): Promise<void> {
               );
             }
 
-            const title = `${config.name || "worker"}${
-              args.env ? `-${args.env}` : ""
-            }-${args.namespace}${args.preview ? "_preview" : ""}`;
-
-            if (/[\W]+/.test(args.namespace)) {
-              throw new Error("invalid binding name, needs to be js friendly");
-            }
+            const name = config.name || "worker";
+            const environment = args.env ? `-${args.env}` : "";
+            const preview = args.preview ? "_preview" : "";
+            const title = `${name}${environment}-${args.namespace}${preview}`;
 
             if (args.local) {
               const { Miniflare } = await import("miniflare");
@@ -1135,7 +1252,7 @@ export async function main(argv: string[]): Promise<void> {
                 // TODO: these options shouldn't be required
                 script: ` `, // has to be a string with at least one char
               });
-              mf.getKVNamespace(title); // this should "create" the namespace
+              await mf.getKVNamespace(title); // this should "create" the namespace
               console.log(`✨ Success! Created KV namespace ${title}`);
               return;
             }
@@ -1152,8 +1269,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -1163,31 +1279,19 @@ export async function main(argv: string[]): Promise<void> {
             // TODO: generate a binding name stripping non alphanumeric chars
 
             console.log(`🌀 Creating namespace with title "${title}"`);
-
-            const response = await cfetch<{ id: string }>(
-              `/accounts/${config.account_id}/storage/kv/namespaces`,
-              {
-                method: "POST",
-                headers: {
-                  "Content-Type": "application/json",
-                },
-                body: JSON.stringify({
-                  title,
-                }),
-              }
-            );
+            const namespaceId = await createNamespace(config.account_id, title);
 
             console.log("✨ Success!");
+            const envString = args.env ? ` under [env.${args.env}]` : "";
+            const previewString = args.preview ? "preview_" : "";
             console.log(
-              `Add the following to your configuration file in your kv_namespaces array${
-                args.env ? ` under [env.${args.env}]` : ""
-              }:`
+              `Add the following to your configuration file in your kv_namespaces array${envString}:`
             );
             console.log(
-              `{ binding = "${args.namespace}", ${
-                args.preview ? "preview_" : ""
-              }id = "${response.id}" }`
+              `{ binding = "${args.namespace}", ${previewString}id = "${namespaceId}" }`
             );
+
+            // TODO: automatically write this block to the wrangler.toml config file??
           }
         )
         .command(
@@ -1196,8 +1300,9 @@ export async function main(argv: string[]): Promise<void> {
           {},
           async (args) => {
             if (args.local) {
-              console.error(`local mode is not yet supported for this command`);
-              return;
+              throw new NotImplementedError(
+                `local mode is not yet supported for this command`
+              );
             }
 
             const config = args.config as Config;
@@ -1214,8 +1319,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -1258,21 +1362,19 @@ export async function main(argv: string[]): Promise<void> {
           },
           async (args) => {
             if (args.local) {
-              console.error(`local mode is not yet supported for this command`);
-              return;
+              throw new NotImplementedError(
+                `local mode is not yet supported for this command`
+              );
             }
             const config = args.config as Config;
 
-            const id =
-              args["namespace-id"] ||
-              (args.env
-                ? config.env[args.env] || {}
-                : config
-              ).kv_namespaces.find(
-                (namespace) => namespace.binding === args.binding
-              )[args.preview ? "preview_id" : "id"];
-            if (!id) {
-              throw new Error("Are you sure? id not found");
+            let id;
+            try {
+              id = getNamespaceId(args);
+            } catch (e) {
+              throw new CommandLineArgsError(
+                "Not able to delete namespace.\n" + e.message
+              );
             }
 
             // -- snip, extract --
@@ -1288,15 +1390,14 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
 
             // -- snip, end --
 
-            await cfetch<{ id: string }>(
+            await fetchResult<{ id: string }>(
               `/accounts/${config.account_id}/storage/kv/namespaces/${id}`,
               { method: "DELETE" }
             );
@@ -1324,13 +1425,13 @@ export async function main(argv: string[]): Promise<void> {
   );
 
   // :key
-  yargs.command(
+  wrangler.command(
     "kv:key",
     "🔑 Individually manage Workers KV key-value pairs",
-    (yargs) => {
-      return yargs
+    (kvKeyYargs) => {
+      return kvKeyYargs
         .command(
-          "put <key> <value>",
+          "put <key> [value]",
           "Writes a single key/value pair to the given namespace.",
           (yargs) => {
             return yargs
@@ -1371,7 +1472,8 @@ export async function main(argv: string[]): Promise<void> {
               .option("path", {
                 type: "string",
                 describe: "Read value from the file at a given path.",
-              });
+              })
+              .check(demandOneOfOption("value", "path"));
           },
           async ({ key, ttl, expiration, ...args }) => {
             const namespaceId = getNamespaceId(args);
@@ -1380,7 +1482,16 @@ export async function main(argv: string[]): Promise<void> {
               : args.value;
             const config = args.config as Config;
 
-            console.log(`writing ${key}=${value} to namespace ${namespaceId}`);
+            if (args.path) {
+              console.log(
+                `writing the contents of ${args.path} to the key "${key}" on namespace ${namespaceId}`
+              );
+            } else {
+              console.log(
+                `writing the value "${value}" to key "${key}" on namespace ${namespaceId}`
+              );
+            }
+
             if (args.local) {
               const { Miniflare } = await import("miniflare");
               const mf = new Miniflare({
@@ -1405,8 +1516,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -1437,6 +1547,12 @@ export async function main(argv: string[]): Promise<void> {
                 type: "string",
                 describe: "Perform on a specific environment",
               })
+              .option("preview", {
+                type: "boolean",
+                // In the case of listing keys we will default to non-preview mode
+                default: false,
+                describe: "Interact with a preview namespace",
+              })
               .option("prefix", {
                 type: "string",
                 describe: "A prefix to filter listed keys",
@@ -1474,8 +1590,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -1512,6 +1627,12 @@ export async function main(argv: string[]): Promise<void> {
               .option("preview", {
                 type: "boolean",
                 describe: "Interact with a preview namespace",
+              })
+              .option("preview", {
+                type: "boolean",
+                // In the case of getting key values we will default to non-preview mode
+                default: false,
+                describe: "Interact with a preview namespace",
               });
           },
           async ({ key, ...args }) => {
@@ -1543,20 +1664,15 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
 
             // -- snip, end --
 
-            // annoyingly, the API for this one doesn't return the
-            // data in the 'standard' format. goddamit.
-            // That's why we have the fallthrough response in cfetch.
-            // Oh well.
             console.log(
-              await cfetch(
+              await fetchRaw(
                 `/accounts/${config.account_id}/storage/kv/namespaces/${namespaceId}/values/${key}`
               )
             );
@@ -1592,6 +1708,10 @@ export async function main(argv: string[]): Promise<void> {
           async ({ key, ...args }) => {
             const namespaceId = getNamespaceId(args);
 
+            console.log(
+              `deleting the key "${key}" on namespace ${namespaceId}`
+            );
+
             if (args.local) {
               const { Miniflare } = await import("miniflare");
               const mf = new Miniflare({
@@ -1619,15 +1739,14 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
 
             // -- snip, end --
 
-            await cfetch(
+            await fetchResult(
               `/accounts/${config.account_id}/storage/kv/namespaces/${namespaceId}/values/${key}`,
               { method: "DELETE" }
             );
@@ -1637,11 +1756,11 @@ export async function main(argv: string[]): Promise<void> {
   );
 
   // :bulk
-  yargs.command(
+  wrangler.command(
     "kv:bulk",
     "💪 Interact with multiple Workers KV key-value pairs at once",
-    (yargs) => {
-      return yargs
+    (kvBulkYargs) => {
+      return kvBulkYargs
         .command(
           "put <filename>",
           "Upload multiple key-value pairs to a namespace",
@@ -1681,8 +1800,9 @@ export async function main(argv: string[]): Promise<void> {
             try {
               parsedContent = JSON.parse(content);
             } catch (err) {
-              console.error(`could not parse json from ${filename}`);
-              throw err;
+              throw new Error(
+                `Could not parse json from ${filename}.\n${err.message ?? err}`
+              );
             }
 
             if (args.local) {
@@ -1721,8 +1841,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -1769,8 +1888,9 @@ export async function main(argv: string[]): Promise<void> {
             try {
               parsedContent = JSON.parse(content);
             } catch (err) {
-              console.error(`could not parse json from ${filename}`);
-              throw err;
+              throw new Error(
+                `Could not parse json from ${filename}.\n${err.message ?? err}`
+              );
             }
 
             if (args.local) {
@@ -1801,8 +1921,7 @@ export async function main(argv: string[]): Promise<void> {
               if (!config.account_id) {
                 config.account_id = await getAccountId();
                 if (!config.account_id) {
-                  console.error("No account id found, quitting...");
-                  return;
+                  throw new Error("No account id found, quitting...");
                 }
               }
             }
@@ -1817,10 +1936,11 @@ export async function main(argv: string[]): Promise<void> {
     }
   );
 
-  yargs.command("pages", "⚡️ Configure Cloudflare Pages", pages);
+  wrangler.command("pages", "⚡️ Configure Cloudflare Pages", pages);
 
-  yargs
+  wrangler
     .option("config", {
+      alias: "c",
       describe: "Path to .toml configuration file",
       type: "string",
       async coerce(arg) {
@@ -1828,18 +1948,27 @@ export async function main(argv: string[]): Promise<void> {
       },
     })
     .option("local", {
+      alias: "l",
       describe: "Run on my machine",
       type: "boolean",
       default: false, // I bet this will a point of contention. We'll revisit it.
     });
 
-  yargs.group(["config", "help", "version"], "Flags:");
-  yargs.version(wranglerVersion);
+  wrangler.group(["config", "help", "version"], "Flags:");
+  wrangler.help().alias("h", "help");
+  wrangler.version(wranglerVersion).alias("v", "version");
+  wrangler.exitProcess(false);
+
   await initialiseUserConfig();
 
-  await yargs.parse(argv, (err, argv, output) => {
-    if (output) {
-      console.log(output);
+  try {
+    await wrangler.parse();
+  } catch (e) {
+    if (e instanceof CommandLineArgsError) {
+      wrangler.showHelp("error");
+      console.error(""); // Just adds a bit of space
     }
-  });
+    console.error(e.message);
+    throw e;
+  }
 }