From e7c92f6dc84e62202c148dc0af592d7dd64ed26d Mon Sep 17 00:00:00 2001
From: Matt Nield <64328730+matthewjnield@users.noreply.github.com>
Date: Thu, 5 Sep 2024 07:25:28 -0400
Subject: [PATCH] Improve `surreal start` command documentation (#818)

Co-authored-by: Obinna Ekwuno <obinnacodes@gmail.com>
---
 .../version-latest/cli/start.mdx              | 30 ++++++++++++++++---
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/doc-surrealdb_versioned_docs/version-latest/cli/start.mdx b/doc-surrealdb_versioned_docs/version-latest/cli/start.mdx
index e1b3fcf9e..db5d2791d 100644
--- a/doc-surrealdb_versioned_docs/version-latest/cli/start.mdx
+++ b/doc-surrealdb_versioned_docs/version-latest/cli/start.mdx
@@ -112,7 +112,7 @@ __BEFORE YOU START :__ Make sure you’ve [installed SurrealDB](/docs/surrealdb/
                 <ul>
                     <li><code>rocksdb</code> for RocksDB</li>
                     <li><code>fdb</code> for FoundationDB</li>
-                    <li><code>indxdb</code> for IndxDB</li>
+                    <li><code>indxdb</code> for IndexedDB</li>
                     <li><code>memory</code> (or no argument) for in-memory storage</li>
                     <li><code>surrealkv</code> for SurrealKV</li>
                     <li><code>tikv</code> for TiKV</li>
@@ -124,12 +124,34 @@ __BEFORE YOU START :__ Make sure you’ve [installed SurrealDB](/docs/surrealdb/
 
 ## Example usage
 
-To display the current command-line tool version, along with the platform and architecture, in a terminal run the surreal version.
+This example will show how to host a SurrealDB server with the `surreal start` command, and then access the Surreal DB server using the [`surreal sql` command](/docs/surrealdb/cli/sql).
+
+To start a SurrealDB server, run the `surreal start` command, using the options below. This example stores the database in memory, with a username and password, hosted at `127.0.0.1:8000` (the default location).
 
 ```bash
-surreal version
+surreal start memory --user my_username --pass my_password
 ```
 
+The server is actively running, and should be left alone until you want to stop hosting the SurrealDB server.
+
+:::note
+__Note:__ The message "Started web server on 127.0.0.1:8000", indicates where the server is being hosted and must be accessed by clients. The location `127.0.0.1:8000` is the default, and can be manually changed by specifying the `--bind` option of the `surreal start` command.
+:::
+
+
+To access the SurrealDB server that you have started hosting, open a separate terminal which will act as the "client", while the previous terminal is still running the `surreal start` command described above. 
+
+In the new terminal, run the [`surreal sql` command](/docs/surrealdb/cli/sql) using the options shown below.
+
+```bash
+surreal sql --endpoint http://127.0.0.1:8000 --namespace my_namespace --database my_database --auth-level root --username my_username --password my_password
+```
+
+Ensure that the hosting location indicated by the output of the `surreal start` command is passed to the `--endpoint` argument, and that you specify the same `--username` and `--password` as in the `surreal start` command.
+
+The above example also selects a namespace and database so that you can immediately start entering queries if you wish. See the documentation of the [`surreal sql` command](/docs/surrealdb/cli/sql) for more information.
+
+
 ## Strict mode
 
 SurrealDB supports the ability to startup in strict mode. When running in strict mode, all `NAMESPACE`, `DATABASE`, and `TABLE` definitions will not be created automatically when data is inserted. Instead, if the selected namespace, database, or table has not been specifically defined, then the query will return an error.
@@ -262,4 +284,4 @@ CAPABILITIES:
 --deny-funcs [<DENY_FUNCS>...]             Deny execution of all functions. Optionally, you can provide a comma-separated list of function names to deny [env:SURREAL_CAPS_DENY_FUNC=]
 
 --deny-net [<DENY_NET>...]             Deny all outbound network access. Optionally, you can provide a comma-separated list of targets to deny [env: SURREAL_CAPS_DENY_NET=]
-```
\ No newline at end of file
+```