Score

Gaming toolkit for tracking scores, rankings, challenges, leaderboards, and rewards from the command line. Log entries, review history, export data, and search across all records.

Overview

Score is a versatile CLI tool for game and competition tracking. Each command logs or retrieves entries with timestamps. Pass arguments to record new data, or run a command with no arguments to view recent entries. Built-in utilities provide statistics, data export, search, and health checks.

Commands

Data Storage

• Location: ~/.local/share/score/
• Per-command logs: Each command (roll, score, rank, etc.) writes to its own <command>.log file
• History: history.log — timestamped action log recording every operation
• Export: export.<fmt> — generated export files (json, csv, txt)
• Format: YYYY-MM-DD HH:MM|value per line in each log file
• All data is plain text. No database or cloud service.

Requirements

• bash (with set -euo pipefail)
• Standard Unix utilities (date, wc, du, tail, grep, cat, head)
• No external dependencies or API keys

When to Use

1. Tracking game scores — Use score score "Player1 25pts" to log scores during a game night or tournament
2. Running leaderboards — Use score leaderboard "Player1 #1" to maintain standings, then score export csv for spreadsheets
3. Dice rolling & randomness — Log dice results with score roll "d20: 17" for tabletop RPG sessions
4. Challenge tracking — Create and track challenges between players with score challenge "speed run level 3"
5. Data analysis & export — Use score stats for summary counts, score search to find specific entries, and score export json for programmatic analysis

Examples

# Log a dice roll
score roll "d20: natural 17"
#  Output: [Score] roll: d20: natural 17
#          Saved. Total roll entries: 1

# Record a game score
score score "Alice 2500pts round-3"
#  Output: [Score] score: Alice 2500pts round-3
#          Saved. Total score entries: 1

# Update the leaderboard
score leaderboard "Alice #1, Bob #2, Charlie #3"

# View recent rolls (no argument = read mode)
score roll

# Check overall statistics
score stats
#  Output: history: 5 entries
#          roll: 3 entries
#          Total: 8 entries
#          Data size: 4.0K

# Search across all entries
score search "Alice"

# Export everything as JSON
score export json
#  Output: Exported to ~/.local/share/score/export.json (245 bytes)

# Export as CSV for spreadsheets
score export csv

# Check system health
score status
#  Output: Version: v2.0.0, Data dir, Entries count, Disk usage, Last activity

# View recent activity
score recent

How It Works

Each domain command (roll, score, rank, challenge, etc.) has dual behavior:

• With arguments: Appends a timestamped entry to <command>.log and logs the action to history.log
• Without arguments: Displays the last 20 entries from that command's log file

The stats utility aggregates entry counts across all log files. The export command converts all logs into JSON, CSV, or plain text format. The search command performs case-insensitive grep across every log file.

Tips

• Each command is its own namespace — you can track dozens of game types simultaneously
• Use recent for a quick dashboard of the last 20 actions
• Pipe export json output to jq for advanced analysis
• Override data directory: export SCORE_DIR=... (set in your environment before sourcing)

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com