documenting goose recipe list command (#5278)

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.

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 <FILE>`: Validate a recipe file
+- **`deeplink <RECIPE_NAME>`**: Generate a shareable link for a recipe file
-- `deeplink <FILE>`: Generate a shareable link for a recipe file
+- **`list [OPTIONS]`**: List all available recipes from local directories and configured GitHub repositories
-- `open <FILE>`: Open a recipe file directly in goose desktop
+  - **`--format <FORMAT>`**: Output format (`text` or `json`). Default is `text`
+  - **`-v, --verbose`**: Show verbose information including recipe titles and full file paths
+- **`open <RECIPE_NAME>`**: Open a recipe file directly in goose desktop
+- **`validate <RECIPE_NAME>`**: Validate a recipe file
 
 **Usage:**
 ```bash
-goose recipe <COMMAND>
-
-# 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
 ```

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

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

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
   </TabItem>
 </Tabs>
 
-## Finding Your Recipes
+## Finding Available Recipes
 
 <Tabs groupId="interface">
   <TabItem value="desktop" label="goose Desktop" default>
 
 **Access Recipe Library:**
 1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
-2. Click `Recipes`
+2. Click `Recipes` to view your Recipe Library
-3. Browse the list of your saved recipes  
+3. Browse your available recipes, which show:
-4. Each recipe shows its title, description, and whether it's global or local
+   - 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.
+:::
 
   </TabItem>
   <TabItem value="cli" label="goose CLI">
 
-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.
 :::
 
   </TabItem>