Skip to content

TUI Client (straw)

The Straw TUI client (straw) provides an interactive interface for monitoring and managing the Straw daemon.

Overview

The TUI client: - Connects to the daemon via IPC - Displays real-time filesystem events - Shows rule execution status - Provides interactive rule creation wizard - Allows configuration reloading

Launching the TUI

# Default config location
straw

# Custom config
straw --config /path/to/config.toml

Interface

The TUI consists of several views:

Main View

The main view displays: - Event Log: Real-time filesystem events - Rule Status: Active rules and match counts - Watch Status: Monitored directories - System Status: Daemon connection status

Key Action
↑/↓ or j/k Navigate through lists
Tab Switch between panels
Enter Select/confirm
r Reload configuration
w Open Rule Wizard
q or Ctrl+c Quit

Rule Wizard

The Rule Wizard helps you create rules interactively without editing the config file manually.

Accessing the Wizard

Press w in the main view to open the Rule Wizard.

Wizard Steps

  1. Rule Name
  2. Enter a descriptive name for your rule

  3. Example: "Organize PDF Downloads"

  4. Enable Rule

  5. Toggle whether the rule is active

  6. Default: Enabled

  7. Match Criteria

  8. Select match type:
    • Glob: Pattern matching (e.g., *.pdf)
    • Regex: Regular expression
    • Extension: File extension
    • Size: File size range
    • Age: File age range
    • Hidden: Hidden file status
  9. Enter the criteria value

  10. Add additional criteria (optional)

  11. Actions

  12. Select action type:
    • Move: Move file to directory
    • Copy: Copy file to directory
    • Trash: Move to system trash
    • Shell: Execute command
  13. Configure action parameters

  14. Add additional actions

  15. Review & Save

  16. Review the rule configuration
  17. Save to config file
  18. Or go back to edit

Example Wizard Session

Rule Name: Clean Old Logs
Enabled: Yes

Match Criteria:
- Extension: .log
- Min Age: 7 days

Actions:
1. Trash

Save this rule? [Yes/No]

Views and Panels

Event Log Panel

Shows filesystem events as they happen:

[14:32:15] Created: /home/user/Downloads/report.pdf
[14:32:16] Rule matched: "Organize PDFs"
[14:32:16] Action: Move to /home/user/Documents/PDFs
[14:32:16] Completed: /home/user/Documents/PDFs/report.pdf

Rules Panel

Lists all configured rules with status:

Rules (3)
---------
[✓] Organize PDFs        (12 matches)
[✓] Clean Temp Files     (45 matches)
[✗] Backup Important     (disabled)

Watches Panel

Shows watched directories:

Watches (2)
-----------
[✓] ~/Downloads (recursive)
[✓] ~/Desktop

Commands

Reload Configuration

Press r to reload the configuration without restarting the daemon.

Create New Rule

Press w to open the Rule Wizard and create a new rule.

Filter Events

Use / to filter the event log by: - Filename pattern - Rule name - Action type

Export Log

Press e to export the current event log to a file.

Keyboard Shortcuts

Global

Key Action
q Quit
? Show help
Tab Next panel
Shift+Tab Previous panel

Event Log

Key Action
↑/↓ Scroll
Page Up/Down Scroll faster
Home/End Jump to start/end
/ Filter
e Export
c Clear

Rules Panel

Key Action
↑/↓ Navigate rules
Enter Toggle enable/disable
d Delete rule
e Edit rule

Wizard

Key Action
↑/↓ Navigate fields
Tab Next field
Enter Confirm
Esc Cancel/Go back

Configuration

TUI Settings

The TUI uses the same configuration file as the daemon. Additional TUI-specific settings can be added:

[tui]
refresh_rate = 100  # milliseconds
show_timestamps = true
max_events = 1000

Themes

The TUI supports theming via the configuration:

[tui.theme]
primary = "#6c5ce7"
secondary = "#a29bfe"
success = "#00b894"
warning = "#fdcb6e"
error = "#d63031"

Troubleshooting

TUI Won't Start

  1. Check daemon is running: 

    systemctl --user status strawd

  2. Verify socket path: 

    ls -la /tmp/straw.sock

  3. Check config file: 

    straw --config ~/.config/straw/config.toml

Connection Lost

If the TUI shows "Connection Lost":

  1. Check if daemon crashed: systemctl --user status strawd
  2. Restart the daemon: systemctl --user restart strawd
  3. Press r in the TUI to reconnect

Display Issues

If the TUI doesn't render correctly:

  1. Check terminal support:
  2. Ensure your terminal supports Unicode

  3. Try a different terminal emulator

  4. Resize terminal:

  5. Minimum recommended size: 80x24

  6. The TUI adapts to smaller sizes but may truncate content

  7. Disable mouse support: 

    [tui]
mouse = false

Tips

  1. Use the Rule Wizard for quick rule creation without editing TOML
  2. Filter events to focus on specific file types or rules
  3. Export logs periodically for debugging or auditing
  4. Reload config after manual edits instead of restarting the daemon
  5. Use keyboard shortcuts for faster navigation