Document Snaps sandbox and update CLI docs (#2030)

* Document Snaps sandbox and update CLI docs

* remove/replace Snaps Simulator

* replace easily

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

@@ -12,7 +12,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/publish-a-snap.md

@@ -25,9 +25,8 @@ After publishing the Snap, any dapp can connect to the Snap by using the Snap ID
 :::caution
 If you are using the Snap monorepo project generated in the [quickstart](../get-started/quickstart.md),
 make sure to only publish the Snap package in `/packages/snap`.
-You can use the [Snaps Simulator](https://metamask.github.io/snaps/snaps-simulator/staging/#/manifest) to verify
-that your Snap was published correctly — just select **localhost** in the top right corner and change the
-Snap location to **npm** and the ID of your Snap.
+You can use the [Snaps sandbox](test-a-snap.md#test-in-the-sandbox) to verify
+that your Snap was published correctly: in the sandbox settings, disable **Use current Snap ID** and specify the npm ID of your Snap.
 
 Also, make sure to update the manifest file, icon file, and README to differentiate your Snap from the template.
 :::

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 test and debug your Snap in an easy-to-use interface.
+
+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

@@ -32,7 +32,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/learn/best-practices/security-guidelines.md

@@ -15,8 +15,6 @@ The following are guidelines for [managing permissions](../../how-to/request-per
 - **Minimum permissions** - Follow the principle of least authority by only adding the minimum
   permissions needed by your Snap in the manifest file.
   Before publishing your Snap, check the permissions again and remove any unused permissions.
-  You can validate your permissions using the [Snaps Simulator Manifest
-  Validator](https://metamask.github.io/snaps/snaps-simulator/staging/#/manifest).
 
 - **Minimum RPC access** - When adding the [`endowment:rpc`](../../reference/permissions.md#endowmentrpc)
   permission for Snaps or dapps, ask yourself if both are necessary.

snaps/learn/resources.md

@@ -52,9 +52,6 @@ View the following Snaps resources in addition to this documentation site.
 - [`snaps-jest`](https://www.npmjs.com/package/@metamask/snaps-jest) - A Jest preset for end-to-end 
   testing MetaMask Snaps, including a Jest environment, and a set of Jest matchers.
   See [how to test a Snap](../how-to/test-a-snap.md) using `snaps-jest`.
-- [Snaps Simulator](https://metamask.github.io/snaps/snaps-simulator/latest) - A tool for simulating
-  Snaps in the browser, streamlining the development process. It doesn't support all Snaps features 
-  but can be useful for testing certain features.
 - [Snapper](https://github.com/sayfer-io/Snapper) - A tool for detecting security vulnerabilities,
   identifying potential issues, and ensuring best coding practices in your Snap.
 - [MetaMask Testing Tools](https://hugomrdias.github.io/metamask/) - A collection of tools for 

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