Interactive Mode Guide

Capcat's interactive mode provides a user-friendly menu interface for all operations without requiring command-line arguments or flags.

Quick Start

Launch interactive mode:

./capcat catch

Main Menu

When you launch ./capcat catch, you see:

  What would you like me to do?

  > Catch articles from a bundle of sources
    Catch articles from a list of sources
    Catch from a single source
    Catch a single article by URL
    Manage Sources (add/remove/configure)
    Exit

   (Use arrow keys to navigate)

Navigation:

Arrow keys: Move between options
Enter: Select option
Ctrl+C: Exit at any time

Main Menu Options

1. Catch Articles from a Bundle

Fetch articles from predefined source groups.

Flow:

Select bundle (tech, news, science, ai, sports)
Choose HTML generation (yes/no)
Confirm and execute

Example:

  Select a news bundle and hit Enter for activation.

  > tech - Technology News
    (IEEE, Mashable)

    news - General News
    (BBC News, The Guardian)

    science - Science News
    (Nature News, Scientific American)

    ai - AI & Machine Learning
    (MIT News)

    sports - Sports News
    (BBC Sport)

Bundle Auto-Discovery:

Bundles automatically include:

Sources explicitly listed in bundles.yml
Sources with matching category from registry
Example: "tech" bundle includes all sources with category: tech

Default Count:

Bundles fetch default number of articles per source (typically 30)
Cannot be changed interactively (use CLI for custom counts)

2. Catch Articles from a List of Sources

Select multiple sources to fetch from simultaneously.

Flow:

Select sources with spacebar (checkbox mode)
Press Enter to confirm selection
Choose HTML generation
Execute

Example:

  Select sources with <space> and press Enter to continue:

  [ ] hn              Hacker News
  [x] lb              Lobsters
  [x] iq              InfoQ
  [ ] bbc             BBC News
  [ ] guardian        The Guardian

   (Use <space> to select, <enter> to confirm)

Tips:

Select as many sources as needed
Sources are grouped by category for easy browsing
No limit on number of selections

3. Catch from a Single Source

Fetch articles from one specific source.

Flow:

Select source from list
Choose HTML generation
Execute

Example:

  Select a source and hit Enter for activation.

  > hn              Hacker News
    lb              Lobsters
    iq              InfoQ
    bbc             BBC News
    guardian        The Guardian

Use Case:

Testing a specific source or fetching focused content.

4. Catch a Single Article by URL

Download and convert a single article from any URL.

Flow:

Enter article URL
Choose HTML generation
Execute

Example:

  (Use Ctrl+C to go to the Main Menu)

  Please enter the article URL: https://example.com/article

  Generate HTML for web browsing?
  > Yes
    No

Supported:

Any publicly accessible article URL
Works with sources not in registry
Automatic content extraction
Media download (images always, videos/docs with --media flag)

5. Manage Sources (add/remove/configure)

Enter source management submenu.

See Source Management Submenu section below.

6. Exit

Leave interactive mode and return to shell.

Source Management Submenu

Accessed via "Manage Sources" from main menu.

Source Management - Select an option: > Add New Source from RSS Feed Generate Custom Source Config Remove Existing Sources List All Sources Test a Source ──────────────── Back to Main Menu (Use arrow keys to navigate)

Add New Source from RSS Feed

Quick source addition from RSS/Atom feeds.

Flow:

Enter RSS feed URL
System inspects feed and extracts metadata
Review auto-suggested source ID
Select category
Optionally add to bundle
Optionally test source

Example:

  Enter the RSS feed URL: https://example.com/article

[OK] Feed 'TechCrunch' found.

Source ID: techcrunch
Category: tech
Add to bundle? Yes
  Select bundle: tech
[OK] Added 'techcrunch' to bundle 'tech'.

Test fetch? Yes
[OK] Source added and verified successfully!

What It Creates:

YAML config in sources/active/config_driven/configs/
Registry entry (automatic on next run)
Bundle entry (if selected)

Generate Custom Source Config

Create comprehensive YAML configuration with all options.

Flow:

Interactive wizard with detailed prompts
Configure all source parameters
YAML file generated and saved
Instructions provided for testing

Configurable Options:

Source ID and display name
Category (tech, news, science, ai, sports, other)
Base URL
Discovery method (RSS feed or HTML scraping)
Article link selectors (CSS/XPath)
Content extraction selectors
Image processing rules
Author/date extraction patterns
Rate limiting (seconds between requests)
Request timeout
Skip patterns (URLs to avoid)
Template selection

Output Location:

sources/active/config_driven/configs/sourceid.yaml

Next Steps:

# Review configuration
cat sources/active/config_driven/configs/newsource.yaml

# Test source
./capcat fetch newsource --count 5

# Add to bundle (edit bundles.yml)
vim sources/active/bundles.yml

Remove Existing Sources

Interactive source removal with safety features.

Flow:

View list of available sources with usage stats
Select sources to remove (checkbox mode)
Review changes
Confirm removal
Automatic backup created
Sources removed from all locations

Safety Features:

Automatic backup to .capcat-backups/
Usage analytics displayed
Confirmation required
Undo capability available

What Gets Removed:

Config files (sources/active/config_driven/configs/ or sources/active/custom/)
Bundle definitions (from bundles.yml)
Registry cache

Backup Structure:

.capcat-backups/ └── backup_YYYYMMDD_HHMMSS/ ├── configs/ ├── bundles.yml └── manifest.json

Undo Last Removal:

./capcat remove-source --undo

List All Sources

Display all available sources grouped by category.

Output Format:

--- Available Sources ---

TECH:
  - ieee           IEEE Spectrum
  - mashable       Mashable

TECHPRO:
  - hn             Hacker News
  - lb             Lobsters
  - iq             InfoQ

NEWS:
  - bbc            BBC News
  - guardian       The Guardian

SCIENCE:
  - nature         Nature News
  - scientificamerican Scientific American

AI:
  - mitnews        MIT News

SPORTS:
  - bbcsport       BBC Sport

Total: 11 sources

Use Cases:

Audit available sources
Find source IDs for CLI commands
Check categorization
Identify gaps in coverage

Test a Source

Validate source functionality by fetching sample articles.

Flow:

Select source from list
System fetches 3 test articles
Results displayed
Success/failure indication

Example:

--- Testing Source: hn ---
Fetching 3 articles...

[OK] Article 1: "New AI Model Released"
[OK] Article 2: "Programming Best Practices"
[OK] Article 3: "Tech Industry Trends"

[OK] Source 'hn' test completed

Use Cases:

Verify new source works
Troubleshoot source issues
Check after configuration changes
Validate after website updates

What It Tests:

Network connectivity
Article discovery
Content extraction
Media download
Markdown conversion

HTML Generation

All main operations prompt for HTML generation.

Options:

Yes
Generate browsable HTML with styling
No
Markdown only

HTML Output:

Article_Folder/ ├── article.md # Always created ├── comments.md # If source supports comments ├── images/ # Downloaded media └── html/ # Only if HTML enabled ├── article.html └── comments.html

When to Use HTML:

Web browsing convenience
Sharing with non-technical users
Visual verification
Archival with styling

When to Skip:

CLI-only workflows
Minimal disk usage
Processing with markdown tools
Speed optimization

Execution Summary

Before execution, interactive mode shows a summary:

--------------------
SUMMARY
Action: bundle
Bundle: tech
Generate HTML: true
--------------------

Executing command...

What Happens:

Arguments validated
Sources initialized
Articles fetched
Content processed
Media downloaded
Files written
HTML generated (if enabled)
Success confirmation

Return to Menu:

After execution completes, press Enter to return to main menu.

CLI Equivalents

All interactive operations have CLI equivalents:

Bundle
→ ./capcat bundle tech --count 30
List of sources
→ ./capcat fetch hn,bbc --count 30
Single source
→ ./capcat fetch hn --count 30
Single URL
→ ./capcat single https://example.com/article
Add RSS source
→ ./capcat add-source --url
Generate config
→ ./capcat generate-config
Remove sources
→ ./capcat remove-source
List sources
→ ./capcat list sources
Test source
→ ./capcat fetch --count 3

CLI Advantages:

Custom count values
Scriptable
Automation-friendly
Advanced flags (--media, --verbose, -L)

Interactive Advantages:

No flag memorization
Guided workflows
Visual feedback
Error prevention

Advanced Features

Screen Management

Interactive mode automatically:

Clears screen between menus
Maintains clean display
Shows selected options
Hides logging noise

Logging Suppression

During menu navigation, logging is suppressed to prevent clutter.

When Active:

Showing menus
Collecting input
Navigation

When Disabled:

During execution
Error messages
Progress updates

Session Continuity

After each operation:

Return to main menu
Previous selections not remembered
Fresh state each time
No persistent session

Error Handling

Errors display helpful messages:

Error adding source: Invalid RSS feed URL

Press Enter to continue...

Recovery:

Returns to menu
No data loss
Can retry operation
Clear error description

Keyboard Shortcuts

Universal:

Arrow keys: Navigate options
Enter: Confirm selection
Ctrl+C: Cancel/go back
Space: Toggle checkbox (multi-select)

Text Input:

Tab: Autocomplete (if available)
Backspace: Delete character
Ctrl+U: Clear line
Ctrl+C: Cancel input

Best Practices

For New Users

Start with
"List All Sources"
to see what's available
Test with
"Catch from a single source"
first
Use
bundles
once comfortable
Enable
HTML generation
for visual verification

For Source Management

Always
test after adding
a source
Use
meaningful source IDs
(lowercase, no spaces)
Categorize correctly
for bundle auto-discovery
Remove unused sources
periodically

For Daily Use

Bundles
for routine fetching
List of sources
for custom combinations
Single URL
for ad-hoc articles
Test source
before reporting issues

Troubleshooting

Menu Not Appearing

# Check wrapper system
./capcat --help

# Try Python wrapper directly
python3 run_capcat.py catch

# Check dependencies
source venv/bin/activate
python -c "import questionary"

Selection Not Working

Ensure terminal supports ANSI codes
Check keyboard/terminal compatibility
Try different terminal emulator
Use CLI commands as fallback

Source Not Listed

After adding a source:

Check config file was created
Verify YAML syntax (no tabs, proper indentation)
Restart Capcat to reload registry
Check error messages in logs

For existing sources:

Run ./capcat list sources
Check if source was removed
Verify source directory structure
Review registry discovery logs

Test Fetch Fails

Common Causes:

Network connectivity issues
Website structure changed
Anti-bot protection
Invalid selectors
Rate limiting

Debugging:

# Detailed logging
./capcat -V fetch sourceid --count 3

# Check configuration
cat sources/active/config_driven/configs/sourceid.yaml

# Manual test
curl -I https://source-url.com

Integration with Workflows

Development Workflow

# 1. Add new source interactively
./capcat catch
  > Manage Sources
  > Add New Source from RSS Feed

# 2. Test thoroughly
./capcat catch
  > Manage Sources
  > Test a Source

# 3. Use in production
./capcat bundle tech --count 50

Content Curation Workflow

# Morning routine
./capcat catch
  > Catch articles from a bundle
  > tech
  > Yes (HTML)

# Ad-hoc interesting article
./capcat catch
  > Catch a single article by URL
  > [paste URL]

Maintenance Workflow

# Weekly audit
./capcat catch
  > Manage Sources
  > List All Sources

# Remove outdated
./capcat catch
  > Manage Sources
  > Remove Existing Sources

# Verify remaining
./capcat catch
  > Manage Sources
  > Test a Source

Implementation Details

Technology Stack

UI Framework
questionary (prompt_toolkit)
Styling
Custom ANSI color scheme (orange theme)
Screen Control
ANSI escape codes
Input Handling
Arrow keys, space, enter

Code Structure

core/ └── interactive.py # Main interactive module ├── start_interactive_mode() # Main menu loop ├── _handle_bundle_flow() # Bundle selection ├── _handle_fetch_flow() # Multi-source selection ├── _handle_single_source_flow() # Single source selection ├── _handle_single_url_flow() # URL input ├── _handle_manage_sources_flow() # Source management submenu ├── _handle_add_source_from_rss() # RSS source addition ├── _handle_generate_config() # Config generator ├── _handle_remove_source() # Source removal ├── _handle_list_sources() # Source listing ├── _handle_test_source() # Source testing ├── _prompt_for_html() # HTML generation prompt └── _confirm_and_execute() # Execution handler

Color Scheme

custom_style = Style([
    ('questionmark', 'fg:#d75f00 bold'),  # Orange question mark
    ('question', 'bold'),                 # Bold question text
    ('selected', 'fg:#d75f00'),          # Orange for selected option
    ('pointer', 'fg:#d75f00 bold'),      # Orange pointer
    ('answer', 'fg:#d75f00'),            # Orange answer
])

Integration Points

With CLI:

Uses same run_app() function
Constructs argument list programmatically
Handles SystemExit exceptions

With Core:

Imports from cli module
Uses get_available_sources()
Uses get_available_bundles()
Integrates with source registry

With Source System:

Source management commands
Registry operations
Backup manager
Analytics system

Comparison: Interactive vs CLI

Learning Curve
→ Low
Speed
→ Moderate
Scriptable
→ No
Custom Counts
→ No
Media Flag
→ No
Error Prevention
→ High
Visual Feedback
→ Excellent
Automation
→ Not suitable
Documentation Needed
→ Minimal
New User Friendly
→ Yes

Recommendation:

Interactive
Daily use, source management, new users
CLI
Scripts, custom parameters, advanced users, automation

Future Enhancements

Potential additions to interactive mode:

Custom count selection in bundles
Media flag toggle
Verbose output option
Configuration editing
Bundle creation/editing
Source statistics dashboard
Scheduling interface
Export/import configurations

Interactive mode makes Capcat accessible to users of all skill levels while maintaining full power for advanced users through CLI commands.

Interactive Mode Guide

Quick Start

Main Menu

Navigation:

Main Menu Options

1. Catch Articles from a Bundle

Flow:

Example:

Bundle Auto-Discovery:

Default Count:

2. Catch Articles from a List of Sources

Flow:

Example:

Tips:

3. Catch from a Single Source

Flow:

Example:

Use Case:

4. Catch a Single Article by URL

Flow:

Example:

Supported:

5. Manage Sources (add/remove/configure)

6. Exit

Source Management Submenu

Add New Source from RSS Feed

Flow:

Example:

What It Creates:

Generate Custom Source Config

Flow:

Configurable Options:

Output Location:

Next Steps:

Remove Existing Sources

Flow:

Safety Features:

What Gets Removed:

Backup Structure:

Undo Last Removal:

List All Sources

Output Format:

Use Cases:

Test a Source

Flow:

Example:

Use Cases:

What It Tests:

HTML Generation

Options:

Yes

No

HTML Output:

When to Use HTML:

When to Skip:

Execution Summary

What Happens:

Return to Menu:

CLI Equivalents

Bundle

List of sources

Single source

Single URL

Add RSS source

Generate config

Remove sources

List sources

Test source

CLI Advantages:

Interactive Advantages:

Advanced Features

Screen Management

Logging Suppression

When Active:

When Disabled:

Session Continuity

Error Handling

Recovery:

Keyboard Shortcuts

Universal: