Review surreal command pages

src/content/doc-surrealdb/cli/env.mdx

@@ -226,48 +226,8 @@ Environment variables can be used to tailor the behaviour of a running SurrealDB
   </tbody>
 </table>
 
-This allows the connection pool size to be determined by an environment variable, falling back to the number of CPUs on the device if no environment variable has been specified. The new environment variable is:
 
 
-
-## Command environment variables
-
-Many of the arguments passed into [the CLI](/docs/surrealdb/cli/start) can be set using these environment variables instead.
-
-As each of these environment variables correspond to a flag passed into a command, it is good practice to put together a command that matches the environment variables you wish to set. Once the database server conforms to your expected behaviour, you can then pull out the values passed into each flag for your environment variables.
-
-For example, take the following command to start the database.
-
-```bash
-surreal start --user root --pass root --allow-net --deny-funcs "crypto::md5, http::post, http::delete"
-```
-
-If we now wanted to use environment variables instead of the `--allow-net` and `--deny-funcs` flags, we would use the `SURREAL_CAPS_ALLOW_NET` and `SURREAL_CAPS_DENY_FUNC` environment variables.
-
-As the `--allow-net` flag was passed in without a following value, the same will be the case with the `SURREAL_CAPS_ALLOW_NET` environment variable, becoming `SURREAL_CAPS_ALLOW_NET=`. The `--deny-funcs` flag can also be used on its own to deny execution of all functions, but in this case is followed by a string to indicate which exact functions are not allowed to be executed. As such, the `SURREAL_CAPS_DENY_FUNC` environment variable must also be followed by a string, becoming `SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete"`.
-
-The command would then look like the following:
-
-<Tabs groupId="start-command">
-
-<TabItem value="bash" label="Bash" >
-```bash
-SURREAL_CAPS_ALLOW_NET
-SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete"
-surreal start --user root --pass root
-```
-</TabItem>
-
-<TabItem value="powershell" label="PowerShell" >
-```powershell
-$env:SURREAL_CAPS_ALLOW_NET
-$env:SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete"
-surreal start --user root --pass root
-```
-</TabItem>
-
-</Tabs>
-
 <table>
   <thead>
     <tr>
@@ -515,11 +475,11 @@ surreal start --user root --pass root
   </tbody>
 </table>
 
-## Storage backend environment variables
+## Environment variables by storage backend
 
 These environment variables are used to configure the storage backend for SurrealDB.
 
-### FoundationDB
+### FoundationDB environment variables
 
 <table>
   <thead>
@@ -549,7 +509,7 @@ These environment variables are used to configure the storage backend for Surrea
 </table>
 
 
-### RocksDB
+### RocksDB environment variables
 
 <table>
   <thead>
@@ -600,6 +560,11 @@ These environment variables are used to configure the storage backend for Surrea
       <td scope="row" data-label="Default">4096</td>
       <td scope="row" data-label="Notes"></td>
     </tr>
+    <tr>
+      <td scope="row" data-label="Env var"><code>SURREAL_ROCKSDB_BLOCK_CACHE_SIZE</code></td>
+      <td scope="row" data-label="Default">Whichever is larger of "System total memory / 2 - 1GiB" and "512MiB"</td>
+      <td scope="row" data-label="Notes">RocksDB <a href="https://github.com/facebook/rocksdb/wiki/memory-usage-in-rocksdb">block cache size</a> in bytes</td>
+    </tr>
     <tr>
       <td scope="row" data-label="Env var"><code>SURREAL_ROCKSDB_KEEP_LOG_FILE_NUM</code></td>
       <td scope="row" data-label="Default">20</td>
@@ -618,7 +583,7 @@ These environment variables are used to configure the storage backend for Surrea
   </tbody>
 </table>
 
-### SurrealKV
+### SurrealKV environment variables
 
 <table>
   <thead>
@@ -639,8 +604,46 @@ These environment variables are used to configure the storage backend for Surrea
       <td scope="row" data-label="Default">false</td>
       <td scope="row" data-label="Notes">Controls the behaviour of RocksDB and SurrealKV. Allows data durability configuration, ensuring that the database can be configured for writes to be synced to disk before transactions are confirmed to be completed.</td>
     </tr>
-
-
   </tbody>
 </table>
 
+## Command environment variables
+
+Many of the arguments passed into [the CLI](/docs/surrealdb/cli/start) can be set using the above environment variables instead.
+
+As each of these environment variables correspond to a flag passed into a command, it is good practice to put together a command that matches the environment variables you wish to set. Once the database server conforms to your expected behaviour, you can then pull out the values passed into each flag for your environment variables.
+
+For example, take the following command to start the database.
+
+```bash
+surreal start --user root --pass root --allow-net --deny-funcs "crypto::md5, http::post, http::delete"
+```
+
+If we now wanted to use environment variables instead of the `--allow-net` and `--deny-funcs` flags, we would use the `SURREAL_CAPS_ALLOW_NET` and `SURREAL_CAPS_DENY_FUNC` environment variables.
+
+As the `--allow-net` flag was passed in without a following value, the same will be the case with the `SURREAL_CAPS_ALLOW_NET` environment variable, becoming `SURREAL_CAPS_ALLOW_NET=`. The `--deny-funcs` flag can also be used on its own to deny execution of all functions, but in this case is followed by a string to indicate which exact functions are not allowed to be executed. As such, the `SURREAL_CAPS_DENY_FUNC` environment variable must also be followed by a string, becoming `SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete"`.
+
+The command would then look like the following:
+
+<Tabs groupId="start-command">
+
+<TabItem value="bash" label="Bash" >
+```bash
+SURREAL_CAPS_ALLOW_NET
+SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete"
+surreal start --user root --pass root
+```
+</TabItem>
+
+<TabItem value="powershell" label="PowerShell" >
+```powershell
+$env:SURREAL_CAPS_ALLOW_NET
+$env:SURREAL_CAPS_DENY_FUNC="crypto::md5, http::post, http::delete"
+surreal start --user root --pass root
+```
+</TabItem>
+</Tabs>
+
+## Surreal Cloud environment variables
+
+Instances on Surreal Cloud are not started with a CLI command or environment variables. Instead, they can be set on the [Configure Instance](/docs/cloud/advanced-topics/configure-an-instance) panel.

src/content/doc-surrealdb/cli/export.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 5
 sidebar_label: Export command
 title: Export command | CLI tool
-description: The export command exports a SurrealQL script file from a local or remote SurrealDB database server.
+description: A command to export data from a SurrealDB database server into a SurrealQL file format.
 ---
 
 import Label from "@components/shared/Label.astro";
@@ -220,19 +220,29 @@ To perform a SurrealQL database export into a local file, in a terminal run the
 surreal export --conn http://localhost:8000 --user root --pass root --ns test --db test export.surql
 ```
 
-Using token based authentication
+Using token-based authentication
 
 ```bash
 surreal export --conn http://localhost:8000 --token <token> --ns test --db test export.surql
 ```
 
-## OPTION IMPORT
+## OPTION IMPORT keyword
 
 The output of a database export includes a line that contains the keywords `OPTION IMPORT`. This command is used internally to ensure that side effects do not run when the data is imported, such as [events](/docs/surrealql/statements/define/event) and [table views](/docs/surrealql/statements/define/table#pre-computed-table-views).
 
+## Using environment variables
+
+When using the `surreal export` command, you can also use environment variables to set the values for the command-line flags. 
+>[!IMPORTANT]
+> Most of the flags mentioned in the command output above also mention a corresponding [environment variables](/docs/surrealdb/cli/env#command-environment-variables). 
+>
+> For example, the `--username` flag can be configured with the `SURREAL_USER` environment variable instead. 
+
+For more on the environment variables available for CLI commands or SurrealDB instances in general, see the [environment variables](/docs/surrealdb/cli/env#command-environment-variables) page.
+
 ## Command help
 
-To see the help information and usage instructions, in a terminal run the surreal export --help command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the export command.
+To see the help information and usage instructions, in a terminal run the `surreal export --help` command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the export command.
 
 ```bash
 surreal export --help
@@ -269,12 +279,3 @@ Options:
   -h, --help                     Print help
 ```
 
-## Using environment variables
-
-When using the `surreal export` command, you can also use environment variables to set the values for the command-line flags. 
->[!IMPORTANT]
-> Most of the flags mentioned in the command output above also mention a corresponding [environment variables](/docs/surrealdb/cli/env#command-environment-variables). 
->
-> For example, the `--username` flag can be configured with the `SURREAL_USER` environment variable instead. 
-
-For more on the environment variables available for CLI commands or SurrealDB instances in general, see the [environment variables](/docs/surrealdb/cli/env#command-environment-variables) page.

src/content/doc-surrealdb/cli/fix.mdx

@@ -2,14 +2,14 @@
 sidebar_position: 6
 sidebar_label: Fix command
 title: Fix command | CLI tool
-description: The fix command converts SurrealDB version 1.x data into a format that can be used in SurrealDB 2.0
+description: A command to convert SurrealDB version 1.x data into a usable format for versions 2.0 and above.
 ---
 
 import Label from "@components/shared/Label.astro";
 
 # Fix command
 
-The fix command converts SurrealDB version 1.x data into a format that can be used in SurrealDB 2.0
+The fix command converts SurrealDB version 1.x data into a format that can be used in SurrealDB 2.x.
 
 > [!NOTE: BEFORE YOU START]
 > Make sure you’ve [installed SurrealDB](/docs/surrealdb/installation) — it should only take a second!
@@ -59,14 +59,23 @@ The fix command converts SurrealDB version 1.x data into a format that can be us
 
 ## Example usage
 
-To perform a fix from SurrealDB 1.x to 2.0 storage, run the `surreal fix` command in a terminal with the path to the stored data.
+To perform a fix from SurrealDB 1.x to 2.x storage, run the `surreal fix` command in a terminal with the path to the stored data.
 
 ```bash
 surreal fix surrealkv://mydatabase.db
 
 surreal fix rocksdb:somedatabase
 ```
 
+## Using environment variables
+
+When using the `surreal fix` command, you can also use environment variables to set the values for the command-line flags. 
+>[!IMPORTANT]
+> Most of the flags mentioned in the command output above also mention a corresponding [environment variables](/docs/surrealdb/cli/env#command-environment-variables). 
+>
+> For example, the `--log` flag can be configured with the `SURREAL_LOG` environment variable instead. 
+
+For more on the environment variables available for CLI commands or SurrealDB instances in general, see the [environment variables](/docs/surrealdb/cli/env#command-environment-variables) page.
 
 ## Command help
 
@@ -91,12 +100,3 @@ Options:
   -h, --help       Print help
 ```
 
-## Using environment variables
-
-When using the `surreal fix` command, you can also use environment variables to set the values for the command-line flags. 
->[!IMPORTANT]
-> Most of the flags mentioned in the command output above also mention a corresponding [environment variables](/docs/surrealdb/cli/env#command-environment-variables). 
->
-> For example, the `--log` flag can be configured with the `SURREAL_LOG` environment variable instead. 
-
-For more on the environment variables available for CLI commands or SurrealDB instances in general, see the [environment variables](/docs/surrealdb/cli/env#command-environment-variables) page.

src/content/doc-surrealdb/cli/help.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 4
 sidebar_label: Help command
 title: Help command | CLI tool
-description: The help command displays help information and instructions on the command-line tool and its arguments.
+description: A command to display all possible top-level commands and arguments used in the the SurrealDB binary.
 ---
 
 # Help command
@@ -36,7 +36,7 @@ Y88b  d88P Y88b 888 888     888     Y8b.     888  888 888 888  .d88P 888   d88P
 To get started using SurrealDB, and for guides on connecting to and building applications
 on top of SurrealDB, check out the SurrealDB documentation (https://surrealdb.com/docs).
 
-If you have questions or ideas, join the SurrealDB community (/community).
+If you have questions or ideas, join the SurrealDB community (https://surrealdb.com/community).
 
 If you find a bug, submit an issue on GitHub (https://github.com/surrealdb/surrealdb/issues).
 
@@ -64,5 +64,13 @@ Options:
       --online-version-check  Whether to allow web check for client version upgrades at start [env: SURREAL_ONLINE_VERSION_CHECK=]
   -h, --help                  Print help
   -V, --version               Print version
+```
+
+## Getting help on individual commands
 
+For individual commands, such as `surreal start` and `surreal sql`, a help prompt can be displayed by adding the `--help` flag. This flag overrides all other flags, and thus can be added to the end of any command regardless of length.
+
+```bash
+surreal start --help
+surreal start --user root --pass root --strict --help
 ```

src/content/doc-surrealdb/cli/import.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 7
 sidebar_label: Import command
 title: Import command | CLI tool
-description: The import command imports a SurrealQL script file into a local or remote SurrealDB database server.
+description: A command that imports a file in SurrealQL format into a local or remote SurrealDB database server.
 ---
 
 import Label from "@components/shared/Label.astro";
@@ -111,7 +111,7 @@ To perform a SurrealQL database import from a local file, in a terminal run the
 surreal import --conn http://localhost:8000 --user root --pass root --ns test --db test downloads/surreal_deal_v1.surql
 ```
 
-Using token based authentication
+Using token-based authentication:
 
 ```bash 
 surreal import --conn http://localhost:8000 --token <token> --ns test --db test downloads/surreal_deal_v1.surql
@@ -121,6 +121,17 @@ surreal import --conn http://localhost:8000 --token <token> --ns test --db test
 
 The output of a database export includes a line that contains the keywords `OPTION IMPORT`. This command is used internally to ensure that side effects do not run when the data is imported, such as [events](/docs/surrealql/statements/define/event) and [table views](/docs/surrealql/statements/define/table#pre-computed-table-views).
 
+## Using environment variables
+
+When using the `surreal import` command, you can also use environment variables to set the values for the command-line flags. 
+
+>[!IMPORTANT]
+> Most of the flags mentioned in the command output above also mention a corresponding [environment variables](/docs/surrealdb/cli/env#command-environment-variables). 
+>
+> For example, the `--username` flag can be configured with the `SURREAL_USER` environment variable instead. 
+
+For more on the environment variables available for CLI commands or SurrealDB instances in general, see the [environment variables](/docs/surrealdb/cli/env#command-environment-variables) page.
+
 ## Command help
 
 To see the help information and usage instructions, in a terminal run the `surreal import --help` command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the `import` command.
@@ -151,13 +162,3 @@ Options:
   -h, --help                     Print help
 ```
 
-## Using environment variables
-
-When using the `surreal import` command, you can also use environment variables to set the values for the command-line flags. 
-
->[!IMPORTANT]
-> Most of the flags mentioned in the command output above also mention a corresponding [environment variables](/docs/surrealdb/cli/env#command-environment-variables). 
->
-> For example, the `--username` flag can be configured with the `SURREAL_USER` environment variable instead. 
-
-For more on the environment variables available for CLI commands or SurrealDB instances in general, see the [environment variables](/docs/surrealdb/cli/env#command-environment-variables) page.

src/content/doc-surrealdb/cli/index.mdx

@@ -7,14 +7,14 @@ description: The SurrealDB command-line tool can be used to export a dataset as
 
 # CLI tool
 
-The SurrealDB command-line tool can be used to [start a single SurrealDB instance](/docs/surrealdb/cli/start), [export a dataset as a `.surql` file](/docs/surrealdb/cli/export), [import SurrealQL](/docs/surrealdb/cli/import) into a local or remote database, or [upgrade](/docs/surrealdb/cli/upgrade) to a new version of SurrealDB.
+The SurrealDB command-line tool uses a single command for functionality such as [starting a single SurrealDB instance](/docs/surrealdb/cli/start), [exporting a dataset as a `.surql` file](/docs/surrealdb/cli/export), [importing SurrealQL](/docs/surrealdb/cli/import) into a local or remote database, [upgrading](/docs/surrealdb/cli/upgrade) to a new version of SurrealDB, or [opening a REPL](/docs/surrealdb/cli/sql) to make queries on a running instance.
 
 >[!IMPORTANT]
->Before using the CLI, you will need to [install SurrealDB](/docs/surrealdb/installation).
+>Before using the CLI, you will need to [install SurrealDB](/docs/surrealdb/installation). To experiment with SurrealDB before installing, see the [Surrealist sandbox](https://surrealist.app/).
 
 ## Getting Started
 
-The CLI, allowing you to use the `surreal` command from your terminal or command prompt. This documentation provides detailed information on each command, including usage examples and options.
+The CLI allows you to use the `surreal` command from your terminal or command prompt. This documentation provides detailed information on each command, including usage examples and options.
 
 When starting with the CLI, the most commonly used commands are [`surreal start`](/docs/surrealdb/cli/start) to start the server, along with [`surreal sql`](/docs/surrealdb/cli/sql) to open up an interactive shell to make queries. Other common commands are [`surreal upgrade`](/docs/surrealdb/cli/upgrade) to switch between versions of SurrealDB, and [`surreal import`](/docs/surrealdb/cli/import) and [`surreal export`](/docs/surrealdb/cli/export) to import and export your data.
 
@@ -29,7 +29,7 @@ Unless you specify otherwise, the CLI will start a database in memory that serve
 In another window, you can then open up an interactive shell to make queries using the  `surreal sql` command.
 
 ```bash
-surreal sql --endpoint http://localhost:8000 --namespace ns --database db --username root --password root --pretty
+surreal sql --namespace ns --database db --username root --password root --pretty
 ```
 
 > [!WARNING]
@@ -68,10 +68,10 @@ ns/db> SELECT * FROM person WHERE age > 25;
 ]
 ```
 
-Alternatively, you can start a local database in memory with the command below. This will start a database in memory with a single namespace called `test` and a database called `test`. Please replace the username and password with your own. 
+Alternatively, you can start a local database in memory with the command below. The `--endpoint memory` flag will start a database in memory, while the other arguments will connect to a single namespace called `test` and a database called `test`. Please replace the username and password with your own. 
 
 ```bash
-surreal sql --endpoint memory --namespace test --database test --auth-level root --username username --password password
+surreal sql --endpoint memory --namespace test --database test --username username --password password
 ```
 
 >[!WARNING]