ContextQMD
Back to Provenance

RetroAchievements CLI Tool Demo

PVCheevos/CLI-DEMO.md

3.3.16.8 KB
Original Source

RetroAchievements CLI Tool Demo

The ra-cli tool provides a comprehensive command-line interface for testing and exploring the RetroAchievements API. Here's how to use it effectively:

šŸš€ Quick Start

1. Get Your Credentials

First, you'll need:

  • Your RetroAchievements username
  • Your web API key (found in your profile settings on retroachievements.org)

2. Basic Setup

bash
# Build the CLI tool
swift build

# Test the help system
swift run ra-cli --help

šŸ“‹ Usage Examples

Basic Profile Information

bash
# View your profile (default command)
swift run ra-cli -u your_username -k your_api_key

# Or explicitly specify the profile command
swift run ra-cli -u your_username -k your_api_key -c profile

Example Output:

šŸ” Validating credentials...
āœ… Credentials validated successfully!

šŸ‘¤ USER PROFILE
ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•
šŸŽ® Username: MaxMilyin
šŸ“… Member Since: 2020-01-15 10:30:00
šŸ† Total Points: 125,847
šŸŽÆ Softcore Points: 45,230
šŸ’Ž True Points: 138,592
šŸŽ® Currently: Playing Super Mario Bros. (NES)
šŸ’­ Motto: "Gotta catch 'em all... achievements!"
šŸ‘Øā€šŸ’» Contributions: 234
šŸ”§ Permissions Level: 1

User Awards and Achievements

bash
# View detailed awards information
swift run ra-cli -u your_username -k your_api_key -c awards

Example Output:

šŸ… USER AWARDS
ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•
šŸ† Total Awards: 87
šŸ‘‘ Mastery Awards: 12
šŸŽÆ Completion Awards: 23
šŸ’Ŗ Hardcore Beat Awards: 8
šŸ˜Œ Softcore Beat Awards: 15
šŸŽŖ Event Awards: 2
šŸŒŸ Site Awards: 27

šŸ“‹ Recent Awards:
   1. Super Mario Bros. Mastery (Game Mastery) - 2023-12-15 14:22:00
   2. Speed Demon (Site Award) - 2023-12-10 09:15:00
   3. Zelda Completion (Game Completion) - 2023-12-08 20:45:00
   ...

Social Connections

bash
# View social connections (following/followers)
swift run ra-cli -u your_username -k your_api_key -c social

Example Output:

šŸ‘„ SOCIAL CONNECTIONS
ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•
šŸ“¤ Following 15 users:
   1. RetroGamer123 - 95,230 points
   2. AchievementHunter - 145,670 points
   3. SpeedRunner99 - 87,421 points
   ...

šŸ“„ 23 followers:
   1. GameCollector - 52,340 points
   2. CasualPlayer - 23,120 points
   3. RetroFan - 78,945 points
   ...

Interactive Game Exploration

bash
# Interactive game lookup
swift run ra-cli -u your_username -k your_api_key -c game

Example Session:

šŸŽ® GAME INFORMATION
ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•
Enter a game ID to explore (e.g., 1 for Super Mario Bros.): 1

šŸŽ® Game: Super Mario Bros.
šŸ•¹ Console: NES (ID: 7)
šŸ‘Øā€šŸ’» Developer: Nintendo
šŸ¢ Publisher: Nintendo
šŸŽ­ Genre: Platform
šŸ“… Released: 1985
šŸ† Total Achievements: 30
šŸ‘„ Casual Players: 15,234
šŸ’Ŗ Hardcore Players: 8,567

šŸ† Sample Achievements:
   ā€¢ World 1-1 (5 pts) - Complete World 1-1
   ā€¢ First Life (10 pts) - Get your first 1up
   ā€¢ Coin Collector (5 pts) - Collect 100 coins
   ā€¢ Fire Flower (10 pts) - Get the Fire Flower power-up
   ā€¢ World 1 Complete (25 pts) - Complete all of World 1
   ... and 25 more achievements

Interactive Achievement Exploration

bash
# Interactive achievement lookup
swift run ra-cli -u your_username -k your_api_key -c achievement

Example Session:

šŸ† ACHIEVEMENT INFORMATION
ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•ā•
Enter an achievement ID to explore: 12345

šŸ† Achievement: Speed Demon
šŸ“ Description: Complete World 1-1 in under 400 seconds
šŸ’Ž Points: 25
šŸ… True Ratio: 50
šŸ‘Øā€šŸ’» Author: RetroAchievementDev
šŸ“… Created: 2019-03-15 12:00:00
šŸ”„ Modified: 2023-01-10 15:30:00
šŸ‘„ Total Unlocks: 1,247
šŸ’Ŗ Hardcore Unlocks: 892

šŸ“‹ Recent Unlocks:
   1. SpeedRunner123 šŸ’Ŗ - 2023-12-20 14:30:00
   2. QuickGamer šŸ˜Œ - 2023-12-20 13:45:00
   3. FastPlayer šŸ’Ŗ - 2023-12-20 12:15:00
   ...

šŸŽ® From Game: Super Mario Bros. (ID: 1)
šŸ•¹ Console: NES

Complete Data Overview

bash
# Get everything at once
swift run ra-cli -u your_username -k your_api_key -c all

This command shows:

  • Complete user profile
  • Awards summary
  • Social connections
  • Suggestions for interactive exploration

šŸ”§ Environment Variables

For convenience, set up environment variables:

bash
# Set up your credentials
export RA_USERNAME=your_username
export RA_API_KEY=your_api_key

# Now you can use shorter commands
swift run ra-cli -c profile
swift run ra-cli -c awards
swift run ra-cli -c social
swift run ra-cli -c all

šŸ“Š Available Commands

CommandAliasDescription
profilepShow user profile information
awardsaShow user awards and achievements
socialsShow social connections
gamegInteractive game exploration
achievementachInteractive achievement exploration
all-Show profile, awards, and social info

šŸ›  Development & Testing

For Library Development

The CLI tool is perfect for:

  • Testing API changes during development
  • Validating credentials before integration
  • Exploring API responses to understand data structure
  • Debugging authentication issues
  • Performance testing with real API calls

For Integration Planning

Use the CLI to:

  • Understand data formats before implementing in your app
  • Test edge cases with real RetroAchievements data
  • Validate user stories with actual user data
  • Plan UI layouts based on real content lengths
  • Test error handling with invalid inputs

šŸ” Troubleshooting

Common Issues

Invalid Credentials:

āŒ Invalid credentials! Please check your username and API key.
  • Double-check your username and API key
  • Ensure you're using the web API key, not your password

Network Errors:

šŸŒ Network error: The Internet connection appears to be offline.
  • Check your internet connection
  • Verify RetroAchievements.org is accessible

Rate Limiting:

ā± Rate limit exceeded - please wait before making more requests
  • Wait a few moments before trying again
  • The API has rate limits to prevent abuse

Getting Help

bash
# Always available help
swift run ra-cli --help

# Or just
swift run ra-cli -h

šŸŽÆ Integration with Provenance

The CLI tool demonstrates exactly how to integrate PVCheevos into the Provenance app:

  1. Authentication Flow - See how credential validation works
  2. Data Structure - Understand the response formats
  3. Error Handling - Learn from the comprehensive error handling
  4. User Experience - Get ideas for presenting achievement data
  5. Performance - Test API response times with real data

This makes the CLI tool an invaluable resource for planning and implementing RetroAchievements support in Provenance! šŸŽ®