A powerful and beautiful CLI scheduler
(p.s. No one said it to me)
Girok, which means "to record" in Korean, is a powerful terminal-based task manager which provides a multitude of scheduling operations that can be done in less than 10 seconds. It also supports beautiful and responsive calendar GUI in which you can move around with VIM key bindings.
Girok works fluently with MacOS
and Linux
users. It also works with Windows
but some features and UIs might break.
If you find it useful, consider supporting to help the development process! As I'm running the server with my own expense now, your help will make the service much more stable and fast!
If you want to see the server source code, go to girokserver.
0.2.5
is released now!pip install girok --upgrade
Girok supports all operating systems including Linux, MacOS, Windows.
However, it works well on Unix-based shells such as bash
, zsh
, fish
, wsl
, etc.
Some shells like powershell
might break some UIs.
Make sure you have Python >=3.9
version installed.
To install,
pip install girok
Now you have installed girok
on your machine. To make sure that it works, enter the following.
girok --help
Now, let's dive into Girok!
If you're a mac user (or other device supporting terminal transparency), enhance your UI by setting up a (dark theme) background for your mac desktop and make it transparent!
My settings are
54 %
transparency20 %
opacityThe photo used in the demo: dark-chinese-door
If you're an ITerm 2 user, for some weird reasons, the calendar doesn't apply the transparency. Please let me know if anyone figures this out to make it transparent for ITerm2! Please use the default mac terminal to see the change for the calendar.
If you have overflowing icons in the background, it looks bad. To hide the background icons(not deleting), enter the following command.
defaults write com.apple.finder CreateDesktop -bool false
killall Finder
To get back the icons, enter
defaults write com.apple.finder CreateDesktop -bool true; killall Finder
As I just found out about this transparency (and I'm lazy), I'll leave the below demonstrations as before. I'll update later.. :)
If you think your background image is awesome, you can contribute by sharing it with other people! Please visit the detailed guide.
In order to see all the commands of Girok, enter girok --help
in your terminal.
In order to see the details of each command, enter the following in your terminal.
girok <command> --help
For example, if you enter
girok addtask --help
then you'll see the following help message
To register a new account enter the following in your terminal.
girok register
@
, #
, $
, %
, *
, !
)[WARNING] Girok doesn't require you to enter your email service's password. You can type any password as input.
Congratulations! Now let's go ahead and login to our account.
In order to login,
girok login
Now you're ready to use all the features!
You can pre-define categories such as School
, Life
and Career
with automatically assigned category color.
Girok supports infinite recursive subcategories. All the subcategories will be assigned with the color of its topmost parent category.
Later on, you can link tasks to these categories.
colors
command You can check out all the category colors with,
girok colors
You can manually assign or update category color with the pre-defined color names.
showcat
command In order to see all the categories you have created, enter the following command.
girok showcat
addcat
command addtask
command takes a single argument category full path
.
In order to add a new category, enter the following command.
girok addcat <target path>
The <target path>
is the full path including the new category name. For example, if you want to add a topmost category named Career
, then enter
girok addcat Career
Then, you'll see the category tree with the newly created category being highlighted.
In order to nest a sub-category under a previously defined category, pass the FULL PATH starting from the topmost category delimited by /
, ending with the new category name.
For example, if you want to create a new category named Resume
under the previously created Career
category, enter the following command.
girok addcat Career/Resume
Then, you'll see Resume
is created under Career
.
In this way, you can create as many categories and sub-categories as you want!
mvcat
command Now you might want to move a category under another category.
In order to move a category A
(recursively all its sub-categories) under category B
, enter the following command.
girok mvcat <full path of A> <full path of B>
For example, if you want to move the whole Career
category under Dev/Network
(for some weird reason), enter the following command.
girok mvcat Career Dev/Network
If you want to move a category to the root category
, then pass /
as the second argument. Let's move Dev/Network/Career
back to the topmost category.
girok mvcat Dev/Network/Career /
rmcat
command Of course, you want to delete a category. In that case, enter the following command.
girok rmcat <full path of category>
Let's add a dummy category named Dummy
under Dev
then remove it.
As you already know, enter
girok addcat Career/Dummy
Now, let's delete it with the following command.
[WARNING] If you delete a category, all its sub-categories and tasks will be DELETED. I'll consider adding an option for users to preserve all the orphan tasks in the future. Please let me know in the issue if you need this feature!
girok rmcat Career/Dummy
Then, you'll be asked to confirm the deletion. Enter y
.
upcat
command You can update category information by
girok upcat -c <color> -n <name>
Note that the color must be one of the pre-defined colors from girok colors
command.
Great job! Now let's move on to the task commands.
Girok provides powerful task scheduling operations. You can perform different operations that would've taken a long time in other schedulers like Notion and Google Calendar in less than 10 seconds.
addtask
command girok addtask <task name> [One of deadline date options] [-c | --category <category path>] [-p | --priority <priority>] [-t | --time <deadline time>] [-T | --tag <tag name>]
girok addtask <task name> -d <start date option>
addtask
rules<task name>
(Argument / Required)
""
. If it does, enclose it double quotes ""
-d | --date <date>@<time>
(Option / Required)
-d 5/18@17:50
, -d 2025/8/15
, -d tmr@17:30
, ...<date>
and <time>
, concatenated by @
. The time
portion can be ommitted.<date>
values
-d 2024/5/19
/
. You can enter the full date in the form of yyyy/mm/dd
. Or, you can omit the year like mm/dd
then the deadline year will be set to the current year.0
s. If the month is May, then just enter 5/23
or 05/23
.-d t1
t{1-7}
referrting to this monday to this sunday (monday indexed as 1
).girok addtask "dummy" -d t5
-d n1
N
days: -d a10
girok addtask "dummy" -d a5
-d tdy|today
-d tmr|tomorrow
<time>
format
07:50
, 23:59
07:23
or 21:59
.girok addtask "Submit assignment" -d tmr@23:59
-e | --end <date>@<time>
(Option, Optional)
-d
option.-r | --repetition <daily | weekly | monthly | yearly>
(Option / Optional)
-r
option.daily
, weekly
, monthly
, yearly
.-d
, -e
and each consists of "date" and "time". Let's define them start date
, start time
, end date
, end time
. Then, only the following combinations(single-day task) are allowed for repetition.
start date
onlystart date
, start time
onlystart date
, start time
, end date
, end time
only, and start date == end date
start date
you specified with -d
option.-c | --category <category full path>
(Option / Optional)
Career/Resume
, then enter girok addtask "dummy task 1" -d tmr -c Career/Resume
.No Category
category.-p | --priority <low | medium | high>
(Option, Optional)
low
, enter girok addtask "dummy task 1" -d tmr -p low
.-t | --tag <tag name>
(Option, Optional)
assignment
and meeting
. With tags, you can more efficiently query your tasks with different types.assignment
, enter girok addtask "assignment 4" -d 4/24 -t assignment
-m | --memo <memo>
-m
optiongirok addtask "Meeting with Jason" -d tmr -m "don't forget to prepare the documents"
In summary, keep the following rules in mind.
-d
option.For example, the following command is a typical command that I use on everyday basis.
girok addtask "Implement tag filtering feature" -c Dev/Girok -d n3 -p high
It looks quite complicated, but you'll get used to it quickly after playing out a little bit.
addtask
demonstrationNow let's play around with addtask
command.
Suppose our category list is
In the demonstration, I will add several tasks and show how it works.
Let's add a task named go over resume again
whose category is Career/Resume
and I will do it by next thursday
. This is a quite important task, so I will assign the priority
high.
girok addtask "go over resume again" -c Career/Resume -d n4 -p high
Now I'll add another task named Midterm exam
with the category HKU/COMP3234
and it's a 3-day exam from 4/18 09:30 AM
to 4/20 10:00
. Let's also add exam
tag and memo.
girok addtask "Midterm exam" -c HKU/COMP3234 -d 4/18@09:30 -e 4/20@10:00 -t exam -m "Do not forget to bring cheatsheet"
Lastly, I'll add a task named Gym day
and I will go every day at 7 AM in the morning.
girok addtask "Gym day" -d tmr@07:00 -r daily
showtask
command. girok showtask [--tree] Deadline date options] [-c | --category <category path>] [-p | --priority <priority>] [-T | --tag <tag name>]
Girok provides powerful commands to effectively query your schedule with many different options. You can filter tasks by category, priority, deadline, and tag.
You can type girok showtask
command with no parameter. The default view of the command is table view.
Note that I've added some more tasks to make the visualization rich.
girok showtask
By default, all tasks will be shown in a nice table format.
If you want to view your tasks in a tree view, then provide --tree
flag.
girok showtask --tree
You can query your tasks filtering by many different date options. Notice that all the options for showtask
command are optional.
-e | --exact <date format from addtask -d option>
-d | --day <# days>
n
days, provide the number of days n
after the flag-w | --week <# days>
n
weeks, provide the number of weeks n
after the flag-m | --month <# days>
n
months, provide the number of months n
after the flag--tdy
--tmr
--tw
, --nw
--tm
, --nm
-u | --urgent
3 days
by defaultTo query tasks under a specific category, use the following command,
girok showtask [-c | --category] <category path>
For example, to query tasks only for the HKU
category. Enter the following command.
girok showtask -c HKU
or
girok showtask -c HKU --tree # tree view
girok showtask [-p | --priority] <low | medium | high>
To view tasks with a specific priority, provide -p
option followed by the priority number between 1
and 5
.
For example, to view tasks with priority 5, enter the following command
girok showtask -p 5
girok showtask [-t | --tag] <tag name>
done
command To complete(delete) a task, provide the done
command followed by the task ID.
Optionally, you can pass -y
or --yes
flag if you don't want to see the confirmation message.
girok done <task ID> [-y | --yes]
[IMPORTANT] The TASK ID is the IDs you can see when you perform showtask
operations. Note that the ONLY the Task IDs of the LATEST showtask operation are valid. In other words, if you consecutively type girok showtask
and girok showtask -p 5
but try to delete a task with the task IDs shown in the table of the first girok showtask
command, you might delete an unexpected task!!
For example, suppose you enter girok showtask
command.
If you completed the task Hangout with Jason
, provide the task ID at the leftmost column.
girok done 3
uptask
command You can update task information with giork uptask
command.
girok chdate <taskID> -n <name> -d <start datetime> -e <end datetime> -r <repetition type> -c <category> -t <tag> -p <priority> -m <memo>
Note that the start and end datetime format are the same as the one from -d
option of addtask
command.
The beauty of Girok is the beautiful and responsive full calendar GUI.
To fire up the calendar, enter the following command
girok cal
Then you'll be prompted to the calendar GUI.
girokcal offers a beautiful but minimalistic GUI in which you can move around with (not exactly same but similar) VIM key bindings.
Notice that all the categories and tags we have created so far are linked to the sidebar.
Upon girok cal
command, the starting "focus" is the category tree.
o
- select the current category/tagj
- downk
- upctrl + j
ctrl + k
e
w
h
- leftj
- downk
- upl
- righto
- select the currently focused calendar celli
u
y
f
q
When you click on a category, then the category title will change accordingly at the left-bottom corner of the calendar. All the tasks belonging to the selected category will be shown.
Let's select HKU
category by pressing alphabet o
key.
Notice that only the tasks with the yellow dots (HKU category color) are shown.
Now let's select All Categories
and change our focus from the category tree to the tag tree by pressing ctrl+j
key. Then, select exam
tag.
Yay! I don't have any exams this month.
But.. do I have exams next month? To check it out, let's press i
to move to the next month.
Lastly, let's press f
to close the sidebar to have make the calendar bigger.
Great job! Now, it's time to explore all the features of Girok on your own!!
The first version of Girok was released just a couple days ago so you might encounter some bugs and errors.
If so, I'd greatly appreciate if you report them as raising issues
then I will respond and update as soon as possible!!
I'm sorry that there's no way to uninstall this package.
Just kidding. Enter pip uninstall girok
in your terminal. Bye..😢
If you have any new features that would make your life easier, please don't hesitate to raise issues.
If you wish to contribute to the project as a programmer, please first open an issue with the feature
tag (title prefixed with [Feat] description
) describing your suggested features. After getting approval from the maintainer, you can drop pull requests and I will review each of them carefully.