2

Getting Started

Storm Dragon edited this page 2025-07-30 15:30:36 -04:00

Table of Contents

• Getting Started with TTYverse
• Prerequisites
• Installation
• Quick Install
• First-Time Setup
• 1. Initial Launch
• 2. Server Configuration
• 3. OAuth Authorization
• 4. First Login
• Essential Commands
• Viewing Content
• Creating Content
• Interacting
• Navigation
• Understanding Post Codes
• Understanding Visibility Indicators
• Media Uploads
• Sound Notifications
• Configuration Files
• Next Steps
• Common Issues
• Connection Problems
• Sound Issues
• Permission Issues
• Getting Help

Getting Started with TTYverse

TTYverse is a command-line fediverse client that lets you interact with Mastodon, GoToSocial, and other ActivityPub servers from your terminal. This guide will get you up and running quickly.

Prerequisites

• Perl 5.x - TTYverse is written in Perl
• curl - For API communication
• Terminal emulator - Any Unix/Linux terminal
• Fediverse account - On Mastodon, GoToSocial, or compatible server

Installation

Quick Install

# Download the latest release
wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl

# Make executable
chmod +x ttyverse.pl

# Run TTYverse
./ttyverse.pl

For detailed installation options, see the Installation guide.

First-Time Setup

1. Initial Launch

When you first run TTYverse, it will guide you through OAuth setup:

./ttyverse.pl

2. Server Configuration

TTYverse will ask for your fediverse server. Enter your instance URL:

Enter your fediverse instance (e.g., mastodon.social): your-instance.com

3. OAuth Authorization

TTYverse will:

1. Open your browser to authorize the application
2. Generate an access token
3. Save credentials to ~/.config/ttyverse/

4. First Login

After setup, you'll see the TTYverse prompt:

TTYverse (c)2025 Storm Dragon
fediverse client for Mastodon/GoToSocial/etc

when ready, hit RETURN/ENTER for a prompt.
type /help for commands or /quit to quit.

TTYverse> 

Essential Commands

Viewing Content

# Show your home timeline
/timeline

# Show local timeline
/timeline local

# Show federated timeline  
/timeline federated

# Show bookmarks
/timeline bookmarks

# Show direct messages
/dms

Creating Content

# Post a message
/post Hello fediverse!

# Reply to a post (using menu code)
/reply a3 Thanks for the interesting post!

# Post with media
/media /path/to/image.jpg

Interacting

# Boost a post
/boost a3

# Favorite a post  
/fav a3

# Vote in a poll
/vote a3 2

# Search
/search #hashtag
/search @username
/search "search terms"

Navigation

# Show more posts
/again

# Refresh timeline
/refresh

# Get help
/help

# Quit
/quit

Understanding Post Codes

TTYverse assigns menu codes to posts for easy reference:

a0> {,POST_ID} <username> (2h ago) via TTYverse [Public]
    This is a post with menu code 'a0'

a1> {,POST_ID} <username> (1h ago) via Web [Unlisted]  
    This post has menu code 'a1'

Use these codes with commands:

• /reply a0 Great post!
• /boost a1
• /fav a0

Understanding Visibility Indicators

Posts show visibility levels:

• [Public] - Visible to everyone, appears in public timelines
• [Unlisted] - Public but doesn't appear in local/federated timelines
• [Followers] - Only visible to your followers
• [Direct] - Direct message, only visible to mentioned users

Media Uploads

TTYverse enforces accessibility for images:

# Upload an image (will prompt for alt-text)
/media /path/to/photo.jpg

# Upload audio/video (no alt-text required)
/media /path/to/audio.mp3

Note: Images require alt-text descriptions. TTYverse will cancel uploads without descriptions to enforce accessibility.

Sound Notifications

TTYverse includes sound notifications for different events:

• New posts
• Mentions
• Direct messages
• Boosts and favorites

Sounds are stored in ~/.local/share/ttyverse/sounds/

Configuration Files

TTYverse stores configuration in XDG-compliant locations:

• Config: ~/.config/ttyverse/
• Extensions: ~/.local/share/ttyverse/extensions/
• Sounds: ~/.local/share/ttyverse/sounds/

Next Steps

Once you're comfortable with basic usage:

1. Configuration - Customize TTYverse settings
2. Advanced Features - Power user features
3. Extensions - Add sound packs and TTS
4. Commands Reference - Complete command documentation

Common Issues

Connection Problems

# Test your connection
/refresh

# Check your OAuth setup
cat ~/.config/ttyverse/ttyverse_rc

Sound Issues

# Check if sound files exist
ls ~/.local/share/ttyverse/sounds/default/

# Test audio playback
paplay ~/.local/share/ttyverse/sounds/default/default.ogg

Permission Issues

# Ensure config directory is writable
ls -la ~/.config/ttyverse/

# Check file permissions
chmod 600 ~/.config/ttyverse/*

Getting Help

• In TTYverse: Type /help for command list
• Troubleshooting: See Troubleshooting guide
• FAQ: Check FAQ for common questions
• Issues: Report bugs at https://git.stormux.org/storm/ttyverse/issues

---

Next: Basic Usage | Commands Reference