From 2b968d87740ebe10dc84a9a4a90f2eaac86929d5 Mon Sep 17 00:00:00 2001 From: Rizel Scarlett Date: Wed, 22 Oct 2025 02:53:16 -0400 Subject: [PATCH] documenting `goose recipe list` command (#5278) --- .../docs/guides/environment-variables.md | 25 ++++ .../docs/guides/goose-cli-commands.md | 28 +++-- .../docs/guides/recipes/recipe-reference.md | 4 +- .../docs/guides/recipes/session-recipes.md | 2 +- .../docs/guides/recipes/storing-recipes.md | 107 ++++++++++++++++-- 5 files changed, 146 insertions(+), 20 deletions(-) diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index b5a141625b..ab7428d1e6 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -314,6 +314,31 @@ These variables configure the [Langfuse integration for observability](/docs/tut | `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` | Alternative public key for Langfuse | String | None | | `LANGFUSE_INIT_PROJECT_SECRET_KEY` | Alternative secret key for Langfuse | String | None | +## Recipe Configuration + +These variables control recipe discovery and management. + +| Variable | Purpose | Values | Default | +|----------|---------|---------|---------| +| `GOOSE_RECIPE_PATH` | Additional directories to search for recipes | Colon-separated paths on Unix, semicolon-separated on Windows | None | +| `GOOSE_RECIPE_GITHUB_REPO` | GitHub repository to search for recipes | Format: "owner/repo" (e.g., "block/goose-recipes") | None | +| `GOOSE_RECIPE_RETRY_TIMEOUT_SECONDS` | Global timeout for recipe success check commands | Integer (seconds) | Recipe-specific default | +| `GOOSE_RECIPE_ON_FAILURE_TIMEOUT_SECONDS` | Global timeout for recipe on_failure commands | Integer (seconds) | Recipe-specific default | + +**Examples** + +```bash +# Add custom recipe directories +export GOOSE_RECIPE_PATH="/path/to/my/recipes:/path/to/team/recipes" + +# Configure GitHub recipe repository +export GOOSE_RECIPE_GITHUB_REPO="myorg/goose-recipes" + +# Set global recipe timeouts +export GOOSE_RECIPE_RETRY_TIMEOUT_SECONDS=300 +export GOOSE_RECIPE_ON_FAILURE_TIMEOUT_SECONDS=60 +``` + ## Experimental Features These variables enable experimental features that are in active development. These may change or be removed in future releases. Use with caution in production environments. diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index 3f0810c74c..f61df86ce9 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -267,29 +267,39 @@ goose bench ...etc. --- #### recipe -Used to validate recipe files, manage recipe sharing, and open recipes in goose desktop. +Used to validate recipe files, manage recipe sharing, list available recipes, and open recipes in goose desktop. **Commands:** -- `validate `: Validate a recipe file -- `deeplink `: Generate a shareable link for a recipe file -- `open `: Open a recipe file directly in goose desktop +- **`deeplink `**: Generate a shareable link for a recipe file +- **`list [OPTIONS]`**: List all available recipes from local directories and configured GitHub repositories + - **`--format `**: Output format (`text` or `json`). Default is `text` + - **`-v, --verbose`**: Show verbose information including recipe titles and full file paths +- **`open `**: Open a recipe file directly in goose desktop +- **`validate `**: Validate a recipe file **Usage:** ```bash -goose recipe - -# Validate a recipe file -goose recipe validate my-recipe.yaml - # Generate a shareable link goose recipe deeplink my-recipe.yaml +# List all available recipes +goose recipe list + +# List recipes with detailed information +goose recipe list --verbose + +# List recipes in JSON format for automation +goose recipe list --format json + # Open a recipe in goose desktop goose recipe open my-recipe.yaml # Open a recipe by name goose recipe open my-recipe +# Validate a recipe file +goose recipe validate my-recipe.yaml + # Get help about recipe commands goose recipe help ``` diff --git a/documentation/docs/guides/recipes/recipe-reference.md b/documentation/docs/guides/recipes/recipe-reference.md index cc2567708b..1e5e8258d8 100644 --- a/documentation/docs/guides/recipes/recipe-reference.md +++ b/documentation/docs/guides/recipes/recipe-reference.md @@ -535,10 +535,10 @@ Recipes can be loaded from: 1. Local filesystem: - Current directory - - Directories specified in `GOOSE_RECIPE_PATH` environment variable + - Directories specified in [`GOOSE_RECIPE_PATH`](/docs/guides/environment-variables#recipe-configuration) environment variable 2. GitHub repositories: - - Configure using `GOOSE_RECIPE_GITHUB_REPO` configuration key + - Configure using [`GOOSE_RECIPE_GITHUB_REPO`](/docs/guides/environment-variables#recipe-configuration) configuration key - Requires GitHub CLI (`gh`) to be installed and authenticated ## Validation Rules diff --git a/documentation/docs/guides/recipes/session-recipes.md b/documentation/docs/guides/recipes/session-recipes.md index eb4486bb7a..41dcfeebb9 100644 --- a/documentation/docs/guides/recipes/session-recipes.md +++ b/documentation/docs/guides/recipes/session-recipes.md @@ -341,7 +341,7 @@ You can turn your current Goose session into a reusable recipe that includes the **Basic Usage** - Run once and exit (see [run options](/docs/guides/goose-cli-commands#run-options) and [recipe commands](/docs/guides/goose-cli-commands#recipe) for more): ```sh - # Using recipe file in current directory or `GOOSE_RECIPE_PATH` directories + # Using recipe file in current directory or [`GOOSE_RECIPE_PATH`](/docs/guides/environment-variables#recipe-configuration) directories goose run --recipe recipe.yaml # Using full path diff --git a/documentation/docs/guides/recipes/storing-recipes.md b/documentation/docs/guides/recipes/storing-recipes.md index ebe5271f96..e7e140cada 100644 --- a/documentation/docs/guides/recipes/storing-recipes.md +++ b/documentation/docs/guides/recipes/storing-recipes.md @@ -101,23 +101,114 @@ When you modify and save a recipe with a new name, a new recipe and new link are -## Finding Your Recipes +## Finding Available Recipes **Access Recipe Library:** 1. Click the button in the top-left to open the sidebar -2. Click `Recipes` -3. Browse the list of your saved recipes -4. Each recipe shows its title, description, and whether it's global or local +2. Click `Recipes` to view your Recipe Library +3. Browse your available recipes, which show: + - Recipe title and description + - Last modified date + - Whether they're stored globally or locally + +:::info Desktop vs CLI Recipe Discovery +The Desktop Recipe Library displays all recipes you've explicitly saved or imported. It doesn't automatically discover recipe files from your filesystem like the CLI does. +::: -To find and configure your saved recipes: +Use the `goose recipe list` command to find all available recipes from multiple sources: + +**Basic Usage** + +```bash +# List all available recipes +goose recipe list + +# Show detailed information including titles and full paths +goose recipe list --verbose + +# Output in JSON format for automation +goose recipe list --format json +``` + +**Recipe Discovery Process** + +Goose searches for recipes in the following locations (in order): + +1. **Current directory**: `.` (looks for `*.yaml` and `*.json` files) +2. **Custom paths**: Directories specified in [`GOOSE_RECIPE_PATH`](/docs/guides/environment-variables#recipe-configuration) environment variable +3. **Global recipe library**: `~/.config/goose/recipes/` (or equivalent on your OS) +4. **Local project recipes**: `./.goose/recipes/` +5. **GitHub repository**: If [`GOOSE_RECIPE_GITHUB_REPO`](/docs/guides/environment-variables#recipe-configuration) environment variable is configured + +**Example Output** + +*Default text format:* +```bash +$ goose recipe list +Available recipes: +goose-self-test - A comprehensive meta-testing recipe - local: ./goose-self-test.yaml +hello-world - A sample recipe demonstrating basic usage - local: ~/.config/goose/recipes/hello-world.yaml +job-finder - Find software engineering positions - local: ~/.config/goose/recipes/job-finder.yaml +``` + +*Verbose mode:* +```bash +$ goose recipe list --verbose +Available recipes: + goose-self-test - A comprehensive meta-testing recipe - local: ./goose-self-test.yaml + Title: Goose Self-Testing Integration Suite + Path: ./goose-self-test.yaml + hello-world - A sample recipe demonstrating basic usage - local: ~/.config/goose/recipes/hello-world.yaml + Title: Hello World Recipe + Path: /Users/username/.config/goose/recipes/hello-world.yaml +``` + +*JSON format for automation:* +```json +[ + { + "name": "goose-self-test", + "source": "Local", + "path": "./goose-self-test.yaml", + "title": "Goose Self-Testing Integration Suite", + "description": "A comprehensive meta-testing recipe" + }, + { + "name": "hello-world", + "source": "GitHub", + "path": "recipes/hello-world.yaml", + "title": "Hello World Recipe", + "description": "A sample recipe demonstrating basic usage" + } +] +``` + +**Configuring Recipe Sources** + +Add custom recipe directories: +```bash +export GOOSE_RECIPE_PATH="/path/to/my/recipes:/path/to/team/recipes" +goose recipe list +``` + +Configure GitHub recipe repository: +```bash +export GOOSE_RECIPE_GITHUB_REPO="myorg/goose-recipes" +goose recipe list +``` + +See the [Environment Variables Guide](/docs/guides/environment-variables#recipe-configuration) for more configuration options. + +**Manual Directory Browsing (Advanced)** + +If you need to browse recipe directories manually: -**Browse recipe directories:** ```bash # List recipes in default global location ls ~/.config/goose/recipes/ @@ -126,11 +217,11 @@ ls ~/.config/goose/recipes/ ls .goose/recipes/ # Search for all recipe files -find . -name "*.md" -path "*/recipes/*" +find . -name "*.yaml" -path "*/recipes/*" -o -name "*.json" -path "*/recipes/*" ``` :::tip -Set up [custom recipe paths](/docs/guides/recipes/session-recipes#configure-recipe-location) to organize recipes in specific directories or access recipes from a shared GitHub repository. +The `goose recipe list` command is the recommended way to find recipes as it automatically searches all configured sources and provides consistent formatting. :::