docs: Add running tasks guide (#1626)

Co-authored-by: Angie Jones <jones.angie@gmail.com>

documentation/docs/guides/goose-cli-commands.md

@@ -144,14 +144,18 @@ goose mcp <name>
 
 ### run [options]
 
-Execute commands from an instruction file or stdin
+Execute commands from an instruction file or stdin. Check out the [full guide](/docs/guides/running-tasks) for more info.
 
 **Options:**
 
 - **`-i, --instructions <FILE>`**: Path to instruction file containing commands
 - **`-t, --text <TEXT>`**: Input text to provide to Goose directly
-- **`-n, --name <NAME>`**: Name for this run session (e.g., 'daily-tasks')
+- **`-s, --interactive`**: Continue in interactive mode after processing initial input
+- **`-n, --name <NAME>`**: Name for this run session (e.g. 'daily-tasks')
 - **`-r, --resume`**: Resume from a previous run
+- **`-p, --path <PATH>`**: Path for this run session (e.g. './playground.jsonl')
+- **`--with-extension <COMMAND>`**: Add stdio extensions (can be used multiple times in the same command)
+- **`--with-builtin <NAME>`**: Add builtin extensions by name (e.g., 'developer' or multiple: 'developer,github')
 
 **Usage:**
 

documentation/docs/guides/running-tasks.md

@@ -0,0 +1,139 @@
+---
+sidebar_position: 7
+---
+# Running Tasks
+
+When working with the Goose CLI, you can pass files and instructions to the `goose run` command to execute tasks and workflows. This could be a simple one-liner command or a complex set of instructions stored in a file.
+
+## Basic Usage
+
+The `goose run` command starts a new session, begins executing using any arguments provided and exits the session automatically once the task is complete. 
+
+There are multiple ways to run tasks with Goose; check out the [list of options](/docs/guides/goose-cli-commands.md#run-options).
+
+### Text in the command
+```bash
+goose run -t "your instructions here"
+```
+
+Using the `-t` flag, one is able to pass a text instruction directly to the command. This is great for quick, one-off commands where you do not need an interactive session with Goose. The instructions will be executed, and the session will end. An example usage could be using in a CI/CD pipeline or running alongside other scripts.
+
+### Using an instruction file
+If you have a complex set of instructions or a workflow that you want to automate, you can store them in a file and pass it to the `goose run` command:
+
+```bash
+goose run -i instructions.md
+```
+
+Here's an example of an instruction file that runs a security audit on project dependencies:
+
+```md
+# Dependency Security Audit
+
+1. Analyze project dependencies:
+   - Check package.json and requirements.txt files
+   - List all dependencies with versions
+   - Identify outdated packages
+
+2. Security check:
+   - Run npm audit (for JavaScript packages)
+   - Check for known vulnerabilities in Python packages
+   - Identify dependencies with critical security issues
+
+3. Create an upgrade plan:
+   - List packages requiring immediate updates
+   - Note breaking changes in latest versions
+   - Estimate impact of required updates
+
+Save findings in 'security_audit.md' with severity levels highlighted.
+```
+
+## Key Features
+
+### Interactive Mode
+
+If you don't want Goose to exit at the end of the task, you can pass the `-s` or `--interactive` flag to start an interactive session after processing your initial commands:
+
+```bash
+goose run -i instructions.txt -s
+```
+
+This is useful when you want to continue working with Goose after your initial commands are processed.
+
+### Session Management
+
+You can name and manage your sessions:
+
+```bash
+# Start a new named session
+goose run -n my-project -t "initial instructions"
+
+# Resume a previous session
+goose run -n my-project -r
+```
+
+### Working with Extensions
+
+If you want to ensure specific extensions are available when running your task, you can indicate this with arguments. This can be done using the `--with-extension` or `--with-builtin` flags:
+
+- Using built-in extensions e.g developer and computercontroller extensions
+
+```bash
+goose run --with-builtin "developer,computercontroller" -t "your instructions"
+```
+
+- Using custom extensions
+
+```bash
+goose run --with-extension "ENV1=value1 custom-extension-args" -t "your instructions"
+```
+
+## Common Use Cases
+
+### Running Script Files
+
+Create an instruction file (e.g., `build-script.txt`):
+```text
+Check the current branch
+Run the test suite
+Build the documentation
+```
+
+Then run it:
+```bash
+goose run -i build-script.txt
+```
+
+### Quick Commands
+
+For one-off commands, use the text option:
+```bash
+goose run -t "Create a CHANGELOG.md entry comparing current git branch with main"
+```
+
+### Development Workflows
+
+Start a session with specific extensions:
+```bash
+goose run --with-builtin "developer,git" -n dev-session -s
+```
+
+### Combining Options
+
+You can combine multiple options to create powerful workflows:
+
+```bash
+# Complex example combining multiple options
+goose run \
+  --with-builtin "developer,git" \
+  --with-extension "API_KEY=xyz123 custom-tool" \
+  -n project-setup \
+  -t "Initialize project" 
+```
+
+This command:
+1. Loads the developer and git built-in extensions
+2. Adds a custom extension with an API key
+3. Names the session "project-setup"
+4. Starts with "Initialize project" instruction
+5. Exits automatically after processing the command.