___ ______ _ ____ ____ _ _
/ \ * | | /\ | | \ / | * | \ | \
\ \ | | /\ \ | |* / | | | | | |
\ \ | | /--\ \ | | \ | | | | | |
*_\./ ._| / ._\ |_| \_ \.|__. |_|_. |_|
Browse trending projects on Github from your command line $ _
pip3 install starcli
Usage: starcli [OPTIONS]
Search and query GitHub repositories
Options:
-l, --lang TEXT Language filter eg: python. (can be used
multiple times)
-S, --spoken-language TEXT Spoken Language filter eg: en for English,
zh for Chinese
-c, --created TEXT Specify repo creation date in YYYY-MM-DD,
use >date, <=date etc to be more specific.
-t, --topic TEXT Date of last push in YYYY-MM-DD (>, <, >=,
<= specifiers supported)
-p, --pushed TEXT Specify date of last push in YYYY-MM-DD, >=<
allowed
-L, --layout [list|table|grid] The output format (list, table, or grid),
default is list
-s, --stars TEXT Number of stars, default is '>=100'. eg:
'>0', '123', '<50000
-n, --num-results INTEGER The number of items in the results. Default:
7
-o, --order [desc|asc] Order of repos by stars, 'desc' or 'asc',
default: desc
--long-stats Print the actual stats number (1300 instead
of 1.3k)
-d, --date-range [day|week|month]
View stars received within time, choose
from: day, week, month. Uses GitHub trending
for fetching results, hence some other
filter options may not work.
-u, --user TEXT Filter for trending repositories by username
--auth TEXT Optionally use GitHub personal access token
in the format 'username:password'.
-P, --pager Use $PAGER to page output. (put -r in $LESS
to enable ANSI styles)
--debug Turn on debugging mode
--help Show this message and exit.
Switch layouts using --layout {list|table|grid}
, or use the short option -L
list
table
grid
All three of the layout options support clickable links for repository names. If your terminal supports links, you can directly click on the name and it will take you to the GitHub repository in your browser.
For example, you only want to find popular Python repos: using --lang
or -l
:
starcli --lang python
Here's another example starcli -l python -L grid
, which is python with grid
layout:
If you wanted to find repos in your native language, you can use
--spoken-language
or -S
:
starcli --spoken-language zh
The above command lists down repos written in Chinese.
A full list of language codes is available here
Note that (as with --date-range
) options like --topics
, --pushed
,
--created
won't take effect because -d
uses a different search mechanism to
find results.
(Recommended to be used with --created
)
The default range is >=100 stars.
Use --stars
or -s
to specify what you want, for example, if you want to find
repos that has more than 100 stars, you can use:
starcli -s '>100'
Note that if you do something like >1000
not many repos can have more than
1000 and is created within around 200 days (which is the default for
--created
), to specify date of creation, use --created
, see below.
You can view the number of stars a repo received today, this week or this month
by using the --date-range
or -d
option:
starcli -d this-week -L table
This command will also display the number of stars received for each repo this week in the form of a table.
-d
uses GitHub Trending search for repositories, hence options --topic
,
--pushed
, --created
won't take effect.
--created
/-c
accepts a date in ISO8601 format: yyyy-mm-dd
For example, for repos created on 1st January 2014, use:
starcli --created 2014-01-01
To search for repos that are created on or after 1st January 2014, use:
starcli --created '>=2014-01-01'
This option lets you filter by topics. You can use --topics
or -t
to include
a topic in search.
This option can be used multiple times.
starcli -l python -d 2020-07-06 -t deep-learning -t pytorch
Use --pushed
/-p
when you want to find popular repos that are last updated on
a given date, say 2020-01-01 for 1st of Jan 2020:
starcli -p 2020-01-01
You can also prefix the value with ">=<" like:
starcli -p '>=2020-01-01'
This is find repos that have last pushed after or on January the 1st, 2020.
Read more about the >=< syntax on GitHub Docs.
Recommended to be used with --stars
and/or --date-created
.
Finding trending projects by GitHub username is supported too. Use --user
or
-u
to do so.
Just provide a valid GitHub username after it, like:
starcli -u torvalds
starcli -u gvanrossum
You can use --date-range
or -d
and specify today, this-week, or this-month,
so that GitHub Trending search function will be used to find popular repos and
tell you how much stars are gained this day/week/month depending on the option
you used.
starcli -d this-week
Note that (like --spoken-language
) options like --topics
, --pushed
,
--created
won't take effect because -d
uses a different search mechanism to
find results.
Don't like the default 7? You can change it to something else, using
--limit-results
or -r
followed by an integer:
starcli -r 2
The above will only give you two repos. This is useful if you want to put it in
your .bashrc
, .zshrc
, or fish_greeting
function.
Just add starcli -r 3 -L grid
in there, and every time you open your terminal,
you will find 3 trending repos printed neatly in a grid format, great way to
start your day (a bit like the Hacker Tab
Extension).
Result output can be displayed through your OS pager using the --pager
/-p
flag.
If you're using less, add R
to your LESS
environment variable so colors and
styling can be displayed correctly.
Rate limit may be hit if starcli sends many repeated requests to GitHub within a short perod of time.
To avoid this, provide an authentication token using --auth
:
starcli --auth 'username:token'
Read more about authentication tokens on GitHub Docs
For contributing guidelines and how to set up your development environment,
please read
CONTRIBUTING.md
.
Remember that all contributions to this project should follow its CODE OF
CONDUCT.
rich
(with click and colorama)requests
Thanks goes to all of these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
This project was forked from githunt
(python) and its initial intention was
to rewrite that project to use Rich instead of colorama + tabulate, but now it
has so much more features than before, thanks to everyone's contributions 🙌