Document Snaps sandbox and update CLI docs

Author: alexandratran

docs/whats-new.md

@@ -11,6 +11,8 @@ of the [MetaMask developer page](https://metamask.io/developer/).
 
 ## May 2025
 
+- Documented [how to use the Snaps sandbox](/snaps/how-to/test-a-snap/#test-in-the-sandbox).
+  ([#2030](https://github.com/MetaMask/metamask-docs/pull/2030))
 - Documented how to use the SDK CLI to set up a [JavaScript + Wagmi](/sdk/quickstart/javascript-wagmi) or [Dynamic SDK](/sdk/quickstart/javascript-dynamic) project.
   ([#2010](https://github.com/MetaMask/metamask-docs/pull/2010))
 - Documented [how to send batch transactions via EIP-5792 and EIP-7702](/wallet/how-to/send-transactions/send-batch-transactions).

snaps/how-to/debug-a-snap/common-issues.md

@@ -60,9 +60,9 @@ plugins for several other build systems:
 For examples on how to set up these build systems yourself, see the
 [examples](https://github.com/MetaMask/snaps/tree/main/packages/examples).
 
-We recommend running [`yarn mm-snap manifest --fix`](../../reference/cli/subcommands.md#m-manifest)
+We recommend running [`yarn mm-snap manifest --fix`](../../reference/cli.md#m-manifest)
 after creating your bundle to make sure your manifest `shasum` value is correct.
-You might also benefit from running [`yarn mm-snap eval`](../../reference/cli/subcommands.md#e-eval)
+You might also benefit from running [`yarn mm-snap eval`](../../reference/cli.md#e-eval)
 to detect any SES issues up front.
 
 ## Patch dependencies

snaps/how-to/debug-a-snap/index.md

@@ -11,7 +11,7 @@ You can also see the [common issues](common-issues.md) encountered by Snap devel
 :::
 
 You can add your log statements in your source code and build your Snap, or add them directly
-to your Snap bundle and use [`yarn mm-snap manifest --fix`](../../reference/cli/subcommands.md#m-manifest)
+to your Snap bundle and use [`yarn mm-snap manifest --fix`](../../reference/cli.md#m-manifest)
 to update the `shasum` in your Snap manifest file.
 The manifest `shasum` must match the contents of your bundle at the time MetaMask fetches your Snap.
 

snaps/how-to/test-a-snap.md

@@ -5,18 +5,43 @@ sidebar_position: 6
 
 # Test a Snap
 
-You can test your Snap by hosting it locally using `yarn start`, installing it in Flask, and calling
-its API methods from a dapp.
+You can test your Snap [locally](#test-locally), in the [Snaps sandbox](#test-in-a-sandbox), and [end-to-end using Jest](#test-end-to-end).
 
-For end-to-end Snap testing in a Jest environment, use the
-[`@metamask/snaps-jest`](https://github.com/MetaMask/snaps/tree/main/packages/snaps-jest) package
-as follows.
+## Test locally
 
-## Steps
+1. Host your Snap locally:
+
+   ```bash
+   yarn start
+   ```
+   
+2. Install your Snap in Flask.
+
+3. Test your Snap by calling its API methods from a dapp.
+
+## Test in the sandbox
+
+Use the Snaps sandbox to easily test and debug your Snap.
+
+1. Run the [`sandbox`](../reference/cli.md#sandbox) subcommand to start the sandbox server:
+
+   ```bash
+   yarn mm-snap sandbox
+   ```
+
+   Navigate to the `localhost` URL displayed in the terminal.
+
+2. Install your Snap in Flask.
+
+3. Test your Snap by calling its API methods from the sandbox interface.
+
+## Test end-to-end
+
+Follow these steps to test your Snap end-to-end in a Jest environment.
 
 ### 1. Install `@metamask/snaps-jest`
 
-Install the `@metamask/snaps-jest` package into your Snap project using [Yarn](https://yarnpkg.com/)
+Install the [`@metamask/snaps-jest`](https://github.com/MetaMask/snaps/tree/main/packages/snaps-jest) package into your Snap project using [Yarn](https://yarnpkg.com/)
 or [npm](https://www.npmjs.com/):
 
 ```bash

snaps/how-to/use-environment-variables.md

@@ -31,7 +31,7 @@ Snaps CLI:
    PUBLIC_KEY=abc123 SNAP_ENV=dev
    ```
 
-2. Build your Snap using the [Snaps CLI](../reference/cli/subcommands.md):
+2. Build your Snap using the [Snaps CLI](../reference/cli.md):
 
    ```bash
    yarn mm-snap build

snaps/learn/about-snaps/files.md

@@ -78,9 +78,9 @@ reproduce the `source.shasum` value), and what
 You might need to modify some manifest fields manually.
 For example, if you change the location of the icon SVG file, you must update
 `source.location.npm.iconPath` to match.
-You can also use the [Snaps CLI](../../reference/cli/subcommands.md) to update some fields for you.
-For example, running [`yarn mm-snap build`](../../reference/cli/subcommands.md#b-build) or
-[`yarn mm-snap manifest --fix`](../../reference/cli/subcommands.md#m-manifest) updates `source.shasum`.
+You can also use the [Snaps CLI](../../reference/cli.md) to update some fields for you.
+For example, running [`yarn mm-snap build`](../../reference/cli.md#b-build) or
+[`yarn mm-snap manifest --fix`](../../reference/cli.md#m-manifest) updates `source.shasum`.
 
 :::caution important
 Some manifest fields must match the corresponding fields of the `/snap/package.json` file.
@@ -105,7 +105,7 @@ expand to support different publishing solutions.
 The Snap configuration file, `snap.config.js` or `snap.config.ts`, must be placed in the project
 root directory.
 You can override the default values of the
-[Snaps configuration options](../../reference/cli/options.md) by specifying them in the
+[Snaps configuration options](../../reference/config-options.md) by specifying them in the
 configuration file.
 For example:
 
@@ -163,7 +163,7 @@ built-ins must be bundled along with the Snap.
 
 Running `yarn start` bundles your Snap for you.
 
-You can also run [`yarn mm-snap build`](../../reference/cli/subcommands.md#b-build) to bundle your
+You can also run [`yarn mm-snap build`](../../reference/cli.md#b-build) to bundle your
 Snap using [webpack](https://webpack.js.org/).
 This command finds all dependencies using your specified main entry point and outputs a bundle
 file to your specified output path.

snaps/reference/cli/subcommands.md snaps/reference/cli.mdsnaps/reference/cli/subcommands.md renamed to snaps/reference/cli.md

@@ -1,14 +1,14 @@
 ---
-sidebar_label: Subcommands
-sidebar_position: 2
+sidebar_label: Snaps CLI
+sidebar_position: 3
 toc_max_heading_level: 4
 description: See the Snaps CLI subcommands reference.
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Snaps subcommands
+# Snaps CLI
 
 This reference describes the syntax of the Snaps command line interface (CLI) subcommands and
 subcommand options.
@@ -19,6 +19,11 @@ You can specify subcommands and their options using the `yarn mm-snap` command:
 yarn mm-snap [SUBCOMMAND] [SUBCOMMAND OPTIONS]
 ```
 
+:::note
+This documentation assumes you created your Snap using the [`@metamask/create-snap`](https://github.com/MetaMask/snaps/tree/main/packages/create-snap) starter kit, which includes the Snaps CLI.
+You can also install the CLI directly using the [`@metamask/snaps-cli`](https://github.com/MetaMask/snaps/tree/main/packages/snaps-cli) package.
+:::
+
 ### `b`, `build`
 
 ```bash
@@ -41,7 +46,7 @@ yarn mm-snap build --analyze
 </TabItem>
 </Tabs>
 
-Enables analyzing the Snap [bundle](../../learn/about-snaps/files.md#bundle-file).
+Enables analyzing the Snap [bundle](../learn/about-snaps/files.md#bundle-file).
 This uses [`webpack-bundle-analyzer`](https://github.com/webpack-contrib/webpack-bundle-analyzer) under the hood,
 which creates an interactive visualization of the contents of your bundle.
 The visualization is located at the URL displayed in the command line output (for example, `http://localhost:8888`).
@@ -69,8 +74,8 @@ yarn mm-snap build --config ./snap.config.build.ts
 </TabItem>
 </Tabs>
 
-Path to the [configuration file](../../learn/about-snaps/files.md#configuration-file),
-which specifies [options](options.md) with which to the build the Snap.
+Path to the [configuration file](../learn/about-snaps/files.md#configuration-file),
+which specifies [options](config-options.md) with which to the build the Snap.
 
 `-c` is an alias for `--config`.
 
@@ -81,7 +86,7 @@ yarn mm-snap eval
 ```
 
 Attempts to evaluate the Snap bundle in
-[Secure ECMAScript (SES)](../../learn/about-snaps/execution-environment.md#secure-ecmascript-ses).
+[Secure ECMAScript (SES)](../learn/about-snaps/execution-environment.md#secure-ecmascript-ses).
 
 `e` is an alias for `eval`.
 
@@ -91,7 +96,7 @@ Attempts to evaluate the Snap bundle in
 yarn mm-snap manifest
 ```
 
-Validates the Snap [manifest file](../../learn/about-snaps/files.md#manifest-file).
+Validates the Snap [manifest file](../learn/about-snaps/files.md#manifest-file).
 
 `m` is an alias for `manifest`.
 
@@ -109,6 +114,18 @@ yarn mm-snap manifest --fix
 
 Enables making any changes to fix the manifest file.
 
+### `sandbox`
+
+```bash
+yarn mm-snap sandbox
+```
+
+Starts a [Snaps sandbox](../how-to/test-a-snap.md#test-in-the-sandbox) server, where you can interact with and test a Snap.
+
+:::info
+This option requires [`@metamask/snaps-cli`](https://github.com/MetaMask/snaps/tree/main/packages/snaps-cli) version 7.1.0 or later.
+:::
+
 ### `s`, `serve`
 
 ```bash

snaps/reference/cli/_category_.json

@@ -1,8 +1,8 @@
 ---
-sidebar_label: Options
-sidebar_position: 1
+sidebar_label: Configuration options
+sidebar_position: 4
 toc_max_heading_level: 4
-description: See the Snaps CLI options reference.
+description: See the Snaps configuration options reference.
 ---
 
 import Tabs from "@theme/Tabs";
@@ -12,7 +12,7 @@ import TabItem from "@theme/TabItem";
 
 This reference describes the syntax of the Snaps command line interface (CLI) configuration options.
 You can specify these options in the
-[configuration file](../../learn/about-snaps/files.md#configuration-file).
+[configuration file](../learn/about-snaps/files.md#configuration-file).
 
 ### `customizeWebpackConfig`
 
@@ -74,7 +74,7 @@ environment: {
 </Tabs>
 
 The environment configuration.
-You can use this to [set environment variables for the Snap](../../how-to/use-environment-variables.md),
+You can use this to [set environment variables for the Snap](../how-to/use-environment-variables.md),
 which can be accessed using `process.env`.
 
 ### `evaluate`
@@ -167,7 +167,7 @@ features: {
 </TabItem>
 </Tabs>
 
-Enables or disables [image support](../../features/custom-ui/index.md#image).
+Enables or disables [image support](../features/custom-ui/index.md#image).
 The default is `true`.
 
 ### `input`
@@ -195,7 +195,7 @@ The default is `"src/index.js"`.
 
 ### `manifest`
 
-The Snap [manifest file](../../learn/about-snaps/files.md#manifest-file) configuration.
+The Snap [manifest file](../learn/about-snaps/files.md#manifest-file) configuration.
 
 #### `manifest.path`
 
@@ -393,7 +393,7 @@ See [the list of available polyfills](https://github.com/MetaMask/snaps/blob/51a
 
 The development server configuration.
 The development server is used to test the Snap during development, using the
-[`watch`](subcommands.md#w-watch) and [`serve`](subcommands.md#s-serve) subcommands.
+[`watch`](cli.md#w-watch) and [`serve`](cli.md#s-serve) subcommands.
 
 #### `server.enabled`
 

snaps/reference/cli/options.md snaps/reference/config-options.mdsnaps/reference/cli/options.md renamed to snaps/reference/config-options.md

@@ -542,6 +542,14 @@
       "source": "/snaps/reference/exports/",
       "destination": "/snaps/reference/entry-points/"
     },
+    {
+      "source": "/snaps/reference/cli/subcommands/",
+      "destination": "/snaps/reference/cli/"
+    },
+    {
+      "source": "/snaps/reference/cli/options/",
+      "destination": "/snaps/reference/config-options/"
+    },
     {
       "source": "/services/gas-api/",
       "destination": "/services/reference/gas-api/"