529.x-list-search CLI Design Principle: Consolidate list/search with optional query argument

[codekiln]

Overview

Establish and document a CLI design principle: all commands should consolidate list and search into a single list [query] command with optional positional query argument.

Parent Issue

This is a sub-issue of #529 (ls-cli-output-dx milestone).

Problem Statement

Having separate list and search commands is confusing for AI agents (and users):

$ langstar <resource> --help
Commands:
  list    List all <resources>
  search  Search for <resources>

User request: "Find datasets about testing"
Claude's confusion: Should I use list or search? The help text doesn't clarify the distinction!

This pattern exists inconsistently across langstar commands.

Design Principle

Single Command Pattern: All resource list commands should accept an optional positional query argument for filtering/searching.

langstar <resource> list                      # List all (paginated)
langstar <resource> list <query>              # Search/filter by query
langstar <resource> list "multi word query"   # Multi-word requires quotes

Implementation Pattern

List {
    /// Optional search query (use quotes for multi-word searches)
    query: Option<String>,
    
    /// Maximum number of results
    #[arg(short, long, default_value = "20")]
    limit: u32,
    
    /// Number of results to skip
    #[arg(short, long, default_value = "0")]
    offset: u32,
    
    // ... other command-specific flags
}

Key decisions:

• Query is optional positional argument (not a flag)
• Multi-word queries require quotes (simplest, matches gh behavior)
• Same --limit applies whether listing or searching
• Existing pagination flags (--offset, --limit) work consistently

Commands to Update

Based on current codebase analysis:

Command	Has list?	Has search?	Action Needed
prompt	✅	✅	Consolidate (reference: #679)
dataset	✅	❌	Add query support
runs	✅	❌	Add query support
deployment	✅	❌	Add query support
assistant	✅	❌	Add query support
queue	✅	❌	Add query support
eval	✅	❌	Add query support
secrets	✅	❌	Add query support
model-config	✅	❌	Add query support

Note: Only prompt currently has both list and search commands that need consolidation.

Reference Implementation

Issue #679 (ls-prompt-ux milestone) implements this pattern for prompt commands:

# Before (confusing)
langstar prompt list
langstar prompt search "rag"

# After (clear)
langstar prompt list
langstar prompt list rag
langstar prompt list "structured output"

This becomes the reference implementation for all other commands.

Migration Strategy

For prompts (has both list and search)

1. Add query as optional positional argument to list
2. Deprecate search command with warning
3. Remove search in future major version

For other commands (list only)

1. Add query as optional positional argument to existing list
2. Update help text to clarify search behavior
3. No breaking changes needed

Documentation

Create docs/dev/cli-design-principles.md documenting this and other CLI patterns:

# CLI Design Principles

## List/Search Pattern

All resource list commands accept optional search query as positional argument.

**Pattern**: `langstar <resource> list [query] [flags]`

**Examples**:
- `langstar prompt list` - List all
- `langstar prompt list rag` - Search for "rag"
- `langstar dataset list "test data"` - Multi-word search

**Rationale**: 
- AI-first: Clearer for Claude reading `--help`
- User-friendly: Natural language mapping
- Consistent: Same pattern everywhere

Implementation Order

1. ✅ Prompts - Reference implementation (tracked in 668.0-design Design prompt command structure for AI-first UX and prompt engineering workflows #679)
2. Dataset - Second implementation to validate pattern
3. Runs - Third implementation
4. Others - Roll out systematically after pattern is proven

Each implementation should be a separate sub-issue with testing.

Success Criteria

• Reference implementation complete in 668.0-design Design prompt command structure for AI-first UX and prompt engineering workflows #679 (prompts)
• Design principle documented in docs/dev/cli-design-principles.md
• Pattern applied to at least 3 commands (prompt, dataset, runs)
• All list commands across langstar accept optional query
• Help text consistently explains search behavior
• No separate search commands remain

Help Text Example

List <resources>, optionally filtered by search query

Usage: langstar <resource> list [QUERY] [OPTIONS]

Arguments:
  [QUERY]  Optional search query to filter results (use quotes for multi-word: "test data")

Options:
  -l, --limit <LIMIT>    Maximum number of results [default: 20]
  -o, --offset <OFFSET>  Number of results to skip [default: 0]
  -f, --format <FORMAT>  Output format (table, json, text) [default: table]
  -h, --help             Print help

Examples:
  # List all resources
  langstar <resource> list
  
  # Search for specific resources
  langstar <resource> list rag
  langstar <resource> list "structured output"
  
  # Combine with other flags
  langstar <resource> list test --limit 50 --format json

References

• Parent issue: ls-cli-output-dx milestone - Improve CLI output developer experience across all commands #529 (ls-cli-output-dx)
• Reference implementation: 668.0-design Design prompt command structure for AI-first UX and prompt engineering workflows #679 (ls-prompt-ux)
• Milestone: ls-cli-output-dx (Configure Claude Code Action to use .claude/settings.json #12)
• Related: ls-prompt-ux milestone - Improve UX consistency across prompt commands #668 (ls-prompt-ux milestone)

Next Steps

1. Wait for 668.0-design Design prompt command structure for AI-first UX and prompt engineering workflows #679 reference implementation to complete
2. Create sub-issues for each command update
3. Document pattern in docs/dev/cli-design-principles.md
4. Update milestone ls-cli-output-dx milestone - Improve CLI output developer experience across all commands #529 description with this principle