Starred

English | 简体中文

Create and maintain your own Awesome-style list from GitHub stars.

Features

• Generate a Markdown list from your starred repositories.
• Group results by language (default) or repository topics.
• Optionally sort categories alphabetically.
• Write the generated file directly to a target GitHub repository.
• Include private repositories with --private.

Installation

Requires Python 3.10+.

pip install starred

Quick Start

1. Create a GitHub token: Personal access tokens
2. Generate a README from your stars:

export GITHUB_TOKEN=<your-token>
starred --username <your-github-username> --sort > README.md

CLI Usage

starred --help

Common options:

• --username: GitHub username (required)
• --token: GitHub token (required)
• --sort: Sort categories alphabetically
• --topic: Group by topic instead of language
• --topic_limit: Topic popularity threshold (default: 500)
• --repository: Target repository name to update/create
• --filename: Target file name in the repository (default: README.md)
• --message: Commit message used when updating a file
• --private: Include private repositories

Update a Repository Directly

This command creates the repository if it does not exist, then updates README.md in that repository.

export GITHUB_TOKEN=<your-token>
starred --username <your-github-username> --repository awesome-stars --sort

Example repository:

• maguowei/awesome-stars

Use awesome-stars as a Template

The easiest setup is using maguowei/awesome-stars as your template repository. It includes a scheduled GitHub Actions workflow for automatic updates.

1. Click Create a new repository from awesome-stars.

1. Configure workflow token permissions: Set GITHUB_TOKEN permissions

Set permissions to Read and write permissions, then click Save.

1. Run the workflow once manually by clicking Run workflow.

1. Customize the schedule in: .github/workflows/schedules.yml#L5

Who Uses starred?

• Code search: Generated by starred
• Topic pages:
  • starred
  • awesome-stars

Development

uv sync --dev
uv run starred --help

Install from source tarball:

uv build
pip install dist/starred-<version>.tar.gz