Skip to main content
This guide will help you get started with the list-updater CLI tool quickly.

​
Basic Usage

The CLI uses a grouped command structure: 
uv run python main.py <group> <command> [options]
The tool is organized into three main command groups:
  • readme - Update README files from listings data
  • contribution - Process contribution issues from GitHub
  • listings - Manage, search, and validate internship listings

​
Getting Help

1

View all available commands

uv run python main.py --help
This shows all command groups and their descriptions.
2

View commands in a specific group

uv run python main.py listings --help
This shows all commands available in the listings group.
3

View help for a specific command

uv run python main.py listings search --help
This shows detailed help for the search command, including all options and flags.

​
Common Examples

Here are some common tasks you can perform with the CLI:

​
Update README Files

Update all README files from the listings.json data: 
uv run python main.py readme update
This command:
  • Generates the main README with active listings
  • Creates README-Inactive.md with inactive listings
  • Creates README-Off-Season.md with off-season positions
  • Validates the data schema before updating

​
Show Statistics

Get a summary of all internship listings: 
uv run python main.py listings stats
This displays:
  • Total listings count
  • Active vs inactive breakdown
  • Category distribution
  • Top companies by listing count
  • Sponsorship breakdown
For JSON output (useful for scripting): 
uv run python main.py listings stats --json

​
Search Listings

Search for internships by company: 
uv run python main.py listings search --company "Google"
Search for active remote positions: 
uv run python main.py listings search --location "Remote" --active
Search by category with custom limit: 
uv run python main.py listings search --category "Software" --active --limit 50

​
Validate Data

Check for issues in listings.json: 
uv run python main.py listings validate
This checks for:
  • Missing required fields
  • Duplicate URLs or IDs
  • Invalid categories
  • Schema violations
  • Blocked companies
To automatically fix issues: 
uv run python main.py listings validate --fix

​
View Recent Changes

See what changed in the last commit: 
uv run python main.py listings diff
See changes since a specific date: 
uv run python main.py listings diff --since "2025-01-01"
See changes since a specific commit: 
uv run python main.py listings diff --commit abc123

​
What’s Next

Now that you know the basics, explore the detailed documentation:

Build docs developers (and LLMs) love

Get started for freeTalk to us