SPOUT provides robust terminal-based interfaces through a Command-Line Interface (CLI), also known as a Terminal User Interface (TUI). These tools enable scriptable interactions with SPOUT's core modules and spoutlets.
Command Structure
The basic command structure follows this pattern:
spout [OPTIONS] COMMAND [ARGS]...
Global Options
| Option | Shortcut | Description |
|---|---|---|
--timer | -m | Display processing time |
--preferred_model | -p | List available models or set preferred model |
--help | -h | Show help information |
Core Commands
Below is a detailed overview of SPOUT's core commands, their descriptions, usage, options, and examples.
Converse
Description: Apply the conversational intelligence of an LLM.
Usage:
spout converse [OPTIONS]
Features:
- Maintains conversation context and history
- Customizable conversation primer and rules
- Supports different AI models
- Persistent conversation storage
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--primer TEXT | -p | Initial context or instructions for the conversation (required) |
--history-file TEXT | -f | Path to the conversation history file |
--recent-message TEXT | -r | The most recent message in the conversation (required) |
--model TEXT | -m | AI model to use for the conversation |
--help | -h | Show help message and exit |
Examples:
spout converse --primer 'You are a helpful assistant' --history_file 'chat_history.txt' --recent_message 'Hello'
spout converse -p 'You are a coding tutor' -f 'python_help.txt' -r 'How do I use lists?' -m gpt-4o
Enhance
Description: Improve the quality and clarity of an input text.
Usage:
spout enhance [TEXT]
Features:
- Refines grammar and word choice
- Improves clarity and readability
- Strengthens overall structure
- Maintains original meaning and intent
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--help | -h | Show help message and exit |
Examples:
spout enhance 'Text that needs improvement'
spout enhance # Uses clipboard content
Evaluate
Description: Compare multiple inputs based on specified criteria.
Usage:
spout evaluate [OPTIONS]
Features:
- Detailed ranking of multiple inputs with scores
- Customizable evaluation criteria with optional weights
- Optional explanations for each ranking
- JSON output with rankings, scores, and explanations
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--combined-inputs TEXT | -i | Multiple inputs to evaluate, combined into a single string (required) |
--separator TEXT | -s | Character or string that separates the inputs |
--judging-criteria TEXT | -c | Criteria for evaluating and comparing the inputs (required) |
--explanation TEXT | -e | Additional context or explanation for the evaluation |
--help | -h | Show help message and exit |
Examples:
spout evaluate -i 'Option A@@Option B@@Option C' -s '@@' -c 'clarity:0.6,conciseness:0.4' -e true
spout evaluate --combined-inputs 'The cat sat on the mat@@A feline rested upon the floor covering@@The small cat positioned itself atop the mat' --separator '@@' --judging-criteria 'simplicity,directness' --explanation true
Expand
Description: Elaborate and expand upon an input text.
Usage:
spout expand [TEXT]
Features:
- Adds relevant details and examples
- Elaborates on key points
- Provides additional context
- Maintains original tone and style
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--help | -h | Show help message and exit |
Examples:
spout expand 'AI is changing technology'
spout expand # Uses clipboard content
Generate
Description: Generate text items based on a description and example.
Usage:
spout generate [OPTIONS]
Features:
- Generates content matching your description
- Uses provided examples as reference
- Can generate multiple items in a batch
- Avoids duplicates with already generated content
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--description TEXT | -d | Description of what to generate (required) |
--example TEXT | -e | Example to base the generation on |
--batch-size TEXT | -b | Number of items to generate (defaults to 5 in CLI, 1 in GUI) |
--already-gen TEXT | -a | List of already generated items to avoid duplicates |
--help | -h | Show help message and exit |
Examples:
spout generate -d 'Product name for a coffee shop' -e 'Morning Brew'
spout generate --description 'Blog title about AI' --example 'The Future of Machine Learning' --batch-size 3
Imagine
Description: Generate plans and ideas based on specified objectives.
Usage:
spout imagine [OPTIONS]
Features:
- Creates structured, step-by-step plans
- Incorporates additional context and constraints
- Supports multiple output formats
- Includes module-specific examples via
@Spouttags
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--objective TEXT | -o | Main goal or objective to imagine (required) |
--context TEXT | -c | Additional context, constraints, or information (required) |
--output-format TEXT | -f | Output format for the generated plan |
--stipulations TEXT | -s | Additional stipulations or constraints for the plan |
--help | -h | Show help message and exit |
Examples:
spout imagine -o 'Design a garden' -c 'Small urban space, shade-loving plants' -s 'Budget: $500'
spout imagine --objective 'Write a story' --context '@SpoutCLI' --format 'json'
Iterate
Description: Process multiple items of text using an example transformation.
Usage:
spout iterate [OPTIONS]
Features:
- Learns from an input/output example pair
- Applies the learned transformation to multiple lines
- Can process lines in batches for efficiency
- Maintains consistent transformation across all lines
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--example-preprocessed-line TEXT | -e | Example of input line before processing (required) |
--example-processed-line TEXT | -o | Example of how the input line should be processed (required) |
--description TEXT | -d | Description of the transformation to perform (required) |
--lines-per-call TEXT | -b | Number of lines to process in each API call |
--preprocessed-lines TEXT | -l | Lines to be processed, separated by newlines (required) |
--help | -h | Show help message and exit |
Examples:
spout iterate -e 'data: 123' -o '123' -d 'Extract number' -l 'data: 456\ndata: 789'
spout iterate --example-preprocessed-line 'John Doe' --example-processed-line 'Doe, J.' --description 'Format as last name, first initial' --preprocessed-lines 'Jane Smith\nBob Johnson' --lines-per-call 2
Mutate
Description: Generate context-appropriate variants of an input text.
Usage:
spout mutate [OPTIONS]
Features:
- Generates multiple variants of the same text
- Controls mutation intensity (levels 1-5)
- Targets specific substrings or entire text
- Maintains grammatical correctness and coherence
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--num_variants TEXT | -n | Number of text variants to generate (default: 1) (required) |
--substring TEXT | -s | Specific substring to modify. If not provided or '*', uses entire input |
--mutation_level TEXT | -l | Mutation intensity level (1-5), where 1 is subtle and 5 is dramatic (default: 1) (required) |
--input TEXT | -i | Text to modify. If not provided, will use clipboard content |
--help | -h | Show help message and exit |
Examples:
spout mutate --input 'The quick brown fox jumps over the lazy dog' --substring 'jumps over' --num_variants 3 --mutation_level 1
spout mutate -i 'Hello world' --num_variants 2 --mutation_level 4 # Modifies entire text
Parse
Description: Extract and structure input text based on specified categories.
Usage:
spout parse [OPTIONS]
Features:
- Identifies and extracts relevant information
- Organizes data into requested categories
- Handles multiple categories simultaneously
- Maintains context while parsing
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--input TEXT | -i | Text to parse and analyze |
--categories TEXT | -c | Categories or fields to extract from the text (required) |
--help | -h | Show help message and exit |
Examples:
spout parse -i 'John Doe, Software Engineer, john@example.com' -c 'name, title, email'
spout parse --input 'Product: Widget 2000, Cost: $19.99' --categories 'product_name, price'
Reduce
Description: Generate a more concise version of an input text.
Usage:
spout reduce [TEXT]
Features:
- Reduces text length while preserving meaning
- Extracts key points and main ideas
- Maintains original context and tone
- Supports direct text or clipboard input
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--help | -h | Show help message and exit |
Examples:
spout reduce 'Your long text here'
spout reduce # Uses clipboard content
Search
Description: Generate a list of relevant URLs for research on a given topic.
Usage:
spout search [TEXT]
Features:
- Provides 10-25 relevant URLs
- Includes multiple search engines
- Incorporates academic sources
- Uses specific search parameters
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--help | -h | Show help message and exit |
Examples:
spout search 'Python async programming'
spout search 'Climate change research methods'
spout search # Uses clipboard content
Translate
Description: Modify an input text with a specified parameter, such as translating between languages or formats.
Usage:
spout translate [OPTIONS]
Features:
- Language translation (e.g., English to Spanish)
- Format conversion (e.g., text to JSON)
- Maintains formatting and context
- Supports clipboard input
Options:
| Option | Shortcut | Description |
|---|---|---|
--spoutlet TEXT | -u | Specify the spoutlet to use |
--test TEXT | -t | Run tests for this module (optionally specify test file) |
--examples TEXT | -x | Test and generate example files (optionally specify test file) |
--specification TEXT | -s | Target language or format specification (e.g., 'to Spanish', 'to JSON') (required) |
--input TEXT | -i | Text to translate. If not provided, will use clipboard content |
--help | -h | Show help message and exit |
Examples:
spout translate --specification 'to Spanish' --input 'Hello world'
spout translate -s 'to JSON' -i 'name: John, age: 30'
spout translate -s 'to French' # Uses clipboard content
Testing Features
SPOUT includes comprehensive testing capabilities:
# Run module tests
spout MODULE --test
# Generate examples
spout MODULE --examples
# Test specific spoutlet
spout MODULE --test --spoutlet SPOUTLET_NAME
Model Management
# List available models
spout -p
# Set preferred model
spout -p "model_name"
Scripting Examples
Chain commands for complex workflows:
#!/usr/bin/env bash
# Reduce -> Enhance pipeline
summary=$(spout reduce 'Long text...')
enhanced=$(spout enhance "$summary")
spout generate --description "$enhanced" --batch-size 1
Add-on Commands
SPOUT automatically discovers and loads add-on plugins:
# List all available plugins
spout
# Core commands:
# converse Apply the conversational intelligence of an LLM
# enhance Improve the quality and clarity of an input text
# ...
# Add-on commands:
# prooster Make improvements to an input text prompt
Tip: Use the
--timerflag to measure execution time for performance optimization.
Info: All configuration files are stored in the
spout/config/directory.