Skip to main content
The S2 CLI includes an interactive Terminal User Interface (TUI) for browsing and managing basins and streams visually.

​
Launch interactive mode

Start the TUI: 
s2 -i
# or
s2 --interactive
The TUI will launch in full-screen mode, replacing your terminal display.

​
Features

The interactive mode provides a visual interface for:
  • Browsing basins and streams
  • Viewing stream configurations
  • Monitoring stream activity
  • Quick access to common operations

​
Setup screen

If you launch the TUI without configuring an access token, you’ll see a setup screen prompting you to configure authentication. To configure before launching: 
s2 config set access_token YOUR_TOKEN
Then launch interactive mode: 
s2 -i
The TUI uses standard terminal navigation:

​
Keyboard shortcuts

  • Arrow keys or h/j/k/l - Navigate lists and menus
  • Enter - Select item or confirm action
  • Esc or q - Go back or quit
  • / - Search or filter
  • Tab - Switch between panels
  • Ctrl+C - Exit immediately

​
Mouse support

If your terminal supports mouse input:
  • Click - Select items
  • Scroll - Navigate lists

​
Terminal requirements

​
Supported terminals

The TUI works best with modern terminal emulators:
  • Linux/macOS: iTerm2, Terminal.app, Alacritty, Kitty, GNOME Terminal
  • Windows: Windows Terminal, ConEmu, Cmder

​
Minimum terminal size

Recommended: 80 columns x 24 rows or larger

​
Color support

The TUI uses colors for better readability. Ensure your terminal supports:
  • 256-color mode (recommended)
  • True color (24-bit) for best experience

​
Architecture

The TUI is built using:
  • ratatui - Terminal UI framework
  • crossterm - Cross-platform terminal control
  • tokio - Async runtime for non-blocking operations

​
Limitations

​
Read-only mode

The current TUI implementation is primarily for browsing and viewing. For write operations, use the standard CLI commands.

​
Performance

When browsing accounts with thousands of basins or streams, initial loading may take a moment. The TUI implements pagination to handle large datasets.

​
Troubleshooting

​
Terminal not restored after crash

If the TUI exits unexpectedly and your terminal looks broken: 
reset
This will restore your terminal to its normal state.

​
Display issues

If you see garbled characters or layout problems:
  1. Verify your terminal supports UTF-8: 
    echo $LANG
# Should show something like en_US.UTF-8
  2. Try resizing your terminal window
  3. Ensure terminal is at least 80x24 characters

​
Mouse not working

Mouse support depends on your terminal emulator. Not all terminals support mouse input in TUI applications.

​
Access token errors

If you see authentication errors:
  1. Exit the TUI (press q or Ctrl+C)
  2. Configure your access token: 
    s2 config set access_token YOUR_TOKEN
  3. Relaunch: s2 -i

​
Using TUI over SSH

The TUI works over SSH connections. Ensure:
  1. Your SSH client supports terminal emulation
  2. The TERM environment variable is set correctly: 
    echo $TERM
# Should show xterm-256color, screen-256color, or similar

​
SSH configuration

For best results, enable terminal forwarding in your SSH config: 
# ~/.ssh/config
Host myserver
  Hostname server.example.com
  RequestTTY yes
  SendEnv LANG LC_*

​
Comparison with CLI commands

TaskTUICLI
Browse basinsVisual interfaces2 list-basins
View streamsNavigate with arrowss2 list-streams
View configSelect and views2 get-stream-config
Create basinNot supporteds2 create-basin
Append recordsNot supporteds2 append
Read recordsNot supporteds2 read

​
When to use interactive mode

Use the TUI when:
  • Exploring basins and streams interactively
  • Viewing configurations and metadata
  • Learning the S2 structure of an account
  • Quick browsing without typing long commands
Use CLI commands when:
  • Scripting and automation
  • CI/CD pipelines
  • Writing or reading records
  • Creating or modifying resources
  • Batch operations

​
Examples

​
Quick exploration

# Launch TUI to browse available basins
s2 -i

# Navigate through basins and streams
# Press 'q' to exit when done

​
Find stream configuration

1

Launch TUI

s2 -i
2

Navigate to basin

Use arrow keys to select the basin containing your stream.
3

Select stream

Browse streams and select the one you want to inspect.
4

View configuration

Press Enter to view detailed configuration.
5

Exit

Press ‘q’ to exit the TUI.

​
TUI for discovery, CLI for operations

# Use TUI to find the stream you need
s2 -i
# Note the basin and stream names

# Exit TUI (press 'q')

# Use CLI for actual operations
s2 read s2://basin-name/stream-name --count 100

​
Future enhancements

Planned features for the interactive mode include:
  • Creating basins and streams from TUI
  • Real-time stream tail viewer
  • Metrics and monitoring dashboards
  • Stream search and filtering
  • Configuration editing
Check the S2 roadmap for updates.

​
Accessibility

​
Screen readers

The TUI’s screen reader support is limited. For better accessibility, use the standard CLI commands with output piped to your preferred text-to-speech tool: 
s2 list-basins | your-screen-reader

​
High contrast mode

Most terminals allow you to configure color schemes. Set your terminal to high contrast mode if needed for better visibility.

Build docs developers (and LLMs) love

Get started for freeTalk to us