From 275adc3ffe0936d0d9894c288f6ae827e285d6e9 Mon Sep 17 00:00:00 2001 From: Adewale Abati Date: Thu, 13 Mar 2025 12:46:04 +0100 Subject: [PATCH] docs: Add running tasks guide (#1626) Co-authored-by: Angie Jones --- .../docs/guides/goose-cli-commands.md | 8 +- documentation/docs/guides/running-tasks.md | 139 ++++++++++++++++++ 2 files changed, 145 insertions(+), 2 deletions(-) create mode 100644 documentation/docs/guides/running-tasks.md diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index e413a12f..228c7457 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -144,14 +144,18 @@ goose mcp ### 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 `**: Path to instruction file containing commands - **`-t, --text `**: Input text to provide to Goose directly -- **`-n, --name `**: Name for this run session (e.g., 'daily-tasks') +- **`-s, --interactive`**: Continue in interactive mode after processing initial input +- **`-n, --name `**: Name for this run session (e.g. 'daily-tasks') - **`-r, --resume`**: Resume from a previous run +- **`-p, --path `**: Path for this run session (e.g. './playground.jsonl') +- **`--with-extension `**: Add stdio extensions (can be used multiple times in the same command) +- **`--with-builtin `**: Add builtin extensions by name (e.g., 'developer' or multiple: 'developer,github') **Usage:** diff --git a/documentation/docs/guides/running-tasks.md b/documentation/docs/guides/running-tasks.md new file mode 100644 index 00000000..2aab412c --- /dev/null +++ b/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. \ No newline at end of file