TTYverse is a command-line client for the fediverse (Mastodon, GoToSocial, etc.). It's designed for terminal users who want a powerful, accessible way to interact with ActivityPub servers.

How is TTYverse different from other fediverse clients?

Accessibility-first design - Built by and for screen reader users
Terminal-native - No GUI dependencies, works over SSH
Single-file architecture - Just one Perl script
Enforced alt-text - Images require descriptions for accessibility

What servers does TTYverse support?

Mastodon - Full support
GoToSocial - Full support
Pleroma - Basic support
Misskey - Limited support
Any ActivityPub server - Basic federation features

Is TTYverse free?

Yes, TTYverse is free software under the Floodgap Free Software License. You can use, modify, and distribute it freely.

Installation and Setup

Do I need to install anything besides TTYverse?

You need Perl and curl, which are available on most Unix-like systems. Optional dependencies improve the experience:

Term::ReadLine::Gnu - Better command line editing
PulseAudio - Sound notifications
w3m/elinks/lynx - Opening links in terminal

Can I run TTYverse on Windows?

Not directly. TTYverse is designed for Unix-like systems. You could try:

WSL (Windows Subsystem for Linux) - Run Linux environment on Windows
Cygwin - Unix-like environment for Windows
Virtual machine - Run Linux in a VM

How do I update TTYverse?

Download the latest version and replace your current script:

wget -O ttyverse.pl https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
chmod +x ttyverse.pl

Usage Questions

How do I see older posts?

Use /again to load more posts from your timeline, or /last 20 to see the last 20 cached posts.

Can I use TTYverse over SSH?

Yes! TTYverse works perfectly over SSH connections.

How do I open links from posts?

Use /url <post_code> (e.g., /url a3). TTYverse will automatically detect your environment and use appropriate browsers.

Why does TTYverse require alt-text for images?

TTYverse enforces accessibility standards. The maintainer is blind, and the philosophy is: "If you're going to use a client maintained by a blind guy, you can damn well describe your images!"

Can I post without media upload?

Yes, just type something and press enter and it will be posted. If you have problems with fat fingering or typing things in the wrong window, use /set verify 1 or -verify. This can be added to the rc file to be default if desired.

Technical Questions

Where does TTYverse store its configuration?

TTYverse follows XDG Base Directory specification:

Config: ~/.config/ttyverse/
Data: ~/.local/share/ttyverse/
Cache: ~/.cache/ttyverse/

How does the multi-process architecture work?

TTYverse runs two processes:

Foreground process - User interface and commands
Background process - Timeline monitoring and data management

They communicate via IPC (pipes and signals).

Can I run multiple instances?

Yes, use different keyfiles:

./ttyverse.pl -keyfile work_account
./ttyverse.pl -keyfile personal_account

How do I backup my configuration?

tar -czf ttyverse-backup.tar.gz ~/.config/ttyverse/

Features and Functionality

What timeline types are supported?

Home timeline - Posts from accounts you follow
Local timeline - Posts from your instance
Federated timeline - Posts from the broader fediverse
Bookmarks - Posts you've bookmarked

Does TTYverse support direct messages?

Yes, use /dms to view direct messages and /reply da1 message to reply.

Can I boost and favorite posts?

Yes:

/boost a3 - Boost post a3
/fav a3 - Favorite post a3
/bookmark a3 - Bookmark post a3

What about search functionality?

Use /search for:

/search #hashtag - Search hashtags
/search @username - Find users
/search "text" - Search post content

Accessibility Features

What accessibility features does TTYverse have?

Screen reader friendly - All output is text-based
Sound notifications - Audio feedback for events (requires sound.pl extension)
Alt-text enforcement - Images must have descriptions
Keyboard navigation - No mouse required
Terminal compatibility - Works with any terminal

Can I disable sound notifications?

Yes, edit ~/.config/ttyverse/ttyverse_rc and set sound_enabled=0

Does TTYverse work with screen readers?

Yes, TTYverse is designed specifically for screen reader users. All output is plain text and follows screen reader conventions.

Customization

Can I change the sound notifications?

Yes, replace sound files in ~/.local/share/ttyverse/sounds/default/ or create custom sound packs.

How do I change the browser TTYverse uses?

/set gui_browser firefox
/set cli_browser w3m

Can I adjust the timeline refresh rate?

/set effpause 300    # Refresh every 5 minutes

Are there extensions available?

Yes, TTYverse includes several extensions:

soundpack.pl - Sound notifications
tts.pl - Text-to-speech
libnotify.pl - Desktop notifications
More to come - Check the extensions directory or the repository: https://git.stormux.org/storm/ttyverse-extensions

Troubleshooting

TTYverse won't start, what should I check?

Perl is installed: perl --version
curl is available: curl --version
Script is executable: chmod +x ttyverse.pl
Config directory exists: mkdir -p ~/.config/ttyverse/

I'm getting "connection failed" errors

Check internet connection: ping 8.8.8.8
Verify server URL in config
Test server manually: curl https://your-instance.com/api/v1/instance
Check firewall/proxy settings

OAuth setup isn't working

Try manual OAuth - copy URL to browser manually
Check browser configuration
Verify server supports OAuth 2.0
Clear old credentials and start fresh

Media uploads aren't working

Check file size limits (8MB for images, 40MB for video on Mastodon)
Verify file format is supported
Test with smaller files
Check server error messages

Development and Contributing

Can I contribute to TTYverse?

Yes! Contributions are welcome:

Report bugs by mentioning @stormux@social.stormux.org
Submit patches via git-email
Improve documentation
Create extensions

How is TTYverse developed?

TTYverse is written in Perl as a single script. It's forked from TTYtter but completely rewritten for the fediverse.

Can I create extensions?

Yes, extensions are Perl scripts in ~/.local/share/ttyverse/extensions/. See existing extensions for examples.

Privacy and Security

What data does TTYverse store locally?

OAuth tokens - For server authentication
Timeline cache - Recent posts for faster display
DM seen status - To track read direct messages
Configuration - Your settings and preferences

How secure is TTYverse?

Uses OAuth 2.0 for authentication
Stores tokens locally with restricted permissions
No data sent to third parties
All communication is HTTPS

Can I run TTYverse without saving credentials?

OAuth tokens must be saved for TTYverse to function. Tokens are stored with restricted file permissions (600).

Getting Help

Where can I get support?

Built-in help: /help command in TTYverse
Documentation: This wiki
Issues: https://git.stormux.org/storm/ttyverse/issues
Community: Fediverse community support

How do I report bugs?

Report bugs by DM or mention @stormux@social.stormux.org with:

TTYverse version
System information
Steps to reproduce
Error messages
Debug output (if applicable)