USCIS Civics Test CLI Trainer

Minimal Bash-based command-line practice for the U.S. Naturalization Civics Test.

• Uses the USCIS 2025 128-question format
• Runs on any Linux distro with Bash and coreutils
• Focuses on simple study and exam workflows

Features

• Multiple choice mode with 4 options per question
• Study mode with instant feedback
• Exam mode with scoring and weak-question tracking
• Main launcher menu with quick commands
• Optional location-based personalization via setup
• Validation script for question file integrity
• Session statistics saved to .stats.json

Project Files

uscis-test/
|- uscis.sh          # Main menu launcher
|- setup.sh          # Download and personalize civics data
|- study_quiz.sh     # Study mode
|- exam_quiz.sh      # Exam mode
|- validate.sh       # File format validator
|- civics.txt        # Canonical 128 questions (NUMBER|QUESTION|ANSWER)
|- weak.txt          # Incorrect questions from exam sessions
|- .stats.json       # Exam statistics history
|- README.md
|- CHANGELOG.md
`- ROADMAP.md

Quick Start

cd ~/uscis-test
chmod +x *.sh
./uscis.sh

Quick command mode:

./uscis.sh study
./uscis.sh exam
./uscis.sh weak
./uscis.sh stats
./uscis.sh setup

Main Menu

Run:

./uscis.sh

Options:

1. Setup (first run or location refresh)
2. Study mode
3. Exam mode
4. Review weak questions
5. View statistics
6. Exit

Study Mode

Run:

./study_quiz.sh

Behavior:

• Choose sequential or random question order
• Answer each question with 1-4
• See instant correct/incorrect feedback
• Press q to quit at any prompt

Exam Mode

Run:

./exam_quiz.sh

Behavior:

• Choose to clear or append to existing weak.txt
• Answer each question with 1-4
• Automatic score and percentage at the end
• Incorrect questions are saved to weak.txt
• Session stats are appended to .stats.json

Weak Question Workflow

Recommended:

./uscis.sh weak

This uses automatic backup/restore of civics.txt and is safer than manual copy/paste.

Manual workflow (if needed):

cp civics.txt civics.txt.backup
cp weak.txt civics.txt
./study_quiz.sh
cp civics.txt.backup civics.txt

Setup and Personalization

Run:

./setup.sh

What setup does:

• Downloads USCIS 2025 PDF and builds civics.txt
• Fetches current congressional/state data
• Updates location-sensitive questions (state, district, officials)
• Uses .cache/ with a 7-day TTL for state data

Validation

Validate canonical civics file:

./validate.sh

Validate any other pipe-delimited file:

./validate.sh weak.txt

Validation rules:

• All files: must be NUMBER|QUESTION|ANSWER
• civics.txt and civics.txt.tmp: must have exactly 128 lines and sequential numbering

Requirements

Study and exam scripts:

• Bash 4+
• coreutils (cat, wc, shuf, awk, grep)

Setup script only:

• curl
• python3
• Python packages: pypdf, pyyaml (auto-installed when possible)

Troubleshooting

Missing civics.txt:

./setup.sh

Missing shuf:

# Debian/Ubuntu
sudo apt install coreutils

# Fedora/RHEL/Rocky
sudo dnf install coreutils

# Arch
sudo pacman -S coreutils

# openSUSE
sudo zypper install coreutils

# Alpine
sudo apk add coreutils

License

MIT License. See LICENSE.