Add documentation for CLI mode (#3706)

* Add documentation for CLI mode

Fixes #3703

Add documentation for CLI mode in OpenHands.

* **New Documentation**: Add `docs/modules/usage/how-to/cli-mode.md` to document CLI mode.
  - Include instructions on starting an interactive OpenHands session via the command line.
  - Explain the difference between CLI mode and headless mode.
  - Provide examples of CLI commands and expected outputs.
* **Update Existing Documentation**: Modify `docs/modules/usage/how-to/headless-mode.md`.
  - Clarify the difference between headless mode and CLI mode.
  - Add a reference to the new CLI mode documentation.

* Update cli-mode.md

* Update headless-mode.md

---------

Co-authored-by: Robert Brennan <accounts@rbren.io>
Co-authored-by: tofarr <tofarr@gmail.com>

docs/modules/usage/how-to/cli-mode.md

@@ -0,0 +1,107 @@
+# Running in CLI Mode
+
+OpenHands can be run in an interactive CLI mode, which allows users to start an interactive session via the command line. This mode is different from the headless mode, which is non-interactive.
+
+## Starting an Interactive Session
+
+To start an interactive OpenHands session via the command line, follow these steps:
+
+1. Ensure you have followed the [Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
+
+2. Run the following command:
+
+```bash
+poetry run python -m openhands.core.cli
+```
+
+This command will start an interactive session where you can input tasks and receive responses from OpenHands.
+
+## Running in CLI Mode with Docker
+
+To run OpenHands in CLI mode with Docker, follow these steps:
+
+1. Set `WORKSPACE_BASE` to the directory you want OpenHands to edit:
+
+```bash
+WORKSPACE_BASE=$(pwd)/workspace
+```
+
+2. Set `LLM_API_KEY` to an API key, e.g., for OpenAI or Anthropic:
+
+```bash
+LLM_API_KEY="abcde"
+```
+
+3. Set `LLM_MODEL` to the model you want to use:
+
+```bash
+LLM_MODEL="gpt-4o"
+```
+
+4. Run the following Docker command:
+
+```bash
+docker run -it \
+    --pull=always \
+    -e SANDBOX_USER_ID=$(id -u) \
+    -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
+    -e LLM_API_KEY=$LLM_API_KEY \
+    -e LLM_MODEL=$LLM_MODEL \
+    -v $WORKSPACE_BASE:/opt/workspace_base \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    --add-host host.docker.internal:host-gateway \
+    --name openhands-app-$(date +%Y%m%d%H%M%S) \
+    ghcr.io/all-hands-ai/openhands:0.9 \
+    poetry run python -m openhands.core.cli
+```
+
+This command will start an interactive session in Docker where you can input tasks and receive responses from OpenHands.
+
+## Difference Between CLI Mode and Headless Mode
+
+- **CLI Mode**: Interactive mode where users can input tasks and receive responses in real-time. It is suitable for users who prefer or require a command-line interface.
+- **Headless Mode**: Non-interactive mode where tasks are executed without user interaction. It is suitable for automation and scripting purposes.
+
+## Examples of CLI Commands and Expected Outputs
+
+Here are some examples of CLI commands and their expected outputs:
+
+### Example 1: Simple Task
+
+```bash
+How can I help? >> Write a Python script that prints "Hello, World!"
+```
+
+Expected Output:
+
+```bash
+🤖 Sure! Here is a Python script that prints "Hello, World!":
+
+❯ print("Hello, World!")
+```
+
+### Example 2: Bash Command
+
+```bash
+How can I help? >> Create a directory named "test_dir"
+```
+
+Expected Output:
+
+```bash
+🤖 Creating a directory named "test_dir":
+
+❯ mkdir test_dir
+```
+
+### Example 3: Error Handling
+
+```bash
+How can I help? >> Delete a non-existent file
+```
+
+Expected Output:
+
+```bash
+🤖 An error occurred. Please try again.
+```

docs/modules/usage/how-to/headless-mode.md

@@ -1,10 +1,13 @@
-# Running in Headless / CLI Mode
+# Running in Headless Mode
 
-You can run OpenHands via a CLI, without starting the web application. This makes it easy
-to automate tasks with OpenHands. There are 2 main modes of operation:
+You can run OpenHands via a CLI, without starting the web application. This makes it easy to automate tasks with OpenHands.
 
-* **Headless** : Designed for use with scripts
-* **CLI** : Designed for interactive use via a console
+## Difference Between CLI Mode and Headless Mode
+
+- **CLI Mode**: Interactive mode where users can input tasks and receive responses in real-time. It is suitable for users who prefer or require a command-line interface.
+- **Headless Mode**: Non-interactive mode where tasks are executed without user interaction. It is suitable for automation and scripting purposes.
+
+For more information on CLI mode, refer to the [CLI Mode documentation](./cli-mode.md).
 
 As with other modes, the environment is configurable via environment variables or by saving values into [config.toml](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml)
 
@@ -19,68 +22,3 @@ and then run:
 ```bash
 poetry run python -m openhands.core.main -t "write a bash script that prints hi"
 ```
-
-### CLI with Python
-
-```bash
-poetry run python -m openhands.core.cli
-
-How can I help? >> write a bash script that prints hi
-```
-
-## Headless With Docker
-
-To run OpenHands in headless mode with Docker, run:
-
-```bash
-# Set WORKSPACE_BASE to the directory you want OpenHands to edit
-WORKSPACE_BASE=$(pwd)/workspace
-
-# Set LLM_API_KEY to an API key, e.g. for OpenAI or Anthropic
-LLM_API_KEY="abcde"
-
-# Set LLM_MODEL to the model you want to use
-LLM_MODEL="gpt-4o"
-
-docker run -it \
-    --pull=always \
-    -e SANDBOX_USER_ID=$(id -u) \
-    -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
-    -e LLM_API_KEY=$LLM_API_KEY \
-    -e LLM_MODEL=$LLM_MODEL \
-    -v $WORKSPACE_BASE:/opt/workspace_base \
-    -v /var/run/docker.sock:/var/run/docker.sock \
-    --add-host host.docker.internal:host-gateway \
-    --name openhands-app-$(date +%Y%m%d%H%M%S) \
-    ghcr.io/all-hands-ai/openhands:0.9 \
-    poetry run python -m openhands.core.main \
-    -t "Write a bash script that prints Hello World"
-```
-
-## CLI With Docker
-
-To run OpenHands in cli mode with Docker, run:
-
-```bash
-# Set WORKSPACE_BASE to the directory you want OpenHands to edit
-WORKSPACE_BASE=$(pwd)/workspace
-
-# Set LLM_API_KEY to an API key, e.g. for OpenAI or Anthropic
-LLM_API_KEY="abcde"
-
-# Set LLM_MODEL to the model you want to use
-LLM_MODEL="gpt-4o"
-
-docker run -it \
-    --pull=always \
-    -e SANDBOX_USER_ID=$(id -u) \
-    -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
-    -e LLM_API_KEY=$LLM_API_KEY \
-    -e LLM_MODEL=$LLM_MODEL \
-    -v $WORKSPACE_BASE:/opt/workspace_base \
-    -v /var/run/docker.sock:/var/run/docker.sock \
-    --add-host host.docker.internal:host-gateway \
-    --name openhands-app-$(date +%Y%m%d%H%M%S) \
-    ghcr.io/all-hands-ai/openhands:0.9 \
-    poetry run python -m openhands.core.cli
-```