Recipe Command

Manage and validate Goose recipes

The recipe command provides utilities for working with Goose recipes - YAML templates that define custom agent configurations.

Usage

goose recipe <subcommand> [OPTIONS]

Subcommands

Validate

Validate a recipe file.

goose recipe validate <RECIPE_NAME>

Arguments:

recipe_name · string · required

Recipe name or full path to the recipe file to validate.

Can be:

• Recipe name from GitHub (if GOOSE_RECIPE_GITHUB_REPO configured)
• Local file path to YAML file

Examples:

goose recipe validate my-recipe
goose recipe validate /path/to/recipe.yaml
goose recipe validate ./recipes/analyze.yaml

Output:

✓ recipe file is valid

Or if invalid:

✗ recipe file is invalid: Missing required field 'prompt'

Deeplink

Generate a deeplink URL for a recipe.

goose recipe deeplink <RECIPE_NAME> [--param KEY=VALUE...]

Arguments:

recipe_name · string · required

Recipe name or full path to the recipe file.

Options:

--param · key=value · default: "[]"

Recipe parameter in key=value format. Can be specified multiple times.

Short: -p

Example: --param username=alice --param channel=goose-team

Examples:

goose recipe deeplink analyze-code
goose recipe deeplink my-recipe --param user=alice --param task=review
goose recipe deeplink /path/to/recipe.yaml -p env=production

Output:

✓ Generated deeplink for: Code Analysis Recipe
goose://recipe?config=eyJ0aXRsZSI6IkNvZGUgQW5...&username=alice&channel=goose-team

Use Cases:

• Share recipe configurations
• Create bookmarkable workflows
• Integrate with external tools
• Pre-fill recipe parameters

Open

Open a recipe in Goose Desktop.

goose recipe open <RECIPE_NAME> [--param KEY=VALUE...]

Arguments:

recipe_name · string · required

Recipe name or full path to the recipe file.

Options:

--param · key=value · default: "[]"

Recipe parameter in key=value format. Can be specified multiple times.

Short: -p

Examples:

goose recipe open analyze-code
goose recipe open my-recipe --param user=alice --param env=dev
goose recipe open ./recipe.yaml

Output:

✓ Opened recipe 'Code Analysis Recipe' in Goose Desktop

Or if Desktop not available:

✗ Failed to open recipe in Goose Desktop: desktop not found
Generated deeplink: goose://recipe?config=...
You can manually copy and open the URL above

List

List available recipes.

goose recipe list [OPTIONS]

Options:

--format · string · default: "text"

Output format: text or json

--verbose · boolean · default: "false"

Show verbose information including recipe descriptions.

Short: -v

Examples:

goose recipe list
goose recipe list --format json
goose recipe list --verbose

Text Output:

Available recipes:
analyze-code - Performs code analysis and review - local: ./recipes/analyze.yaml
test-generator - Generates unit tests - github: recipes/test-gen.yaml

Verbose Output:

Available recipes:
  analyze-code - Performs code analysis and review - local: ./recipes/analyze.yaml
    Title: Code Analysis Recipe
    Path: /home/user/recipes/analyze.yaml

JSON Output:

[
  {
    "name": "analyze-code",
    "title": "Code Analysis Recipe",
    "description": "Performs code analysis and review",
    "path": "./recipes/analyze.yaml",
    "source": "Local"
  }
]

Recipe Sources

Recipes can be loaded from:

Local Files

YAML files on your filesystem:

goose recipe validate ./my-recipe.yaml
goose recipe validate /absolute/path/to/recipe.yaml

GitHub Repository

If GOOSE_RECIPE_GITHUB_REPO is configured:

export GOOSE_RECIPE_GITHUB_REPO=username/recipes
goose recipe validate my-recipe  # Fetches from GitHub

Or configure permanently:

goose configure
# Select: goose settings → goose recipe github repo
# Enter: username/recipes

Recipe Format

Recipes are YAML files with this structure:

title: "My Recipe"
description: "Recipe description"
version: "1.0"

prompt: |
  System instructions for the AI agent.
  Can include parameters: {{ username }}

instructions: |
  Additional context and guidance.
  Parameters work here too: {{ task }}

parameters:
  username:
    type: string
    description: "User name"
    required: true
  task:
    type: string  
    description: "Task to perform"
    default: "analyze"

response:
  json_schema:
    type: object
    properties:
      result:
        type: string
        description: "Analysis result"
    required:
      - result

Using Recipes

With Run Command

Execute a recipe:

goose run --recipe analyze-code
goose run --recipe ./recipe.yaml --params user=alice --params task=review

See: Run Command documentation for details.

With Parameters

Pass parameters to recipes:

goose run --recipe my-recipe \
  --params username=alice \
  --params task=review \
  --params env=production

Explain Recipe

Show recipe details before running:

goose run --recipe analyze-code --explain

Output:

Title: Code Analysis Recipe
Description: Performs comprehensive code analysis

Parameters:
  - file (required): Path to file to analyze
  - depth (optional): Analysis depth (default: full)

Render Recipe

Print the rendered recipe YAML:

goose run --recipe my-recipe \
  --params user=alice \
  --render-recipe

Shows the final YAML with parameters substituted.

Validation

Recipe validation checks:

• Required fields: title, prompt
• Schema validation: JSON schema syntax
• Parameter references: All {{ param }} references exist
• YAML syntax: Valid YAML structure
• Type checking: Parameter types match usage

Example errors:

✗ recipe file is invalid: Missing required field 'title'
✗ recipe file is invalid: Invalid JSON schema
✗ recipe file is invalid: Parameter 'username' referenced but not defined

Examples

Create and validate recipe:

# Create recipe.yaml
cat > recipe.yaml << 'EOF'
title: "Test Generator"
description: "Generate unit tests"
prompt: |
  Generate unit tests for {{ file }}
instructions: |
  Use {{ framework }} testing framework
parameters:
  file:
    type: string
    required: true
  framework:
    type: string
    default: "jest"
EOF

# Validate
goose recipe validate recipe.yaml

Generate deeplink with parameters:

goose recipe deeplink test-generator \
  --param file=src/utils.ts \
  --param framework=vitest

List and filter recipes:

# All recipes
goose recipe list

# With descriptions
goose recipe list --verbose

# JSON for scripting
goose recipe list --format json | jq '.[] | select(.source == "Local")'

Open in Desktop:

goose recipe open analyze-code --param file=main.ts

Recipe Repository

Configure a GitHub repository for shared recipes:

# Set repository
export GOOSE_RECIPE_GITHUB_REPO=myorg/goose-recipes

# Or configure permanently
goose configure
# Select: goose settings → goose recipe github repo

Then reference recipes by name:

goose recipe validate code-review
goose run --recipe test-generator

Goose will fetch from: https://github.com/myorg/goose-recipes/recipes/<name>.yaml

See Also

• Run Command - Execute recipes
• Configure Command - Set recipe repository
• Recipe authoring guide (link to guide)