Search and Discovery Guide
SwissArmyHammer provides powerful search capabilities to help you discover and find prompts in your collection. This guide covers search strategies, advanced filtering, and integration workflows.
Basic Search
Simple Text Search
The most basic way to search is with a simple text query:
# Search for prompts containing "code"
swissarmyhammer search code
# Search for multiple terms
swissarmyhammer search "code review"
# Search with partial matches
swissarmyhammer search debug
Search Results Format
Found 3 prompts matching "code":
📝 code-review (builtin)
Review code for best practices and potential issues
Arguments: code, language (optional)
🔧 debug-helper (user)
Help debug programming issues and errors
Arguments: error, context (optional)
📊 analyze-performance (local)
Analyze code performance and suggest optimizations
Arguments: code, language, metrics (optional)
Each result shows:
- Icon: Indicates prompt type (📝 builtin, 🔧 user, 📊 local)
- Name: Prompt identifier
- Source: Where the prompt is stored
- Description: Brief description of the prompt’s purpose
- Arguments: Required and optional parameters
Field-Specific Search
Search in Titles Only
# Find prompts with "review" in the title
swissarmyhammer search --in title review
# Case-sensitive title search
swissarmyhammer search --in title --case-sensitive "Code Review"
Search in Descriptions
# Find prompts about debugging in descriptions
swissarmyhammer search --in description debug
# Find prompts mentioning specific technologies
swissarmyhammer search --in description "python javascript"
Search in Content
# Find prompts that use specific template variables
swissarmyhammer search --in content "{{code}}"
# Find prompts with specific instructions
swissarmyhammer search --in content "best practices"
Search All Fields
# Search across titles, descriptions, and content (default)
swissarmyhammer search --in all "security"
# Explicit all-field search
swissarmyhammer search "API documentation"
Advanced Search Techniques
Regular Expression Search
Use regex patterns for powerful pattern matching:
# Find prompts with "test" followed by any word
swissarmyhammer search --regex "test\s+\w+"
# Find prompts starting with specific words
swissarmyhammer search --regex "^(debug|fix|analyze)"
# Find prompts with email patterns
swissarmyhammer search --regex "\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b"
# Case-sensitive regex
swissarmyhammer search --regex --case-sensitive "^Code"
Search by Source
Filter prompts by their source location:
# Find only built-in prompts
swissarmyhammer search --source builtin
# Find only user-created prompts
swissarmyhammer search --source user
# Find only local project prompts
swissarmyhammer search --source local
# Combine with text search
swissarmyhammer search review --source user
Search by Arguments
Find prompts based on their argument requirements:
# Find prompts that accept a "code" argument
swissarmyhammer search --has-arg code
# Find prompts with no arguments (simple prompts)
swissarmyhammer search --no-args
# Find prompts with specific argument combinations
swissarmyhammer search --has-arg code --has-arg language
# Combine with text search
swissarmyhammer search debug --has-arg error
Search Strategies
Discovery Workflows
Finding Prompts for a Task
# 1. Start broad
swissarmyhammer search "code review"
# 2. Narrow down by context
swissarmyhammer search "code review" --source user
# 3. Check argument requirements
swissarmyhammer search "code review" --has-arg language
# 4. Examine specific matches
swissarmyhammer search --in title "Advanced Code Review"
Exploring Available Prompts
# See all available prompts
swissarmyhammer search --limit 50 ""
# Browse by category/topic
swissarmyhammer search documentation
swissarmyhammer search testing
swissarmyhammer search refactoring
# Find simple prompts (no arguments)
swissarmyhammer search --no-args
Finding Template Examples
# Find prompts using loops
swissarmyhammer search --in content "{% for"
# Find prompts with conditionals
swissarmyhammer search --in content "{% if"
# Find prompts using specific filters
swissarmyhammer search --in content "| capitalize"
Search Optimization
Performance Tips
# Limit results for faster response
swissarmyhammer search --limit 10 query
# Use specific fields to reduce search scope
swissarmyhammer search --in title query # faster than all fields
# Use source filtering to narrow search space
swissarmyhammer search --source user query
Precision vs. Recall
# High precision (exact matches)
swissarmyhammer search --case-sensitive --regex "^exact pattern$"
# High recall (find everything related)
swissarmyhammer search --in all "broad topic"
# Balanced approach
swissarmyhammer search "specific terms" --limit 20
Integration with Other Commands
Search and Test Workflow
# Find debugging prompts
swissarmyhammer search debug
# Test a specific one
swissarmyhammer test debug-helper
# Test with specific arguments
swissarmyhammer test debug-helper --arg error="TypeError: undefined"
Search and Export Workflow
# Find all review-related prompts
swissarmyhammer search review --limit 20
# Export specific ones found
swissarmyhammer export code-review security-review design-review output.tar.gz
# Or export all matching a pattern
# (manual selection based on search results)
Scripted Search
#!/bin/bash
# find-and-test.sh
QUERY="$1"
if [ -z "$QUERY" ]; then
echo "Usage: $0 <search-query>"
exit 1
fi
echo "Searching for: $QUERY"
PROMPTS=$(swissarmyhammer search --json "$QUERY" | jq -r '.results[].id')
if [ -z "$PROMPTS" ]; then
echo "No prompts found"
exit 1
fi
echo "Found prompts:"
echo "$PROMPTS"
echo "Select a prompt to test:"
select PROMPT in $PROMPTS; do
if [ -n "$PROMPT" ]; then
swissarmyhammer test "$PROMPT"
break
fi
done
JSON Output for Scripting
Basic JSON Search
swissarmyhammer search --json "code review"
{
"query": "code review",
"total_found": 3,
"results": [
{
"id": "code-review",
"title": "Code Review Helper",
"description": "Review code for best practices and potential issues",
"source": "builtin",
"path": "/builtin/review/code.md",
"arguments": [
{"name": "code", "required": true},
{"name": "language", "required": false, "default": "auto-detect"}
],
"score": 0.95
}
]
}
Processing JSON Results
# Extract prompt IDs
swissarmyhammer search --json query | jq -r '.results[].id'
# Get highest scoring result
swissarmyhammer search --json query | jq -r '.results[0].id'
# Filter by score threshold
swissarmyhammer search --json query | jq '.results[] | select(.score > 0.8)'
# Count results by source
swissarmyhammer search --json "" --limit 100 | jq '.results | group_by(.source) | map({source: .[0].source, count: length})'
Search Index Management
Understanding the Search Index
SwissArmyHammer automatically maintains a search index that includes:
- Prompt titles - Weighted heavily in scoring
- Descriptions - Medium weight
- Content text - Lower weight
- Argument names - Considered for relevance
- File paths - Used for source filtering
Index Updates
The search index is automatically updated when:
- Prompts are added to the library
- Existing prompts are modified
- The
serve
command starts (full rebuild) - File watching detects changes
Performance Characteristics
- Index size: Proportional to prompt collection size
- Search speed: Sub-second for collections up to 10,000 prompts
- Memory usage: Moderate (index kept in memory)
- Update speed: Fast incremental updates
Troubleshooting Search Issues
No Results Found
# Check if prompts exist
swissarmyhammer search --limit 100 ""
# Verify prompt sources
swissarmyhammer search --source builtin
swissarmyhammer search --source user
swissarmyhammer search --source local
# Try broader search
swissarmyhammer search --in all "partial terms"
Too Many Results
# Use more specific terms
swissarmyhammer search "specific exact phrase"
# Limit by source
swissarmyhammer search broad-term --source user
# Use field-specific search
swissarmyhammer search --in title specific-title
# Limit result count
swissarmyhammer search broad-term --limit 5
Unexpected Results
# Check what's being matched
swissarmyhammer search --full query
# Use exact matching
swissarmyhammer search --regex "^exact term$"
# Search in specific field
swissarmyhammer search --in description query
Best Practices
Effective Search Terms
- Use specific terms: “REST API documentation” vs. “API”
- Include context: “Python debugging” vs. “debugging”
- Try synonyms: “review”, “analyze”, “examine”
- Use argument names: Search for “code”, “error”, “data” to find relevant prompts
Search Workflow Patterns
- Start broad, narrow down: Begin with general terms, add filters
- Use multiple strategies: Try both fuzzy and regex search
- Check all sources: Don’t assume prompts are only in one location
- Combine with testing: Always test prompts before using
Organization for Searchability
- Clear titles: Use descriptive, searchable titles
- Good descriptions: Include keywords and use cases
- Consistent naming: Use standard terms across prompts
- Tag with arguments: Use predictable argument names
Advanced Examples
Finding Template Patterns
# Find prompts using custom filters
swissarmyhammer search --in content "format_lang"
# Find prompts with error handling
swissarmyhammer search --in content "default:"
# Find prompts with loops
swissarmyhammer search --in content "{% for"
Building Prompt Collections
# Find all code-related prompts
swissarmyhammer search --regex "(code|programming|software)" --limit 50
# Find all documentation prompts
swissarmyhammer search --regex "(doc|documentation|readme|guide)" --limit 30
# Find all analysis prompts
swissarmyhammer search --regex "(analy|review|audit|inspect)" --limit 20
Quality Assurance
# Find prompts without descriptions
swissarmyhammer search --in description "^$" --regex
# Find prompts with no arguments (might need descriptions)
swissarmyhammer search --no-args --limit 50
# Find prompts with many arguments (might be complex)
swissarmyhammer search --json "" --limit 100 | \
jq '.results[] | select(.arguments | length > 5)'
See Also
search
command - Command referencetest
command - Testing found prompts- Prompt Organization - Organizing for discoverability