From c19a268fecac1b12f9c66c36990751e7e7e7ea79 Mon Sep 17 00:00:00 2001
From: Jordan Ribbink <jribbink@telus.net>
Date: Tue, 7 Oct 2025 18:22:18 -0700
Subject: [PATCH] Update Flow Emulator Reference Doc

---
 docs/build/tools/emulator/index.md | 90 ++++++++++++++++++++++++++++--
 1 file changed, 84 insertions(+), 6 deletions(-)

diff --git a/docs/build/tools/emulator/index.md b/docs/build/tools/emulator/index.md
index 451e772a64..ff248a2aa1 100644
--- a/docs/build/tools/emulator/index.md
+++ b/docs/build/tools/emulator/index.md
@@ -29,20 +29,98 @@ This starts a local Flow network with:
 - REST API on `http://localhost:8888`
 - Admin API on port `8080`
 
-## Common Options
+## Available Commands
+
+- `snapshot`: Create/Load/List emulator snapshots. See: [Create Emulator Snapshot](../flow-cli/deployment/emulator-snapshot.md)
+
+## Key Flags
+
+- **Networking**
+  - `--host <string>`: Host to listen on for gRPC/REST/Admin (default: all interfaces)
+  - `--port, -p <int>`: gRPC port (default `3569`)
+  - `--rest-port <int>`: REST API port (default `8888`)
+  - `--admin-port <int>`: Admin API port (default `8080`)
+  - `--debugger-port <int>`: Debug Adapter Protocol port (default `2345`)
+  - `--grpc-debug`: Enable gRPC server reflection
+  - `--rest-debug`: Enable REST API debug output
+
+- **State & Persistence**
+  - `--persist`: Enable persistent storage (default disabled)
+  - `--dbpath <path>`: Directory for on-disk state (default `./flowdb`)
+  - `--sqlite-url <url>`: Use SQLite storage backend
+  - `--redis-url <url>`: Use Redis storage backend
+  - `--checkpoint-dir <path>`: Load state from checkpoint directory
+  - `--state-hash <string>`: Load state from checkpoint state hash
+
+- **Forking**
+  - `--rpc-host <host>`: Access node to query when forking Mainnet/Testnet
+  - `--start-block-height <uint>`: Starting block height when forking
+
+- **Cadence & VM**
+  - `--block-time, -b <duration>`: Time between sealed blocks (e.g. `1s`, `300ms`)
+  - `--coverage-reporting`: Enable code coverage reporting
+  - `--computation-reporting`: Enable computation reporting
+  - `--legacy-upgrade`: Enable legacy contract upgrade behavior
+  - `--scheduled-transactions`: Enable scheduled transactions (default true)
+  - `--script-gas-limit <int>`: Gas limit for scripts (default `100000`)
+  - `--transaction-max-gas-limit <int>`: Max transaction gas limit (default `9999`)
+  - `--transaction-expiry <int>`: Transaction expiry in blocks (default `10`)
+  - `--skip-tx-validation`: Skip tx signature and sequence number checks
+  - `--simple-addresses`: Use sequential addresses starting with `0x01`
+  - `--storage-limit`: Enforce account storage limit (default true)
+  - `--storage-per-flow <decimal>`: MB of storage per 1 FLOW token
+  - `--token-supply <decimal>`: Initial FLOW token supply (default `1000000000.0`)
+  - `--transaction-fees`: Enable transaction fees
+  - `--setup-evm`: Deploy EVM contracts (default true)
+  - `--setup-vm-bridge`: Deploy VM Bridge contracts (default true)
+
+- **Service Account & Identity**
+  - `--chain-id <emulator|testnet|mainnet>`: Address generation chain (default `emulator`)
+  - `--service-priv-key <hex>` / `--service-pub-key <hex>`: Service account keys
+  - `--service-sig-algo <ECDSA_P256|ECDSA_secp256k1>`: Service key signature algo (default `ECDSA_P256`)
+  - `--service-hash-algo <SHA3_256|SHA2_256>`: Service key hash algo (default `SHA3_256`)
+  - `--min-account-balance <decimal>`: Minimum account balance / account creation cost
+  - `--contracts`: Deploy common contracts on start
+  - `--contract-removal`: Allow contract removal for development (default true)
+  - `--init`: Initialize a new account profile
+
+- **Logging & Output**
+  - `--verbose, -v`: Verbose logging
+  - `--log-format <text|JSON>`: Logging output format (default `text`)
+
+- **Snapshots**
+  - `--snapshot`: Enable snapshots in the emulator
+
+## Examples
 
 ```bash
-# Start with verbose logging
+# Verbose logs
 flow emulator --verbose
 
-# Set custom block time (e.g., 1 second between blocks)
+# Custom ports
+flow emulator --port 9000 --rest-port 9001 --admin-port 9002
+
+# Custom block time (1 second between blocks)
 flow emulator --block-time 1s
 
-# Persist state between restarts
-flow emulator --persist
+# Persist state on disk
+flow emulator --persist --dbpath ./flowdb
+
+# Fork from Testnet at a specific height
+flow emulator --rpc-host access.devnet.nodes.onflow.org:9000 --start-block-height 12345678
+
+# Disable fees and use simple addresses for local testing
+flow emulator --transaction-fees=false --simple-addresses
+
+# Enable code coverage reporting
+flow emulator --coverage-reporting
 ```
 
-For all available options, see the [CLI commands overview](../flow-cli/index.md).
+For the complete and current list of flags, run:
+
+```bash
+flow emulator --help
+```
 
 ## Debugging & Testing