Presto, a wiki! Thanks Claud. Most information should be accurate, let me know if something is off.
Storm Dragon
369
Basic-Usage.md
Normal file
369
Basic-Usage.md
Normal file
@ -0,0 +1,369 @@
|
||||
# Basic Usage
|
||||
|
||||
Essential workflows and everyday usage patterns for TTYverse. This guide assumes you've completed [Getting Started](Getting-Started) and have TTYverse configured.
|
||||
|
||||
## Daily Workflow
|
||||
|
||||
### Starting TTYverse
|
||||
```bash
|
||||
# Start TTYverse
|
||||
./ttyverse.pl
|
||||
|
||||
# TTYverse loads and shows:
|
||||
# - Current version and login status
|
||||
# - Recent timeline posts
|
||||
# - Direct messages (if any)
|
||||
# - Ready prompt: TTYverse>
|
||||
```
|
||||
|
||||
### Reading Your Timeline
|
||||
When TTYverse starts, it automatically loads your home timeline:
|
||||
|
||||
```
|
||||
a0> {,POST_ID} <username> (2h ago) via Web [Public]
|
||||
Content of the post goes here with any links or hashtags
|
||||
|
||||
a1> {,POST_ID} <username> (1h ago) via TTYverse [Unlisted]
|
||||
Another post with different visibility
|
||||
```
|
||||
|
||||
**Understanding the format:**
|
||||
- **a0**, **a1** - Menu codes for referencing posts
|
||||
- **username** - Who posted it
|
||||
- **(2h ago)** - How long ago it was posted
|
||||
- **via Web** - What client was used
|
||||
- **[Public]** - Visibility level
|
||||
|
||||
### Loading More Content
|
||||
```bash
|
||||
# See more posts from timeline
|
||||
/again
|
||||
|
||||
# Refresh timeline for new posts
|
||||
/refresh
|
||||
|
||||
# See posts from cache
|
||||
/last 15
|
||||
```
|
||||
|
||||
## Reading Different Timelines
|
||||
|
||||
### Home Timeline (Default)
|
||||
Your personalized feed from accounts you follow:
|
||||
```bash
|
||||
/timeline # Show home timeline
|
||||
```
|
||||
|
||||
### Local Timeline
|
||||
Posts from your instance/server:
|
||||
```bash
|
||||
/timeline local # See what your community is posting
|
||||
```
|
||||
|
||||
### Federated Timeline
|
||||
Posts from across the fediverse:
|
||||
```bash
|
||||
/timeline federated # See the broader conversation
|
||||
```
|
||||
|
||||
### Bookmarks
|
||||
Posts you've saved:
|
||||
```bash
|
||||
/timeline bookmarks # Your saved posts
|
||||
```
|
||||
|
||||
## Interacting with Posts
|
||||
|
||||
### Basic Interactions
|
||||
```bash
|
||||
# Like a post
|
||||
/fav a3
|
||||
|
||||
# Share a post (boost/reblog)
|
||||
/boost a3
|
||||
|
||||
# Save for later
|
||||
/bookmark a3
|
||||
|
||||
# Reply to a post
|
||||
/reply a3 Great point about accessibility!
|
||||
```
|
||||
|
||||
### Opening Links
|
||||
When posts contain URLs:
|
||||
```bash
|
||||
# Open the URL from post a3
|
||||
/url a3
|
||||
|
||||
# TTYverse automatically detects your environment:
|
||||
# - GUI environment: Opens in Firefox, Chrome, etc.
|
||||
# - Terminal: Opens in w3m, elinks, or lynx
|
||||
```
|
||||
|
||||
### Getting User Information
|
||||
```bash
|
||||
# Learn about a user
|
||||
/whois storm@stormux.org
|
||||
|
||||
# Shows profile information, follower count, etc.
|
||||
```
|
||||
|
||||
## Creating Content
|
||||
|
||||
### Simple Text Posts
|
||||
```bash
|
||||
# Create a public post
|
||||
/post Just learned about TTYverse - loving the accessibility focus!
|
||||
|
||||
# TTYverse creates the post and shows confirmation
|
||||
```
|
||||
|
||||
### Posts with Media
|
||||
```bash
|
||||
# Upload an image
|
||||
/media ~/pictures/sunset.jpg
|
||||
|
||||
# TTYverse will prompt for:
|
||||
# 1. Alt-text description (required for images)
|
||||
# 2. Optional post message
|
||||
```
|
||||
|
||||
**Alt-text example:**
|
||||
```
|
||||
Enter alt text for sunset.jpg: Orange and purple clouds over mountains during golden hour
|
||||
Enter post message (optional): Beautiful evening hike in the local mountains
|
||||
```
|
||||
|
||||
### Replying to Conversations
|
||||
```bash
|
||||
# Reply to someone's post
|
||||
/reply a5 That's exactly what I was thinking! Have you tried the new media upload feature?
|
||||
|
||||
# Your reply appears in the conversation thread
|
||||
```
|
||||
|
||||
## Managing Conversations
|
||||
|
||||
### Direct Messages
|
||||
```bash
|
||||
# Check for direct messages
|
||||
/dms
|
||||
|
||||
# Shows recent DMs:
|
||||
[DM da0][friend@instance.org] (1h ago)
|
||||
Hey, saw your post about TTYverse - is it really that accessible?
|
||||
|
||||
# Reply to a DM
|
||||
/reply da0 Yes! It's designed by a blind developer with accessibility as the top priority.
|
||||
```
|
||||
|
||||
### Following Conversations
|
||||
```bash
|
||||
# Follow an interesting user
|
||||
/follow @username@instance.com
|
||||
|
||||
# Their posts will appear in your home timeline
|
||||
```
|
||||
|
||||
## Searching and Discovery
|
||||
|
||||
### Finding Content
|
||||
```bash
|
||||
# Search for hashtags
|
||||
/search #accessibility
|
||||
|
||||
# Find users
|
||||
/search storm@stormux.org
|
||||
|
||||
# Search post content
|
||||
/search "command line fediverse"
|
||||
```
|
||||
|
||||
### Exploring Communities
|
||||
```bash
|
||||
# See what your local instance is discussing
|
||||
/timeline local
|
||||
|
||||
# Discover broader conversations
|
||||
/timeline federated
|
||||
|
||||
# Find trending topics (if your server supports it)
|
||||
/search #trending
|
||||
```
|
||||
|
||||
## Voting in Polls
|
||||
|
||||
When you see a poll in your timeline, it appears with numbered options:
|
||||
|
||||
```
|
||||
b3> {,POST_ID} <username> (30m ago) via Web [Public]
|
||||
What's your favorite terminal editor?
|
||||
|
||||
Poll (ends in 2 days, 15 votes):
|
||||
1. vim (8 votes - 53%)
|
||||
2. emacs (4 votes - 27%)
|
||||
3. nano (3 votes - 20%)
|
||||
```
|
||||
|
||||
Vote using the menu code and option number:
|
||||
```bash
|
||||
# Vote for option 1 (vim)
|
||||
/vote b3 1
|
||||
|
||||
# For multiple choice polls, vote for multiple options
|
||||
/vote b3 1,3
|
||||
```
|
||||
|
||||
## Managing Your Experience
|
||||
|
||||
### Adjusting Settings
|
||||
```bash
|
||||
# Change how often timeline refreshes (in seconds)
|
||||
/set effpause 300 # Refresh every 5 minutes
|
||||
|
||||
# Set your preferred browsers
|
||||
/set gui_browser firefox
|
||||
/set cli_browser w3m
|
||||
|
||||
# Check current settings
|
||||
/get effpause
|
||||
```
|
||||
|
||||
### Getting Information
|
||||
```bash
|
||||
# See available commands
|
||||
/help
|
||||
|
||||
# Check API rate limits
|
||||
/rate
|
||||
|
||||
# See TTYverse version
|
||||
/version
|
||||
```
|
||||
|
||||
### Controlling Output
|
||||
```bash
|
||||
# Enable detailed output
|
||||
/verbose
|
||||
|
||||
# Enable debug information (for troubleshooting)
|
||||
/debug
|
||||
```
|
||||
|
||||
## Sound Notifications
|
||||
|
||||
TTYverse includes audio feedback for different events:
|
||||
|
||||
- **New posts** - Gentle notification sound
|
||||
- **Mentions** - Distinctive alert when someone mentions you
|
||||
- **Direct messages** - Special sound for private messages
|
||||
- **Your posts** - Confirmation when your posts appear
|
||||
- **Boosts/favorites** - Feedback when others interact with your posts
|
||||
|
||||
Sound files are stored in `~/.local/share/ttyverse/sounds/default/`
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Morning Routine
|
||||
```bash
|
||||
# Start TTYverse and catch up
|
||||
./ttyverse.pl # Shows recent timeline
|
||||
/dms # Check direct messages
|
||||
/timeline local # See community activity
|
||||
```
|
||||
|
||||
### Active Participation
|
||||
```bash
|
||||
# Engage with interesting content
|
||||
/fav a3 # Like interesting posts
|
||||
/boost a5 # Share good content
|
||||
/reply a7 Great insight! # Join conversations
|
||||
/post Today I learned... # Share your thoughts
|
||||
```
|
||||
|
||||
### Content Creation
|
||||
```bash
|
||||
# Share a photo with proper accessibility
|
||||
/media ~/photo.jpg
|
||||
# Alt-text: "Golden retriever playing in autumn leaves"
|
||||
# Message: "Morning walk with the dog - beautiful fall colors!"
|
||||
```
|
||||
|
||||
### Research and Discovery
|
||||
```bash
|
||||
# Explore topics
|
||||
/search #photography # Find photography discussions
|
||||
/timeline federated # See broader conversations
|
||||
/search @expert # Find knowledgeable users
|
||||
/follow @expert@domain # Follow interesting people
|
||||
```
|
||||
|
||||
### End of Session
|
||||
```bash
|
||||
# Save interesting posts for later
|
||||
/bookmark a3
|
||||
/bookmark b7
|
||||
|
||||
# Exit cleanly
|
||||
/quit
|
||||
```
|
||||
|
||||
## Tips for Effective Usage
|
||||
|
||||
### Navigation Tips
|
||||
1. **Use menu codes efficiently** - They're faster than scrolling
|
||||
2. **Bookmark interesting posts** - Save them for later reference
|
||||
3. **Follow local timeline** - Discover your community
|
||||
4. **Use search regularly** - Find conversations on topics you care about
|
||||
|
||||
### Engagement Tips
|
||||
1. **Always provide alt-text** - TTYverse enforces this for good reason
|
||||
2. **Reply thoughtfully** - Add value to conversations
|
||||
3. **Use appropriate visibility** - Consider who should see your posts
|
||||
4. **Boost good content** - Help spread valuable information
|
||||
|
||||
### Accessibility Tips
|
||||
1. **TTYverse is screen reader friendly** - All output is plain text
|
||||
2. **Sound notifications help** - Audio cues for different events
|
||||
3. **Consistent structure** - Posts always follow the same format
|
||||
4. **Keyboard-only navigation** - No mouse required anywhere
|
||||
|
||||
### Performance Tips
|
||||
1. **Adjust refresh rate** - Slower connections benefit from longer intervals
|
||||
2. **Use /last command** - Access cached posts without network requests
|
||||
3. **Bookmark instead of searching** - Faster access to interesting content
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
### Timeline Issues
|
||||
```bash
|
||||
# Timeline won't load
|
||||
/refresh # Force refresh
|
||||
# Check network: ping 8.8.8.8
|
||||
|
||||
# Old posts showing
|
||||
/timeline # Reload home timeline
|
||||
```
|
||||
|
||||
### Interaction Problems
|
||||
```bash
|
||||
# Menu codes not working
|
||||
# Make sure you're using current codes (they change as new posts load)
|
||||
|
||||
# Can't reply or boost
|
||||
# Check if post is still available: /url a3
|
||||
```
|
||||
|
||||
### Media Upload Issues
|
||||
```bash
|
||||
# Image upload fails
|
||||
# Ensure file exists: ls -la ~/path/to/image.jpg
|
||||
# Check file size (8MB limit for images on most servers)
|
||||
# Provide meaningful alt-text (required!)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also:** [Getting Started](Getting-Started) | [Commands Reference](Commands-Reference) | [Media Uploads](Media-Uploads)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
287
Commands-Reference.md
Normal file
287
Commands-Reference.md
Normal file
@ -0,0 +1,287 @@
|
||||
# Commands Reference
|
||||
|
||||
Complete reference for all TTYverse commands. Commands are entered at the `TTYverse>` prompt and always start with `/`.
|
||||
|
||||
## Timeline & Navigation Commands
|
||||
|
||||
### `/timeline [type]`
|
||||
Display timeline content.
|
||||
|
||||
**Usage:**
|
||||
- `/timeline` - Show home timeline (default)
|
||||
- `/timeline local` - Show local instance timeline
|
||||
- `/timeline federated` - Show federated timeline
|
||||
- `/timeline bookmarks` - Show bookmarked posts
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
/timeline # Home timeline
|
||||
/timeline local # Local posts
|
||||
/timeline federated # All federated posts
|
||||
/timeline bookmarks # Your bookmarks
|
||||
```
|
||||
|
||||
### `/again`
|
||||
Show more posts from the current timeline.
|
||||
|
||||
### `/refresh`
|
||||
Refresh the current timeline and fetch new posts.
|
||||
|
||||
### `/last [number]`
|
||||
Show the last N posts from cache.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
/last 10 # Show last 10 posts
|
||||
```
|
||||
|
||||
## Posting Commands
|
||||
|
||||
### `/post <message>`
|
||||
Create a new public post.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/post Hello fediverse!
|
||||
/post This is a longer post with multiple words
|
||||
```
|
||||
|
||||
**Note:** Posts default to public visibility.
|
||||
|
||||
### `/reply <code> <message>`
|
||||
Reply to a specific post using its menu code.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/reply a3 Thanks for sharing!
|
||||
/reply b1 Great point about accessibility
|
||||
```
|
||||
|
||||
### `/media <filepath> [message]`
|
||||
Upload media (image, audio, video) with optional post text.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/media /path/to/image.jpg # Upload image only
|
||||
/media /path/to/audio.mp3 Great song! # Upload with message
|
||||
```
|
||||
|
||||
**Accessibility:** Images require alt-text descriptions. TTYverse will prompt for alt-text and cancel uploads without descriptions.
|
||||
|
||||
**Supported formats:**
|
||||
- **Images:** JPEG, PNG, GIF, WebP
|
||||
- **Audio:** MP3, OGG, WAV, FLAC, M4A
|
||||
- **Video:** MP4, WebM, MOV
|
||||
|
||||
## Interaction Commands
|
||||
|
||||
### `/boost <code>`
|
||||
Boost (reblog) a post.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/boost a3 # Boost post a3
|
||||
/boost b7 # Boost post b7
|
||||
```
|
||||
|
||||
### `/unboost <code>`
|
||||
Remove boost from a post.
|
||||
|
||||
### `/fav <code>` / `/favorite <code>`
|
||||
Favorite (like) a post.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/fav a3 # Favorite post a3
|
||||
/favorite b1 # Same as /fav
|
||||
```
|
||||
|
||||
### `/unfav <code>`
|
||||
Remove favorite from a post.
|
||||
|
||||
### `/bookmark <code>`
|
||||
Bookmark a post for later.
|
||||
|
||||
### `/unbookmark <code>`
|
||||
Remove bookmark from a post.
|
||||
|
||||
### `/vote <code> <choices>`
|
||||
Vote in a poll.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/vote a3 1 # Vote for option 1
|
||||
/vote b2 2,3 # Vote for options 2 and 3 (multiple choice)
|
||||
/vote c1 1-3 # Vote for options 1 through 3
|
||||
```
|
||||
|
||||
## Direct Messages
|
||||
|
||||
### `/dms`
|
||||
Show recent direct messages.
|
||||
|
||||
### `/reply <dm_code> <message>`
|
||||
Reply to a direct message.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/reply da1 Thanks for the message!
|
||||
```
|
||||
|
||||
## Search Commands
|
||||
|
||||
### `/search <query>`
|
||||
Search for posts, hashtags, or accounts.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/search #accessibility # Search hashtag
|
||||
/search @username@instance.com # Search user
|
||||
/search "climate change" # Search text
|
||||
/search technology # Search term
|
||||
```
|
||||
|
||||
### `/whois <username>`
|
||||
Get information about a user.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/whois storm@stormux.org
|
||||
/whois @localuser
|
||||
```
|
||||
|
||||
## Account & Profile Commands
|
||||
|
||||
### `/follow <username>`
|
||||
Follow a user.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/follow storm@stormux.org
|
||||
/follow @localuser
|
||||
```
|
||||
|
||||
### `/unfollow <username>`
|
||||
Unfollow a user.
|
||||
|
||||
### `/block <username>`
|
||||
Block a user.
|
||||
|
||||
### `/unblock <username>`
|
||||
Unblock a user.
|
||||
|
||||
### `/mute <username>`
|
||||
Mute a user.
|
||||
|
||||
### `/unmute <username>`
|
||||
Unmute a user.
|
||||
|
||||
## URL & Link Commands
|
||||
|
||||
### `/url <code>`
|
||||
Open URL from a post in your browser.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
/url a3 # Open URL from post a3
|
||||
```
|
||||
|
||||
TTYverse automatically detects your environment and uses:
|
||||
- **GUI browsers:** Firefox, Chrome, etc. (if DISPLAY is set)
|
||||
- **CLI browsers:** w3m, elinks, lynx (in terminal)
|
||||
|
||||
**Configuration:**
|
||||
- Set `gui_browser` in config for GUI preference
|
||||
- Set `cli_browser` in config for CLI preference
|
||||
|
||||
## Information Commands
|
||||
|
||||
### `/help`
|
||||
Show available commands.
|
||||
|
||||
### `/version`
|
||||
Show TTYverse version information.
|
||||
|
||||
### `/about`
|
||||
Show information about TTYverse.
|
||||
|
||||
### `/rate`
|
||||
Show current API rate limit status.
|
||||
|
||||
## Configuration Commands
|
||||
|
||||
### `/set <option> <value>`
|
||||
Change configuration options.
|
||||
|
||||
**Common options:**
|
||||
```bash
|
||||
/set effpause 60 # Set refresh interval (seconds)
|
||||
/set gui_browser firefox # Set GUI browser
|
||||
/set cli_browser w3m # Set CLI browser
|
||||
```
|
||||
|
||||
### `/get <option>`
|
||||
Show current value of configuration option.
|
||||
|
||||
## System Commands
|
||||
|
||||
### `/quit` / `/exit`
|
||||
Exit TTYverse.
|
||||
|
||||
### `/restart`
|
||||
Restart TTYverse (reload configuration).
|
||||
|
||||
## Debug Commands
|
||||
|
||||
### `/verbose`
|
||||
Toggle verbose output for debugging.
|
||||
|
||||
### `/debug`
|
||||
Toggle debug output for troubleshooting.
|
||||
|
||||
## Menu Codes
|
||||
|
||||
TTYverse assigns menu codes to posts for easy reference:
|
||||
|
||||
- **Posts:** `a0`, `a1`, `a2`, ... `a9`, `b0`, `b1`, etc.
|
||||
- **DMs:** `da0`, `da1`, `da2`, etc.
|
||||
|
||||
Codes are assigned in chronological order, with newer posts getting later codes.
|
||||
|
||||
## Visibility Levels
|
||||
|
||||
When posting, content visibility is shown:
|
||||
- **[Public]** - Visible to everyone, appears in timelines
|
||||
- **[Unlisted]** - Public but not in local/federated timelines
|
||||
- **[Followers]** - Only followers can see
|
||||
- **[Direct]** - Only mentioned users can see
|
||||
|
||||
## Command Aliases
|
||||
|
||||
Some commands have shorter aliases:
|
||||
- `/fav` = `/favorite`
|
||||
- `/boost` = `/rt` = `/reblog`
|
||||
- `/dms` = `/dm`
|
||||
- `/quit` = `/exit` = `/q`
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Tab completion:** Most commands support tab completion
|
||||
2. **Command history:** Use up/down arrows for command history
|
||||
3. **Multiple words:** Wrap multi-word arguments in quotes if needed
|
||||
4. **Case sensitivity:** Commands are case-insensitive
|
||||
5. **Menu codes:** Always use current menu codes (they change as new posts load)
|
||||
|
||||
## Error Handling
|
||||
|
||||
Common error messages:
|
||||
- "Invalid menu code" - Post code doesn't exist or is old
|
||||
- "Rate limit exceeded" - API calls too frequent, wait a moment
|
||||
- "Not found" - User or post doesn't exist
|
||||
- "Unauthorized" - Authentication problem, check OAuth setup
|
||||
|
||||
---
|
||||
|
||||
**See also:** [Getting Started](Getting-Started) | [Basic Usage](Basic-Usage) | [Advanced Features](Advanced-Features)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
322
Configuration.md
Normal file
322
Configuration.md
Normal file
@ -0,0 +1,322 @@
|
||||
# Configuration
|
||||
|
||||
TTYverse stores configuration in XDG-compliant directories and supports extensive customization through configuration files and runtime settings.
|
||||
|
||||
## Configuration Locations
|
||||
|
||||
### XDG Base Directory Support
|
||||
TTYverse follows the XDG Base Directory Specification:
|
||||
|
||||
- **Config files:** `$XDG_CONFIG_HOME/ttyverse/` or `~/.config/ttyverse/`
|
||||
- **Data files:** `$XDG_DATA_HOME/ttyverse/` or `~/.local/share/ttyverse/`
|
||||
- **Cache files:** `$XDG_CACHE_HOME/ttyverse/` or `~/.cache/ttyverse/`
|
||||
|
||||
### Key Files
|
||||
```
|
||||
~/.config/ttyverse/
|
||||
├── ttyverse_rc # Main configuration file
|
||||
├── oauth_credentials # OAuth tokens (keep secure!)
|
||||
└── dm_seen_status # Direct message tracking
|
||||
|
||||
~/.local/share/ttyverse/
|
||||
├── extensions/ # Extension scripts
|
||||
│ ├── soundpack.pl # Sound notifications
|
||||
│ ├── tts.pl # Text-to-speech
|
||||
│ └── libnotify.pl # Desktop notifications
|
||||
└── sounds/ # Sound notification files
|
||||
└── default/ # Default sound pack
|
||||
├── default.ogg
|
||||
├── mention.ogg
|
||||
├── dm.ogg
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Main Configuration File
|
||||
|
||||
### ttyverse_rc Format
|
||||
The main config file (`~/.config/ttyverse/ttyverse_rc`) uses a simple key=value format:
|
||||
|
||||
```perl
|
||||
# TTYverse Configuration File
|
||||
# Generated by TTYverse setup
|
||||
|
||||
# Server and authentication
|
||||
apibase=https://your-instance.com/api/v1
|
||||
tokenkey=your_oauth_token_here
|
||||
|
||||
# Display and behavior settings
|
||||
effpause=120
|
||||
verbose=1
|
||||
readline=1
|
||||
|
||||
# Browser settings
|
||||
gui_browser=firefox
|
||||
cli_browser=w3m
|
||||
|
||||
# Extension settings
|
||||
extension_notify=default,mention,dm
|
||||
```
|
||||
|
||||
### Key Configuration Options
|
||||
|
||||
#### Core Settings
|
||||
- **`apibase`** - Your fediverse server's API base URL
|
||||
- **`tokenkey`** - OAuth authentication token (keep private!)
|
||||
- **`effpause`** - Timeline refresh interval in seconds (default: 120)
|
||||
- **`verbose`** - Enable verbose output (0/1)
|
||||
- **`readline`** - Enable advanced readline support (0/1)
|
||||
|
||||
#### Browser Configuration
|
||||
- **`gui_browser`** - Preferred GUI browser (firefox, chrome, etc.)
|
||||
- **`cli_browser`** - Preferred CLI browser (w3m, elinks, lynx)
|
||||
|
||||
#### Timeline Settings
|
||||
- **`timeline_count`** - Number of posts to fetch (default: 30)
|
||||
- **`timeline_cache`** - Maximum cached posts (default: 200)
|
||||
|
||||
#### Notification Settings
|
||||
- **`extension_notify`** - Comma-separated list of notification types
|
||||
- **`sound_enabled`** - Enable sound notifications (0/1)
|
||||
|
||||
## Browser Configuration
|
||||
|
||||
TTYverse automatically detects your environment and chooses appropriate browsers:
|
||||
|
||||
### GUI Environment (DISPLAY set)
|
||||
1. Uses `gui_browser` setting if configured
|
||||
2. Falls back to `xdg-open`
|
||||
3. Tries common browsers: firefox, chrome, chromium
|
||||
|
||||
### CLI Environment (no DISPLAY)
|
||||
1. Uses `cli_browser` setting if configured
|
||||
2. Tries CLI browsers: w3m, elinks, lynx
|
||||
|
||||
### Manual Configuration
|
||||
```bash
|
||||
# Set browsers in TTYverse
|
||||
/set gui_browser firefox
|
||||
/set cli_browser w3m
|
||||
|
||||
# Or edit config file directly
|
||||
echo "gui_browser=firefox" >> ~/.config/ttyverse/ttyverse_rc
|
||||
echo "cli_browser=w3m" >> ~/.config/ttyverse/ttyverse_rc
|
||||
```
|
||||
|
||||
## Sound Configuration
|
||||
|
||||
### Sound Pack Structure
|
||||
```
|
||||
~/.local/share/ttyverse/sounds/default/
|
||||
├── default.ogg # General notifications
|
||||
├── mention.ogg # When mentioned
|
||||
├── dm.ogg # Direct messages
|
||||
├── me.ogg # Your own posts
|
||||
├── search.ogg # Search results
|
||||
├── follow.ogg # New followers
|
||||
├── boost.ogg # When boosted
|
||||
├── favourite.ogg # When favorited
|
||||
├── poll.ogg # Poll notifications
|
||||
├── edit.ogg # Edited posts
|
||||
└── announcement.ogg # Server announcements
|
||||
```
|
||||
|
||||
### Sound Types
|
||||
TTYverse supports these notification types:
|
||||
- **default** - General notifications
|
||||
- **mention** - When someone mentions you
|
||||
- **dm** - Direct messages
|
||||
- **me** - Your own posts appearing in timeline
|
||||
- **search** - Search results
|
||||
- **follow** - New followers
|
||||
- **boost** - When someone boosts your post
|
||||
- **favourite** - When someone favorites your post
|
||||
- **poll** - Poll-related notifications
|
||||
- **edit** - When posts are edited
|
||||
- **announcement** - Server announcements
|
||||
|
||||
### Custom Sound Packs
|
||||
Create custom sound packs by:
|
||||
1. Creating directory: `~/.local/share/ttyverse/sounds/mysounds/`
|
||||
2. Adding OGG files for each notification type
|
||||
3. Activating: `/set sound_pack mysounds`
|
||||
|
||||
## Extension Configuration
|
||||
|
||||
### Available Extensions
|
||||
- **soundpack.pl** - Sound notifications
|
||||
- **tts.pl** - Text-to-speech support
|
||||
- **libnotify.pl** - Desktop notifications
|
||||
- **timestamp.pl** - Enhanced timestamp display
|
||||
|
||||
### Extension Management
|
||||
```bash
|
||||
# List loaded extensions
|
||||
ls ~/.local/share/ttyverse/extensions/
|
||||
|
||||
# Check loaded extensions in TTYverse
|
||||
/verbose
|
||||
# Shows: ** loaded extensions: soundpack, tts
|
||||
```
|
||||
|
||||
### Extension Settings
|
||||
Extensions can be configured through the main config file:
|
||||
```perl
|
||||
# Sound pack settings
|
||||
sound_enabled=1
|
||||
sound_pack=default
|
||||
|
||||
# TTS settings
|
||||
tts_enabled=1
|
||||
tts_voice=espeak
|
||||
|
||||
# Notification settings
|
||||
notify_desktop=1
|
||||
notify_sound=1
|
||||
```
|
||||
|
||||
## Runtime Configuration
|
||||
|
||||
### Setting Options During Session
|
||||
```bash
|
||||
# View current setting
|
||||
/get effpause
|
||||
|
||||
# Change setting
|
||||
/set effpause 60
|
||||
|
||||
# View all settings
|
||||
/verbose
|
||||
```
|
||||
|
||||
### Common Runtime Changes
|
||||
```bash
|
||||
# Adjust refresh rate
|
||||
/set effpause 300 # 5 minutes
|
||||
|
||||
# Change browser
|
||||
/set gui_browser chrome
|
||||
|
||||
# Toggle verbose output
|
||||
/verbose
|
||||
|
||||
# Toggle debug output
|
||||
/debug
|
||||
```
|
||||
|
||||
## OAuth Configuration
|
||||
|
||||
### OAuth Credential Files
|
||||
TTYverse stores OAuth credentials securely in:
|
||||
- **`oauth_credentials`** - Token and server information
|
||||
- **`ttyverse_rc`** - Main config with tokenkey
|
||||
|
||||
### Re-authenticating
|
||||
If OAuth fails:
|
||||
```bash
|
||||
# Remove old credentials
|
||||
rm ~/.config/ttyverse/oauth_credentials
|
||||
rm ~/.config/ttyverse/ttyverse_rc
|
||||
|
||||
# Restart TTYverse for fresh OAuth setup
|
||||
./ttyverse.pl
|
||||
```
|
||||
|
||||
### Multiple Accounts
|
||||
TTYverse supports multiple accounts through keyfiles:
|
||||
```bash
|
||||
# Use different keyfile for second account
|
||||
./ttyverse.pl -keyfile work_account
|
||||
|
||||
# This creates ~/.config/ttyverse/work_account_rc
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Memory Usage
|
||||
```perl
|
||||
# Reduce cached posts for lower memory usage
|
||||
timeline_cache=100
|
||||
|
||||
# Reduce fetch count for slower connections
|
||||
timeline_count=15
|
||||
```
|
||||
|
||||
### Network Settings
|
||||
```perl
|
||||
# Increase refresh interval for slower connections
|
||||
effpause=300
|
||||
|
||||
# Reduce concurrent connections
|
||||
max_connections=2
|
||||
```
|
||||
|
||||
### Accessibility Settings
|
||||
```perl
|
||||
# Force screen reader compatibility
|
||||
readline=1
|
||||
verbose=1
|
||||
|
||||
# Enable all accessibility features
|
||||
sound_enabled=1
|
||||
alt_text_required=1
|
||||
```
|
||||
|
||||
## Backup and Migration
|
||||
|
||||
### Backing Up Configuration
|
||||
```bash
|
||||
# Backup entire config directory
|
||||
tar -czf ttyverse-config-backup.tar.gz ~/.config/ttyverse/
|
||||
|
||||
# Backup just the main config
|
||||
cp ~/.config/ttyverse/ttyverse_rc ~/ttyverse_rc.backup
|
||||
```
|
||||
|
||||
### Migration Between Systems
|
||||
1. Copy config directory to new system
|
||||
2. Update file paths if needed
|
||||
3. Re-authenticate if moving between different systems
|
||||
4. Install required dependencies (curl, perl modules)
|
||||
|
||||
## Troubleshooting Configuration
|
||||
|
||||
### Common Issues
|
||||
```bash
|
||||
# Config file not found
|
||||
ls -la ~/.config/ttyverse/
|
||||
# Create directory if missing: mkdir -p ~/.config/ttyverse/
|
||||
|
||||
# Permission issues
|
||||
chmod 700 ~/.config/ttyverse/
|
||||
chmod 600 ~/.config/ttyverse/*
|
||||
|
||||
# OAuth token issues
|
||||
# Check if token exists and is not empty
|
||||
cat ~/.config/ttyverse/ttyverse_rc | grep tokenkey
|
||||
```
|
||||
|
||||
### Debug Configuration Loading
|
||||
```bash
|
||||
# Run with verbose output to see config loading
|
||||
./ttyverse.pl -verbose
|
||||
|
||||
# Check which config file is being used
|
||||
./ttyverse.pl -debug
|
||||
```
|
||||
|
||||
### Reset to Defaults
|
||||
```bash
|
||||
# Remove all configuration (will prompt for fresh setup)
|
||||
rm -rf ~/.config/ttyverse/
|
||||
rm -rf ~/.local/share/ttyverse/
|
||||
rm -rf ~/.cache/ttyverse/
|
||||
|
||||
# Restart TTYverse
|
||||
./ttyverse.pl
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also:** [Getting Started](Getting-Started) | [Extensions](Extensions) | [Troubleshooting](Troubleshooting)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
98
Extensions.md
Normal file
98
Extensions.md
Normal file
@ -0,0 +1,98 @@
|
||||
# Extensions
|
||||
|
||||
TTYverse supports extensions that add functionality like sound notifications, text-to-speech, and desktop integration. Extensions are Perl scripts that integrate with TTYverse's multi-process architecture.
|
||||
|
||||
## Available Extensions
|
||||
|
||||
TTYverse includes several extensions that enhance the user experience:
|
||||
|
||||
- **Sound Pack** - Audio notifications for different types of posts and events
|
||||
- **Text-to-Speech** - Speak posts and notifications aloud
|
||||
- **Desktop Notifications** - Visual notification bubbles
|
||||
- **Timestamp Enhancement** - Enhanced timestamp display options
|
||||
|
||||
Extensions are included with TTYverse but not enabled by default.
|
||||
|
||||
## Extension Installation
|
||||
|
||||
### Extension Availability
|
||||
TTYverse includes core extensions in the installation:
|
||||
|
||||
```bash
|
||||
** attempting to load extensions
|
||||
** loading /home/user/.local/share/ttyverse/extensions/extensionname.pl
|
||||
** loaded extensions: extensionname
|
||||
```
|
||||
|
||||
### Extension Location
|
||||
Extensions are stored in:
|
||||
```
|
||||
~/.local/share/ttyverse/extensions/
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Extensions are configured through TTYverse settings:
|
||||
|
||||
```bash
|
||||
# View extension-related settings
|
||||
/get sound_enabled
|
||||
/get tts_enabled
|
||||
|
||||
# Enable/disable extensions
|
||||
/set sound_enabled 1
|
||||
/set extension_name 0
|
||||
```
|
||||
|
||||
Configuration can also be edited directly in:
|
||||
```
|
||||
~/.config/ttyverse/ttyverse_rc
|
||||
```
|
||||
|
||||
## Extension Dependencies
|
||||
|
||||
Some extensions may require additional system packages. Check the documentation for your specific distribution to install:
|
||||
|
||||
- **Audio support** - PulseAudio or similar audio system
|
||||
- **Text-to-speech** - TTS engines like espeak or festival
|
||||
- **Desktop notifications** - libnotify and related Perl modules
|
||||
|
||||
## Custom Extensions
|
||||
|
||||
### Creating Extensions
|
||||
Extensions are Perl scripts that follow TTYverse conventions. They can:
|
||||
|
||||
- Hook into post processing
|
||||
- React to different notification types
|
||||
- Add new commands
|
||||
- Integrate with system features
|
||||
|
||||
### Extension Development
|
||||
See the existing extensions in `~/.local/share/ttyverse/extensions/` for examples of how to create custom functionality.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Extension Issues
|
||||
```bash
|
||||
# Check if extensions are loading
|
||||
./ttyverse.pl -verbose
|
||||
|
||||
# Test extension files manually
|
||||
perl ~/.local/share/ttyverse/extensions/extensionname.pl
|
||||
|
||||
# Fix permissions if needed
|
||||
chmod +x ~/.local/share/ttyverse/extensions/*.pl
|
||||
```
|
||||
|
||||
### Common Problems
|
||||
- **Permission denied** - Make extension files executable
|
||||
- **Missing dependencies** - Install required system packages
|
||||
- **Configuration errors** - Check settings in ttyverse_rc
|
||||
|
||||
For specific extension issues, check the [Troubleshooting](Troubleshooting) guide.
|
||||
|
||||
---
|
||||
|
||||
**See also:** [Configuration](Configuration) | [Troubleshooting](Troubleshooting) | [Installation](Installation)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
230
FAQ.md
Normal file
230
FAQ.md
Normal file
@ -0,0 +1,230 @@
|
||||
# Frequently Asked Questions (FAQ)
|
||||
|
||||
Common questions about TTYverse. For technical issues, see [Troubleshooting](Troubleshooting).
|
||||
|
||||
## General Questions
|
||||
|
||||
### What is TTYverse?
|
||||
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
|
||||
- **Sound notifications** - Audio feedback for different post types
|
||||
- **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:
|
||||
```bash
|
||||
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. Sound notifications won't work over SSH, but all other features do.
|
||||
|
||||
### 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, use `/post Your message here` for text-only posts.
|
||||
|
||||
## 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:
|
||||
```bash
|
||||
./ttyverse.pl -keyfile work_account
|
||||
./ttyverse.pl -keyfile personal_account
|
||||
```
|
||||
|
||||
### How do I backup my configuration?
|
||||
```bash
|
||||
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
|
||||
- **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?
|
||||
```bash
|
||||
/set gui_browser firefox
|
||||
/set cli_browser w3m
|
||||
```
|
||||
|
||||
### Can I adjust the timeline refresh rate?
|
||||
```bash
|
||||
/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
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### TTYverse won't start, what should I check?
|
||||
1. Perl is installed: `perl --version`
|
||||
2. curl is available: `curl --version`
|
||||
3. Script is executable: `chmod +x ttyverse.pl`
|
||||
4. Config directory exists: `mkdir -p ~/.config/ttyverse/`
|
||||
|
||||
### I'm getting "connection failed" errors
|
||||
1. Check internet connection: `ping 8.8.8.8`
|
||||
2. Verify server URL in config
|
||||
3. Test server manually: `curl https://your-instance.com/api/v1/instance`
|
||||
4. Check firewall/proxy settings
|
||||
|
||||
### OAuth setup isn't working
|
||||
1. Try manual OAuth - copy URL to browser manually
|
||||
2. Check browser configuration
|
||||
3. Verify server supports OAuth 2.0
|
||||
4. Clear old credentials and start fresh
|
||||
|
||||
### Media uploads aren't working
|
||||
1. Check file size limits (8MB for images, 40MB for video on Mastodon)
|
||||
2. Verify file format is supported
|
||||
3. Test with smaller files
|
||||
4. Check server error messages
|
||||
|
||||
## Development and Contributing
|
||||
|
||||
### Can I contribute to TTYverse?
|
||||
Yes! Contributions are welcome:
|
||||
- Report bugs at https://git.stormux.org/storm/ttyverse/issues
|
||||
- Submit patches via email or git
|
||||
- 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 at https://git.stormux.org/storm/ttyverse/issues with:
|
||||
- TTYverse version
|
||||
- System information
|
||||
- Steps to reproduce
|
||||
- Error messages
|
||||
- Debug output (if applicable)
|
||||
|
||||
---
|
||||
|
||||
**See also:** [Getting Started](Getting-Started) | [Troubleshooting](Troubleshooting) | [Commands Reference](Commands-Reference)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
232
Getting-Started.md
Normal file
232
Getting-Started.md
Normal file
@ -0,0 +1,232 @@
|
||||
# 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
|
||||
```bash
|
||||
# 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](Installation) guide.
|
||||
|
||||
## First-Time Setup
|
||||
|
||||
### 1. Initial Launch
|
||||
When you first run TTYverse, it will guide you through OAuth setup:
|
||||
|
||||
```bash
|
||||
./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 2025.07.28 (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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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](Configuration)** - Customize TTYverse settings
|
||||
2. **[Advanced Features](Advanced-Features)** - Power user features
|
||||
3. **[Extensions](Extensions)** - Add sound packs and TTS
|
||||
4. **[Commands Reference](Commands-Reference)** - Complete command documentation
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Connection Problems
|
||||
```bash
|
||||
# Test your connection
|
||||
/refresh
|
||||
|
||||
# Check your OAuth setup
|
||||
cat ~/.config/ttyverse/ttyverse_rc
|
||||
```
|
||||
|
||||
### Sound Issues
|
||||
```bash
|
||||
# Check if sound files exist
|
||||
ls ~/.local/share/ttyverse/sounds/default/
|
||||
|
||||
# Test audio playback
|
||||
paplay ~/.local/share/ttyverse/sounds/default/default.ogg
|
||||
```
|
||||
|
||||
### Permission Issues
|
||||
```bash
|
||||
# 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](Troubleshooting) guide
|
||||
- **FAQ:** Check [FAQ](FAQ) for common questions
|
||||
- **Issues:** Report bugs at https://git.stormux.org/storm/ttyverse/issues
|
||||
|
||||
---
|
||||
|
||||
**Next:** [Basic Usage](Basic-Usage) | [Commands Reference](Commands-Reference)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
103
Home.md
103
Home.md
@ -1 +1,102 @@
|
||||
This is the central repository of knowledge about using TTYverse.
|
||||
# TTYverse Wiki
|
||||
|
||||
**TTYverse** is a command-line fediverse client for Mastodon, GoToSocial, and other ActivityPub servers. Originally forked from TTYtter, it's been completely rebuilt for the fediverse era with accessibility and usability as core principles.
|
||||
|
||||
## Quick Start
|
||||
|
||||
**New to TTYverse?** → [Getting Started](Getting-Started) | [Installation](Installation)
|
||||
|
||||
**Need help with a command?** → [Commands Reference](Commands-Reference) | [Quick Command List](Quick-Commands)
|
||||
|
||||
**Having issues?** → [Troubleshooting](Troubleshooting) | [FAQ](FAQ)
|
||||
|
||||
## Navigation
|
||||
|
||||
### 📚 User Guides
|
||||
- **[Getting Started](Getting-Started)** - First-time setup and basic usage
|
||||
- **[Installation](Installation)** - Download, install, and initial configuration
|
||||
- **[Basic Usage](Basic-Usage)** - Essential commands and workflows
|
||||
- **[Advanced Features](Advanced-Features)** - Power user features and customization
|
||||
|
||||
### 📖 Reference Documentation
|
||||
- **[Commands Reference](Commands-Reference)** - Complete command documentation
|
||||
- **[Configuration](Configuration)** - Settings, options, and customization
|
||||
- **[Keyboard Shortcuts](Keyboard-Shortcuts)** - Terminal navigation and hotkeys
|
||||
- **[File Locations](File-Locations)** - Config files, logs, and data storage
|
||||
|
||||
### 🔧 Technical Documentation
|
||||
- **[Extensions](Extensions)** - Sound packs, TTS, and custom extensions
|
||||
- **[OAuth Setup](OAuth-Setup)** - Server authentication and key management
|
||||
- **[API Integration](API-Integration)** - Mastodon API usage and limitations
|
||||
- **[Architecture](Architecture)** - Multi-process design and IPC
|
||||
|
||||
### 🆘 Support & Troubleshooting
|
||||
- **[Troubleshooting](Troubleshooting)** - Common issues and solutions
|
||||
- **[FAQ](FAQ)** - Frequently asked questions
|
||||
- **[Error Messages](Error-Messages)** - What error messages mean and how to fix them
|
||||
- **[Performance](Performance)** - Optimizing TTYverse for your system
|
||||
|
||||
### 🎯 Feature Guides
|
||||
- **[Timeline Navigation](Timeline-Navigation)** - Reading posts, filtering, and browsing
|
||||
- **[Posting](Posting)** - Creating posts, replies, and using visibility settings
|
||||
- **[Media Uploads](Media-Uploads)** - Images, audio, video, and accessibility
|
||||
- **[Direct Messages](Direct-Messages)** - Private messaging and conversations
|
||||
- **[Polls](Polls)** - Creating and voting on polls
|
||||
- **[Search](Search)** - Finding posts, people, and hashtags
|
||||
|
||||
### 🌐 Fediverse Integration
|
||||
- **[Server Compatibility](Server-Compatibility)** - Mastodon, GoToSocial, Pleroma support
|
||||
- **[Instance Features](Instance-Features)** - Feature differences across servers
|
||||
- **[Cross-Instance](Cross-Instance)** - Following and interacting across servers
|
||||
|
||||
### 🔨 Development
|
||||
- **[Contributing](Contributing)** - How to contribute to TTYverse
|
||||
- **[Development Setup](Development-Setup)** - Setting up a development environment
|
||||
- **[Extension Development](Extension-Development)** - Creating custom extensions
|
||||
- **[Testing](Testing)** - Running tests and validation
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Essential Commands
|
||||
- `/help` - Show available commands
|
||||
- `/timeline` - Show timeline (home, local, federated, bookmarks)
|
||||
- `/post message` - Create a new post
|
||||
- `/reply a3 message` - Reply to post a3
|
||||
- `/boost a3` - Boost post a3
|
||||
- `/fav a3` - Favorite post a3
|
||||
- `/dms` - Show direct messages
|
||||
- `/media /path/file` - Upload media with post
|
||||
- `/search term` - Search posts and accounts
|
||||
- `/quit` - Exit TTYverse
|
||||
|
||||
### Key Features
|
||||
- **🎵 Sound Notifications** - Audio feedback for different post types
|
||||
- **♿ Accessibility First** - Alt-text enforcement and screen reader friendly
|
||||
- **🔐 OAuth 2.0** - Secure authentication with any fediverse server
|
||||
- **⚡ Real-time Updates** - Background monitoring and notifications
|
||||
- **🎨 Extensions** - Sound packs, TTS, notifications, and more
|
||||
- **📱 Multi-format** - Text, images, audio, video, and polls
|
||||
|
||||
## About TTYverse
|
||||
|
||||
**Current Version:** 2025.07.28
|
||||
**License:** Floodgap Free Software License
|
||||
**Original:** Forked from TTYtter by Cameron Kaiser
|
||||
**Maintainer:** Storm Dragon
|
||||
**Repository:** https://git.stormux.org/storm/ttyverse
|
||||
|
||||
### Philosophy
|
||||
> "If you're going to use a client maintained by a blind guy, you can damn well describe your images!"
|
||||
|
||||
TTYverse prioritizes accessibility, usability, and the principles of the open fediverse. Every feature is designed with screen reader users and keyboard navigation in mind, while remaining powerful for all users.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Commands:** Type `/help` in TTYverse for command list
|
||||
- **Issues:** Report bugs at https://git.stormux.org/storm/ttyverse/issues
|
||||
- **Wiki:** This wiki for comprehensive documentation
|
||||
- **Community:** Find support in the fediverse community
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
346
Installation.md
Normal file
346
Installation.md
Normal file
@ -0,0 +1,346 @@
|
||||
# Installation
|
||||
|
||||
TTYverse is a single Perl script that works on any Unix-like system with Perl and curl. This guide covers installation methods for different systems.
|
||||
|
||||
## System Requirements
|
||||
|
||||
### Required
|
||||
- **Perl 5.x** - TTYverse is written in Perl
|
||||
- **curl** - For API communication with fediverse servers
|
||||
- **Terminal emulator** - Any Unix/Linux terminal
|
||||
|
||||
### Recommended
|
||||
- **Term::ReadLine::Gnu** - Enhanced command line editing
|
||||
- **PulseAudio** - For sound notifications
|
||||
- **GUI browser** - For opening links (Firefox, Chrome, etc.)
|
||||
- **CLI browser** - For terminal link opening (w3m, elinks, lynx)
|
||||
|
||||
### Optional
|
||||
- **Desktop notification system** - For desktop alerts
|
||||
- **Text-to-speech** - For TTS extensions
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Method 1: Direct Download (Recommended)
|
||||
|
||||
```bash
|
||||
# Download latest release
|
||||
wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
|
||||
|
||||
# Make executable
|
||||
chmod +x ttyverse.pl
|
||||
|
||||
# Run TTYverse
|
||||
./ttyverse.pl
|
||||
```
|
||||
|
||||
### Method 2: Git Clone
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://git.stormux.org/storm/ttyverse.git
|
||||
cd ttyverse
|
||||
|
||||
# Run TTYverse
|
||||
perl ttyverse.pl
|
||||
```
|
||||
|
||||
### Method 3: System Package (Future)
|
||||
|
||||
*System packages are planned for future releases*
|
||||
|
||||
## Dependency Installation
|
||||
|
||||
### Debian/Ubuntu
|
||||
```bash
|
||||
# Basic dependencies
|
||||
sudo apt update
|
||||
sudo apt install perl curl
|
||||
|
||||
# Enhanced readline support
|
||||
sudo apt install libterm-readline-gnu-perl
|
||||
|
||||
# Sound support
|
||||
sudo apt install pulseaudio-utils
|
||||
|
||||
# Browser options
|
||||
sudo apt install firefox w3m
|
||||
|
||||
# Optional: Desktop notifications
|
||||
sudo apt install libdesktop-notify-perl
|
||||
```
|
||||
|
||||
### Arch Linux
|
||||
```bash
|
||||
# Basic dependencies
|
||||
sudo pacman -S perl curl
|
||||
|
||||
# Enhanced readline support
|
||||
sudo pacman -S perl-term-readline-gnu
|
||||
|
||||
# Sound support
|
||||
sudo pacman -S pulseaudio
|
||||
|
||||
# Browser options
|
||||
sudo pacman -S firefox w3m
|
||||
|
||||
# Optional: AUR packages for additional features
|
||||
yay -S perl-desktop-notify
|
||||
```
|
||||
|
||||
### Fedora/RHEL/CentOS
|
||||
```bash
|
||||
# Basic dependencies
|
||||
sudo dnf install perl curl
|
||||
|
||||
# Enhanced readline support
|
||||
sudo dnf install perl-Term-ReadLine-Gnu
|
||||
|
||||
# Sound support
|
||||
sudo dnf install pulseaudio-utils
|
||||
|
||||
# Browser options
|
||||
sudo dnf install firefox w3m
|
||||
```
|
||||
|
||||
### macOS
|
||||
```bash
|
||||
# Install Homebrew if not already installed
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# Install dependencies
|
||||
brew install perl curl
|
||||
|
||||
# Install optional dependencies
|
||||
brew install w3m
|
||||
|
||||
# Note: macOS includes curl by default
|
||||
```
|
||||
|
||||
### FreeBSD
|
||||
```bash
|
||||
# Install from ports
|
||||
sudo pkg install perl5 curl w3m
|
||||
|
||||
# Or compile from ports
|
||||
cd /usr/ports/lang/perl5.32 && sudo make install clean
|
||||
cd /usr/ports/ftp/curl && sudo make install clean
|
||||
```
|
||||
|
||||
## Installation Locations
|
||||
|
||||
### Portable Installation
|
||||
TTYverse can run from any directory:
|
||||
```bash
|
||||
# Download to home directory
|
||||
cd ~
|
||||
wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
|
||||
chmod +x ttyverse.pl
|
||||
./ttyverse.pl
|
||||
```
|
||||
|
||||
### System-wide Installation
|
||||
```bash
|
||||
# Install to /usr/local/bin for all users
|
||||
sudo wget -O /usr/local/bin/ttyverse https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
|
||||
sudo chmod +x /usr/local/bin/ttyverse
|
||||
|
||||
# Now any user can run
|
||||
ttyverse
|
||||
```
|
||||
|
||||
### Personal Binary Directory
|
||||
```bash
|
||||
# Install to personal bin directory
|
||||
mkdir -p ~/bin
|
||||
wget -O ~/bin/ttyverse https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
|
||||
chmod +x ~/bin/ttyverse
|
||||
|
||||
# Add to PATH if needed
|
||||
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
|
||||
# Run from anywhere
|
||||
ttyverse
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### Test Installation
|
||||
```bash
|
||||
# Check TTYverse version
|
||||
./ttyverse.pl -version
|
||||
|
||||
# Expected output:
|
||||
# TTYverse 2025.07.28 (c)2025 Storm Dragon
|
||||
```
|
||||
|
||||
### Test Dependencies
|
||||
```bash
|
||||
# Check Perl
|
||||
perl --version
|
||||
|
||||
# Check curl
|
||||
curl --version
|
||||
|
||||
# Check optional readline
|
||||
perl -MArray::ReadLine::Gnu -e 'print "ReadLine::Gnu available\n"' 2>/dev/null || echo "ReadLine::Gnu not available"
|
||||
|
||||
# Check sound support
|
||||
paplay --version 2>/dev/null || echo "PulseAudio not available"
|
||||
```
|
||||
|
||||
## First Run Setup
|
||||
|
||||
### Initial Configuration
|
||||
When you first run TTYverse, it will:
|
||||
|
||||
1. **Create config directories:**
|
||||
```
|
||||
~/.config/ttyverse/
|
||||
~/.local/share/ttyverse/
|
||||
```
|
||||
|
||||
2. **Download extensions:**
|
||||
- Sound pack extension
|
||||
- TTS extension (if available)
|
||||
- Notification extensions
|
||||
|
||||
3. **OAuth setup:**
|
||||
- Prompt for fediverse server
|
||||
- Open browser for authorization
|
||||
- Save authentication tokens
|
||||
|
||||
### Manual Extension Setup
|
||||
```bash
|
||||
# Create extension directory
|
||||
mkdir -p ~/.local/share/ttyverse/extensions/
|
||||
|
||||
# Download extensions manually if needed
|
||||
cd ~/.local/share/ttyverse/extensions/
|
||||
wget https://git.stormux.org/storm/ttyverse/raw/branch/master/extensions/soundpack.pl
|
||||
wget https://git.stormux.org/storm/ttyverse/raw/branch/master/extensions/tts.pl
|
||||
chmod +x *.pl
|
||||
```
|
||||
|
||||
## Troubleshooting Installation
|
||||
|
||||
### Permission Issues
|
||||
```bash
|
||||
# Make sure you can execute the script
|
||||
ls -la ttyverse.pl
|
||||
chmod +x ttyverse.pl
|
||||
|
||||
# Check directory permissions
|
||||
ls -la ~/.config/
|
||||
mkdir -p ~/.config/ttyverse/
|
||||
chmod 700 ~/.config/ttyverse/
|
||||
```
|
||||
|
||||
### Missing Dependencies
|
||||
```bash
|
||||
# Test if Perl modules are available
|
||||
perl -MHTml::Entities -e 'print "HTML::Entities available\n"'
|
||||
perl -MArray::JSON -e 'print "JSON available\n"'
|
||||
|
||||
# Install missing Perl modules
|
||||
cpan HTML::Entities
|
||||
cpan JSON
|
||||
```
|
||||
|
||||
### Network Issues
|
||||
```bash
|
||||
# Test network connectivity
|
||||
ping 8.8.8.8
|
||||
curl -I https://git.stormux.org/
|
||||
|
||||
# Test SSL certificates
|
||||
curl https://mastodon.social/api/v1/instance
|
||||
```
|
||||
|
||||
## Development Installation
|
||||
|
||||
### For Contributors
|
||||
```bash
|
||||
# Clone development repository
|
||||
git clone https://git.stormux.org/storm/ttyverse.git
|
||||
cd ttyverse
|
||||
|
||||
# Install development dependencies
|
||||
# (Add any dev-specific requirements here)
|
||||
|
||||
# Run from source
|
||||
perl ttyverse.pl -verbose
|
||||
```
|
||||
|
||||
### Building from Source
|
||||
```bash
|
||||
# TTYverse is a single script, no build process needed
|
||||
# Just ensure you have the latest version:
|
||||
|
||||
cd ttyverse
|
||||
git pull origin master
|
||||
perl ttyverse.pl
|
||||
```
|
||||
|
||||
## Uninstallation
|
||||
|
||||
### Remove TTYverse
|
||||
```bash
|
||||
# Remove script
|
||||
rm ttyverse.pl
|
||||
# or
|
||||
sudo rm /usr/local/bin/ttyverse
|
||||
|
||||
# Remove configuration (optional - saves your settings)
|
||||
rm -rf ~/.config/ttyverse/
|
||||
rm -rf ~/.local/share/ttyverse/
|
||||
rm -rf ~/.cache/ttyverse/
|
||||
```
|
||||
|
||||
### Keep Configuration
|
||||
If you want to reinstall later, keep the config directories:
|
||||
```bash
|
||||
# Only remove the script
|
||||
rm ttyverse.pl
|
||||
|
||||
# Configuration in ~/.config/ttyverse/ will be reused
|
||||
```
|
||||
|
||||
## Updating
|
||||
|
||||
### Manual Update
|
||||
```bash
|
||||
# Download new version
|
||||
wget -O ttyverse.pl.new https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
|
||||
|
||||
# Backup old version
|
||||
mv ttyverse.pl ttyverse.pl.backup
|
||||
|
||||
# Install new version
|
||||
mv ttyverse.pl.new ttyverse.pl
|
||||
chmod +x ttyverse.pl
|
||||
|
||||
# Test new version
|
||||
./ttyverse.pl -version
|
||||
```
|
||||
|
||||
### Git Update
|
||||
```bash
|
||||
# If installed via git
|
||||
cd ttyverse
|
||||
git pull origin master
|
||||
```
|
||||
|
||||
### Version Check
|
||||
TTYverse checks for updates automatically:
|
||||
```
|
||||
-- checking TTYverse version...
|
||||
-- your version of TTYverse is up to date (2025.07.28)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Next:** [Getting Started](Getting-Started) | [Configuration](Configuration)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
244
Media-Uploads.md
Normal file
244
Media-Uploads.md
Normal file
@ -0,0 +1,244 @@
|
||||
# Media Uploads
|
||||
|
||||
TTYverse supports uploading images, audio, and video files to your fediverse posts with a strong focus on accessibility.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### Upload Media with Post
|
||||
```bash
|
||||
/media /path/to/file.jpg Optional post message here
|
||||
```
|
||||
|
||||
### Upload Media Only
|
||||
```bash
|
||||
/media /path/to/file.mp3
|
||||
```
|
||||
|
||||
TTYverse will:
|
||||
1. Detect the file type automatically
|
||||
2. Prompt for alt-text (images only)
|
||||
3. Upload the media to your server
|
||||
4. Create a post with the media attached
|
||||
|
||||
## Supported File Types
|
||||
|
||||
### Images
|
||||
- **JPEG** (`.jpg`, `.jpeg`)
|
||||
- **PNG** (`.png`)
|
||||
- **GIF** (`.gif`)
|
||||
- **WebP** (`.webp`)
|
||||
|
||||
### Audio
|
||||
- **MP3** (`.mp3`)
|
||||
- **OGG** (`.ogg`)
|
||||
- **WAV** (`.wav`)
|
||||
- **FLAC** (`.flac`)
|
||||
- **M4A** (`.m4a`)
|
||||
|
||||
### Video
|
||||
- **MP4** (`.mp4`)
|
||||
- **WebM** (`.webm`)
|
||||
- **MOV** (`.mov`)
|
||||
|
||||
## Accessibility Requirements
|
||||
|
||||
### Image Alt-Text (Required)
|
||||
|
||||
TTYverse enforces alt-text for all images to ensure accessibility:
|
||||
|
||||
```bash
|
||||
TTYverse> /media /home/user/photo.jpg
|
||||
-- Detected file type: image/jpeg
|
||||
-- Images require alt-text for accessibility
|
||||
Enter alt text for photo.jpg: A sunset over mountains with orange and purple clouds
|
||||
Enter post message (optional): Beautiful evening hike!
|
||||
-- Uploading media file...
|
||||
-- Media uploaded successfully
|
||||
-- Post created successfully!
|
||||
```
|
||||
|
||||
### Alt-Text Guidelines
|
||||
|
||||
**Good alt-text examples:**
|
||||
- "A golden retriever playing fetch in a park"
|
||||
- "Screenshot of terminal showing TTYverse timeline"
|
||||
- "Graph showing temperature increase over time"
|
||||
- "Person wearing red jacket standing on snowy mountain"
|
||||
|
||||
**Avoid:**
|
||||
- Empty alt-text (upload will be cancelled)
|
||||
- Redundant phrases like "image of" or "picture showing"
|
||||
- File names or technical details
|
||||
- Vague descriptions like "thing" or "stuff"
|
||||
|
||||
### Enforcement Message
|
||||
|
||||
If you try to upload an image without alt-text:
|
||||
|
||||
```
|
||||
-- Upload cancelled: Alt-text is required for images
|
||||
-- If you're going to use a client maintained by a blind guy, you can damn well describe your images!
|
||||
```
|
||||
|
||||
This enforcement ensures TTYverse maintains its accessibility-first philosophy.
|
||||
|
||||
## Audio and Video
|
||||
|
||||
Audio and video files don't require alt-text, but you can still add descriptive post text:
|
||||
|
||||
```bash
|
||||
/media /path/to/song.mp3 My latest recording - feedback welcome!
|
||||
/media /path/to/video.mp4 Time-lapse of sunset from my backyard
|
||||
```
|
||||
|
||||
## File Size Limits
|
||||
|
||||
Media upload limits depend on your fediverse server:
|
||||
|
||||
- **Mastodon default:** 8MB for images, 40MB for video/audio
|
||||
- **GoToSocial:** Configurable by admin
|
||||
- **Other servers:** Check your instance's upload limits
|
||||
|
||||
TTYverse will show server error messages if files are too large.
|
||||
|
||||
## Upload Process
|
||||
|
||||
### Step-by-Step Flow
|
||||
|
||||
1. **File Detection**
|
||||
```
|
||||
-- Detected file type: image/jpeg
|
||||
```
|
||||
|
||||
2. **Alt-Text Prompt** (images only)
|
||||
```
|
||||
-- Images require alt-text for accessibility
|
||||
Enter alt text for filename.jpg: [your description]
|
||||
```
|
||||
|
||||
3. **Post Message** (optional)
|
||||
```
|
||||
Enter post message (optional): [your message]
|
||||
```
|
||||
|
||||
4. **Upload and Post**
|
||||
```
|
||||
-- Uploading media file...
|
||||
-- Media uploaded successfully (ID: xxxxxxxxx)
|
||||
-- Creating post with media attachment...
|
||||
-- Post created successfully!
|
||||
```
|
||||
|
||||
### Background Processing
|
||||
|
||||
TTYverse uploads happen in the foreground process while background monitoring continues. The multi-process architecture ensures:
|
||||
- Timeline updates don't interrupt uploads
|
||||
- Media uploads don't block timeline refresh
|
||||
- User can continue using TTYverse after posting
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Upload Errors
|
||||
|
||||
**File not found:**
|
||||
```
|
||||
-- ERROR: File not found: /path/to/missing.jpg
|
||||
```
|
||||
|
||||
**Unsupported file type:**
|
||||
```
|
||||
-- ERROR: Unsupported file type: application/pdf
|
||||
-- Supported types: image/*, audio/*, video/*
|
||||
```
|
||||
|
||||
**Server upload failure:**
|
||||
```
|
||||
-- ERROR: Media upload failed
|
||||
-- Response: {"error":"File too large"}
|
||||
```
|
||||
|
||||
**Authentication errors:**
|
||||
```
|
||||
-- ERROR: No media ID in response
|
||||
-- Response: {"error":"Unauthorized: token not supplied"}
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**Authentication issues:**
|
||||
1. Check OAuth setup: `ls ~/.config/ttyverse/`
|
||||
2. Verify token: `/refresh` to test API access
|
||||
3. Re-authenticate if needed: `rm ~/.config/ttyverse/*` and restart
|
||||
|
||||
**File permission issues:**
|
||||
1. Check file exists: `ls -la /path/to/file`
|
||||
2. Verify read permissions: `cat /path/to/file > /dev/null`
|
||||
3. Use absolute paths when possible
|
||||
|
||||
**Server limits:**
|
||||
1. Check file size: `ls -lh /path/to/file`
|
||||
2. Try smaller files to test limits
|
||||
3. Check server documentation for upload limits
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Alt-Text Writing
|
||||
- **Be concise but descriptive**
|
||||
- **Include relevant context** for the post
|
||||
- **Describe the important elements** that sighted users would notice
|
||||
- **Use natural language** as if describing to a friend
|
||||
|
||||
### File Management
|
||||
- **Use descriptive filenames** for organization
|
||||
- **Keep files organized** in logical directories
|
||||
- **Check file sizes** before uploading
|
||||
- **Test uploads** with small files first
|
||||
|
||||
### Accessibility Considerations
|
||||
- **Always provide meaningful alt-text** for images
|
||||
- **Include transcripts** in post text for audio content
|
||||
- **Describe video content** in post text when relevant
|
||||
- **Consider screen reader users** in all media posts
|
||||
|
||||
## Examples
|
||||
|
||||
### Image Post with Context
|
||||
```bash
|
||||
/media ~/photos/garden.jpg Tomatoes are finally ripening!
|
||||
# Alt-text: "Red and green tomatoes growing on vines in a garden"
|
||||
```
|
||||
|
||||
### Audio with Description
|
||||
```bash
|
||||
/media ~/recordings/bird-song.mp3 Recorded this morning in the park
|
||||
```
|
||||
|
||||
### Video with Context
|
||||
```bash
|
||||
/media ~/videos/demo.mp4 Quick demo of the new feature working
|
||||
```
|
||||
|
||||
### Technical Screenshot
|
||||
```bash
|
||||
/media ~/screenshots/terminal.png
|
||||
# Alt-text: "Terminal window showing TTYverse commands and timeline with several posts visible"
|
||||
```
|
||||
|
||||
## Integration with Fediverse
|
||||
|
||||
### Server Compatibility
|
||||
- **Mastodon:** Full support for all media types
|
||||
- **GoToSocial:** Full support, admin-configurable limits
|
||||
- **Pleroma:** Basic support, check instance features
|
||||
- **Other servers:** Media support varies by implementation
|
||||
|
||||
### Cross-Instance Media
|
||||
- Media uploads work with any compatible fediverse server
|
||||
- Alt-text is preserved when posts are viewed on other instances
|
||||
- Media appears in boosts and replies across the fediverse
|
||||
|
||||
---
|
||||
|
||||
**See also:** [Commands Reference](Commands-Reference) | [Accessibility](Accessibility) | [Server Compatibility](Server-Compatibility)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
152
Quick-Commands.md
Normal file
152
Quick-Commands.md
Normal file
@ -0,0 +1,152 @@
|
||||
# Quick Commands Reference
|
||||
|
||||
Essential TTYverse commands for quick reference. For complete documentation, see [Commands Reference](Commands-Reference).
|
||||
|
||||
## Essential Commands
|
||||
|
||||
### Getting Started
|
||||
```bash
|
||||
/help # Show all available commands
|
||||
/timeline # Show your home timeline
|
||||
/refresh # Refresh timeline
|
||||
/quit # Exit TTYverse
|
||||
```
|
||||
|
||||
### Posting and Interaction
|
||||
```bash
|
||||
/post Hello world! # Create a public post
|
||||
/reply a3 Great point! # Reply to post a3
|
||||
/boost a3 # Boost post a3
|
||||
/fav a3 # Favorite post a3
|
||||
/bookmark a3 # Bookmark post a3
|
||||
```
|
||||
|
||||
### Media and Content
|
||||
```bash
|
||||
/media /path/image.jpg # Upload image (requires alt-text)
|
||||
/media /path/audio.mp3 # Upload audio file
|
||||
/url a3 # Open URL from post a3
|
||||
```
|
||||
|
||||
### Navigation
|
||||
```bash
|
||||
/timeline # Home timeline
|
||||
/timeline local # Local instance timeline
|
||||
/timeline federated # Federated timeline
|
||||
/timeline bookmarks # Your bookmarks
|
||||
/again # Load more posts
|
||||
/last 10 # Show last 10 cached posts
|
||||
```
|
||||
|
||||
### Direct Messages
|
||||
```bash
|
||||
/dms # Show direct messages
|
||||
/reply da1 Thanks! # Reply to DM da1
|
||||
```
|
||||
|
||||
### Search and Discovery
|
||||
```bash
|
||||
/search #hashtag # Search hashtag
|
||||
/search @username # Find user
|
||||
/search "search text" # Search posts
|
||||
/whois @username # Get user info
|
||||
```
|
||||
|
||||
### Account Management
|
||||
```bash
|
||||
/follow @user # Follow a user
|
||||
/unfollow @user # Unfollow a user
|
||||
/block @user # Block a user
|
||||
/mute @user # Mute a user
|
||||
```
|
||||
|
||||
### Poll Interaction
|
||||
```bash
|
||||
/vote a3 1 # Vote for option 1 in poll a3
|
||||
/vote b2 2,3 # Vote for options 2 and 3
|
||||
```
|
||||
|
||||
### Configuration
|
||||
```bash
|
||||
/set effpause 300 # Set refresh interval (5 minutes)
|
||||
/set gui_browser firefox # Set GUI browser
|
||||
/set cli_browser w3m # Set CLI browser
|
||||
/get effpause # Show current refresh interval
|
||||
```
|
||||
|
||||
### Information
|
||||
```bash
|
||||
/version # Show TTYverse version
|
||||
/rate # Show API rate limit status
|
||||
/verbose # Toggle verbose output
|
||||
/debug # Toggle debug output
|
||||
```
|
||||
|
||||
## Post Menu Codes
|
||||
|
||||
TTYverse assigns codes to posts for easy reference:
|
||||
- **Timeline posts:** `a0`, `a1`, `a2`... `a9`, `b0`, `b1`, etc.
|
||||
- **Direct messages:** `da0`, `da1`, `da2`, etc.
|
||||
|
||||
Use these codes with interaction commands:
|
||||
```bash
|
||||
/boost a3 # Boost post a3
|
||||
/reply b7 Nice post! # Reply to post b7
|
||||
/url c2 # Open URL from post c2
|
||||
```
|
||||
|
||||
## Visibility Indicators
|
||||
|
||||
Posts show their visibility level:
|
||||
- **[Public]** - Visible to everyone
|
||||
- **[Unlisted]** - Public but not in timelines
|
||||
- **[Followers]** - Only followers can see
|
||||
- **[Direct]** - Only mentioned users can see
|
||||
|
||||
## Quick Tips
|
||||
|
||||
1. **Use tab completion** - Start typing commands and press Tab
|
||||
2. **Command history** - Use up/down arrows for previous commands
|
||||
3. **Help anytime** - Type `/help` to see all commands
|
||||
4. **Menu codes change** - Always use current codes as new posts load
|
||||
5. **Alt-text required** - Images must have descriptions
|
||||
6. **Multiple timelines** - Switch between different timeline views
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Reading Timeline
|
||||
```bash
|
||||
/timeline # Load home timeline
|
||||
/again # See more posts
|
||||
/url a3 # Open interesting link
|
||||
/boost a5 # Share good post
|
||||
```
|
||||
|
||||
### Posting with Media
|
||||
```bash
|
||||
/media ~/photo.jpg # Upload image
|
||||
# Enter alt-text when prompted
|
||||
# Enter optional post message
|
||||
```
|
||||
|
||||
### Engaging with Posts
|
||||
```bash
|
||||
/fav a3 # Like the post
|
||||
/boost a3 # Share it
|
||||
/reply a3 Great point! # Add your thoughts
|
||||
/bookmark a3 # Save for later
|
||||
```
|
||||
|
||||
### Managing Timeline
|
||||
```bash
|
||||
/timeline bookmarks # See saved posts
|
||||
/timeline local # See local community
|
||||
/search #topic # Find specific content
|
||||
/refresh # Get latest posts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**See also:** [Commands Reference](Commands-Reference) | [Getting Started](Getting-Started) | [Basic Usage](Basic-Usage)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
479
Troubleshooting.md
Normal file
479
Troubleshooting.md
Normal file
@ -0,0 +1,479 @@
|
||||
# Troubleshooting
|
||||
|
||||
Common issues and solutions for TTYverse. If you don't find your issue here, check the [FAQ](FAQ) or report it at https://git.stormux.org/storm/ttyverse/issues.
|
||||
|
||||
## Connection Issues
|
||||
|
||||
### "Connection failed" or "Cannot connect to server"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
-- ERROR: Connection failed
|
||||
-- Unable to fetch timeline
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Check internet connection:**
|
||||
```bash
|
||||
ping 8.8.8.8
|
||||
curl -I https://google.com
|
||||
```
|
||||
|
||||
2. **Verify server URL:**
|
||||
```bash
|
||||
# Check your configured server
|
||||
grep apibase ~/.config/ttyverse/ttyverse_rc
|
||||
|
||||
# Test server manually
|
||||
curl https://your-instance.com/api/v1/instance
|
||||
```
|
||||
|
||||
3. **Check server status:**
|
||||
- Visit your server's web interface
|
||||
- Check server status pages
|
||||
- Try different DNS servers
|
||||
|
||||
4. **Firewall/proxy issues:**
|
||||
```bash
|
||||
# Test if curl works
|
||||
curl https://your-instance.com/api/v1/instance
|
||||
|
||||
# Check proxy settings
|
||||
echo $HTTP_PROXY
|
||||
echo $HTTPS_PROXY
|
||||
```
|
||||
|
||||
### SSL/TLS Certificate Issues
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
-- SSL certificate problem
|
||||
-- unable to get local issuer certificate
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Update CA certificates:**
|
||||
```bash
|
||||
# Debian/Ubuntu
|
||||
sudo apt update && sudo apt install ca-certificates
|
||||
|
||||
# Arch Linux
|
||||
sudo pacman -S ca-certificates
|
||||
```
|
||||
|
||||
2. **Check system time:**
|
||||
```bash
|
||||
date
|
||||
# Ensure system time is correct
|
||||
```
|
||||
|
||||
3. **Test SSL manually:**
|
||||
```bash
|
||||
openssl s_client -connect your-instance.com:443 -servername your-instance.com
|
||||
```
|
||||
|
||||
## Authentication Issues
|
||||
|
||||
### "Unauthorized" or "Token not supplied"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
-- ERROR: Unauthorized: token not supplied
|
||||
-- Authentication failed
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Check OAuth credentials:**
|
||||
```bash
|
||||
# Verify token exists
|
||||
cat ~/.config/ttyverse/ttyverse_rc | grep tokenkey
|
||||
|
||||
# Check file permissions
|
||||
ls -la ~/.config/ttyverse/
|
||||
```
|
||||
|
||||
2. **Re-authenticate:**
|
||||
```bash
|
||||
# Remove old credentials
|
||||
rm ~/.config/ttyverse/oauth_credentials
|
||||
rm ~/.config/ttyverse/ttyverse_rc
|
||||
|
||||
# Restart TTYverse for fresh setup
|
||||
./ttyverse.pl
|
||||
```
|
||||
|
||||
3. **Check token validity:**
|
||||
```bash
|
||||
# Test token manually
|
||||
TOKEN=$(grep tokenkey ~/.config/ttyverse/ttyverse_rc | cut -d= -f2)
|
||||
curl -H "Authorization: Bearer $TOKEN" https://your-instance.com/api/v1/accounts/verify_credentials
|
||||
```
|
||||
|
||||
### OAuth Setup Fails
|
||||
|
||||
**Symptoms:**
|
||||
- Browser doesn't open during setup
|
||||
- "Failed to get authorization code"
|
||||
- OAuth redirect fails
|
||||
|
||||
**Solutions:**
|
||||
1. **Manual OAuth setup:**
|
||||
- Copy the authorization URL from TTYverse
|
||||
- Open in browser manually
|
||||
- Copy authorization code back to TTYverse
|
||||
|
||||
2. **Check browser setup:**
|
||||
```bash
|
||||
# Test browser detection
|
||||
echo $DISPLAY
|
||||
which xdg-open firefox chrome
|
||||
```
|
||||
|
||||
3. **Alternative authentication:**
|
||||
- Use different device for OAuth
|
||||
- Try text-based browser
|
||||
- Check server's OAuth settings
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow Timeline Loading
|
||||
|
||||
**Symptoms:**
|
||||
- Long delays fetching posts
|
||||
- Timeouts during refresh
|
||||
|
||||
**Solutions:**
|
||||
1. **Adjust refresh settings:**
|
||||
```bash
|
||||
# Increase refresh interval
|
||||
/set effpause 300
|
||||
|
||||
# Reduce post count
|
||||
/set timeline_count 15
|
||||
```
|
||||
|
||||
2. **Check network speed:**
|
||||
```bash
|
||||
# Test connection speed to server
|
||||
time curl -I https://your-instance.com/
|
||||
```
|
||||
|
||||
3. **Server performance:**
|
||||
- Try different instance
|
||||
- Check server status
|
||||
- Use smaller media uploads
|
||||
|
||||
### High Memory Usage
|
||||
|
||||
**Symptoms:**
|
||||
- TTYverse consuming excessive RAM
|
||||
- System becoming unresponsive
|
||||
|
||||
**Solutions:**
|
||||
1. **Reduce cache size:**
|
||||
```bash
|
||||
# Edit config to reduce cached posts
|
||||
echo "timeline_cache=50" >> ~/.config/ttyverse/ttyverse_rc
|
||||
```
|
||||
|
||||
2. **Restart periodically:**
|
||||
```bash
|
||||
# Exit and restart TTYverse
|
||||
/quit
|
||||
./ttyverse.pl
|
||||
```
|
||||
|
||||
3. **Monitor memory:**
|
||||
```bash
|
||||
# Check TTYverse memory usage
|
||||
ps aux | grep ttyverse
|
||||
top -p $(pgrep ttyverse)
|
||||
```
|
||||
|
||||
## Media Upload Issues
|
||||
|
||||
### Media Upload Fails
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
-- ERROR: Media upload failed
|
||||
-- Response: {"error":"File too large"}
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Check file size:**
|
||||
```bash
|
||||
# Check file size
|
||||
ls -lh /path/to/file
|
||||
|
||||
# Common limits:
|
||||
# Images: 8MB on Mastodon
|
||||
# Video/Audio: 40MB on Mastodon
|
||||
```
|
||||
|
||||
2. **Verify file format:**
|
||||
```bash
|
||||
# Check MIME type
|
||||
file --mime-type /path/to/file
|
||||
|
||||
# Supported: image/*, audio/*, video/*
|
||||
```
|
||||
|
||||
3. **Test with smaller file:**
|
||||
```bash
|
||||
# Create test image
|
||||
convert -size 100x100 xc:red test.jpg
|
||||
/media test.jpg
|
||||
```
|
||||
|
||||
### Alt-text Issues
|
||||
|
||||
**Symptoms:**
|
||||
- Upload cancelled for images
|
||||
- Alt-text prompt not appearing
|
||||
|
||||
**Solutions:**
|
||||
1. **Provide alt-text:**
|
||||
- Always describe images meaningfully
|
||||
- Don't leave alt-text empty
|
||||
- Use descriptive, concise language
|
||||
|
||||
2. **Check file type detection:**
|
||||
```bash
|
||||
# Verify file is detected as image
|
||||
file --mime-type /path/to/image.jpg
|
||||
# Should show: image/jpeg
|
||||
```
|
||||
|
||||
## Sound and Extension Issues
|
||||
|
||||
### No Sound Notifications
|
||||
|
||||
**Symptoms:**
|
||||
- Sound notifications not playing
|
||||
- Silent operation
|
||||
|
||||
**Solutions:**
|
||||
1. **Check sound files:**
|
||||
```bash
|
||||
# Verify sound files exist
|
||||
ls ~/.local/share/ttyverse/sounds/default/
|
||||
|
||||
# Test sound playback
|
||||
paplay ~/.local/share/ttyverse/sounds/default/default.ogg
|
||||
```
|
||||
|
||||
2. **Check audio system:**
|
||||
```bash
|
||||
# Test system audio
|
||||
speaker-test -c 2 -t wav
|
||||
|
||||
# Check PulseAudio
|
||||
pulseaudio --check
|
||||
```
|
||||
|
||||
3. **Install sound dependencies:**
|
||||
```bash
|
||||
# Install PulseAudio utils
|
||||
sudo apt install pulseaudio-utils # Debian/Ubuntu
|
||||
sudo pacman -S pulseaudio # Arch Linux
|
||||
```
|
||||
|
||||
### Extension Loading Fails
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
** ERROR: Failed to load extension soundpack.pl
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Check extension files:**
|
||||
```bash
|
||||
# Verify extensions exist
|
||||
ls ~/.local/share/ttyverse/extensions/
|
||||
|
||||
# Check file permissions
|
||||
chmod +x ~/.local/share/ttyverse/extensions/*.pl
|
||||
```
|
||||
|
||||
2. **Install Perl dependencies:**
|
||||
```bash
|
||||
# Common Perl modules needed
|
||||
cpan Audio::Play::Simple
|
||||
cpan Desktop::Notify
|
||||
```
|
||||
|
||||
3. **Manual extension loading:**
|
||||
```bash
|
||||
# Test extension manually
|
||||
perl ~/.local/share/ttyverse/extensions/soundpack.pl
|
||||
```
|
||||
|
||||
## Display and Terminal Issues
|
||||
|
||||
### Readline Problems
|
||||
|
||||
**Symptoms:**
|
||||
- No command history
|
||||
- No tab completion
|
||||
- Broken line editing
|
||||
|
||||
**Solutions:**
|
||||
1. **Install Perl readline:**
|
||||
```bash
|
||||
# Install Term::ReadLine::Gnu
|
||||
sudo apt install libterm-readline-gnu-perl # Debian/Ubuntu
|
||||
cpan Term::ReadLine::Gnu # Manual install
|
||||
```
|
||||
|
||||
2. **Check terminal compatibility:**
|
||||
```bash
|
||||
# Verify terminal type
|
||||
echo $TERM
|
||||
|
||||
# Test readline
|
||||
perl -MArray::ReadLine::Gnu -e 'print "Readline available\n"'
|
||||
```
|
||||
|
||||
3. **Alternative terminals:**
|
||||
- Try different terminal emulator
|
||||
- Use screen or tmux
|
||||
- Check terminal settings
|
||||
|
||||
### Character Encoding Issues
|
||||
|
||||
**Symptoms:**
|
||||
- Garbled text
|
||||
- Unicode characters display incorrectly
|
||||
- Emoji problems
|
||||
|
||||
**Solutions:**
|
||||
1. **Check locale settings:**
|
||||
```bash
|
||||
# Verify UTF-8 locale
|
||||
locale
|
||||
echo $LANG
|
||||
|
||||
# Set UTF-8 if needed
|
||||
export LANG=en_US.UTF-8
|
||||
export LC_ALL=en_US.UTF-8
|
||||
```
|
||||
|
||||
2. **Terminal encoding:**
|
||||
- Ensure terminal supports UTF-8
|
||||
- Check terminal preferences
|
||||
- Try different terminal emulator
|
||||
|
||||
## Configuration Issues
|
||||
|
||||
### Config File Not Found
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
-- Config file not found
|
||||
-- Using defaults
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Create config directory:**
|
||||
```bash
|
||||
mkdir -p ~/.config/ttyverse/
|
||||
chmod 700 ~/.config/ttyverse/
|
||||
```
|
||||
|
||||
2. **Check XDG variables:**
|
||||
```bash
|
||||
echo $XDG_CONFIG_HOME
|
||||
echo $HOME
|
||||
```
|
||||
|
||||
3. **Manual config creation:**
|
||||
```bash
|
||||
# Create basic config
|
||||
cat > ~/.config/ttyverse/ttyverse_rc << EOF
|
||||
effpause=120
|
||||
verbose=1
|
||||
readline=1
|
||||
EOF
|
||||
```
|
||||
|
||||
### Permission Denied Errors
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
-- ERROR: Permission denied writing to config
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Fix permissions:**
|
||||
```bash
|
||||
# Set correct permissions
|
||||
chmod 700 ~/.config/ttyverse/
|
||||
chmod 600 ~/.config/ttyverse/*
|
||||
```
|
||||
|
||||
2. **Check ownership:**
|
||||
```bash
|
||||
# Verify you own the files
|
||||
ls -la ~/.config/ttyverse/
|
||||
|
||||
# Fix ownership if needed
|
||||
chown -R $USER:$USER ~/.config/ttyverse/
|
||||
```
|
||||
|
||||
## Getting Debug Information
|
||||
|
||||
### Enable Debug Output
|
||||
```bash
|
||||
# Run with verbose output
|
||||
./ttyverse.pl -verbose
|
||||
|
||||
# Enable debug in session
|
||||
/debug
|
||||
/verbose
|
||||
```
|
||||
|
||||
### Collect System Information
|
||||
```bash
|
||||
# System info
|
||||
uname -a
|
||||
perl --version
|
||||
curl --version
|
||||
|
||||
# TTYverse info
|
||||
./ttyverse.pl -version
|
||||
|
||||
# Config info
|
||||
ls -la ~/.config/ttyverse/
|
||||
cat ~/.config/ttyverse/ttyverse_rc | grep -v tokenkey
|
||||
```
|
||||
|
||||
### Log Analysis
|
||||
```bash
|
||||
# Check for error patterns
|
||||
grep -i error debug.log
|
||||
grep -i failed debug.log
|
||||
grep -i timeout debug.log
|
||||
|
||||
# Timeline of events
|
||||
tail -f debug.log
|
||||
```
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
When reporting bugs, include:
|
||||
|
||||
1. **TTYverse version:** `./ttyverse.pl -version`
|
||||
2. **System info:** `uname -a` and `perl --version`
|
||||
3. **Error messages:** Copy exact error text
|
||||
4. **Steps to reproduce:** What you were doing when it failed
|
||||
5. **Debug output:** Run with `-verbose` and include relevant logs
|
||||
6. **Configuration:** Sanitized config (remove tokens!)
|
||||
|
||||
**Report at:** https://git.stormux.org/storm/ttyverse/issues
|
||||
|
||||
---
|
||||
|
||||
**See also:** [FAQ](FAQ) | [Configuration](Configuration) | [Getting Started](Getting-Started)
|
||||
|
||||
*Last updated: 2025-07-28*
|
||||
Reference in New Issue
Block a user