Package: girok
✏️ Girok - The most powerful CLI task managerWho said you cannot have a beautiful UI on terminal?(p.s. No one said it to me)💥 IntroductionGirok, which means "to record" in Korean, is apowerful terminal-based task managerwhich provides a multitude of scheduling operations that can be done in less than 10 seconds. It also supportsbeautiful and responsive calendar GUIin which you can move around with VIM key bindings.💫 Highlighted FeaturesInfinite recursive sub-categories with automatic assigned colorsA beautiful and responsive calendar TUI(Termina User Interface)Add/Query a task super fast with a variety of date options💬 RemarksGirok works fluently withMacOSandLinuxusers. It also works withWindowsbut 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 togirokserver.🤖 Version0.2.3is released now!Guest mode- You can choose to log in asguest modeto save your data locally.Currently, local data are not synchronized with the server. Synchronization with the server will be added in the upcoming release.Upgrade withpip install girok --upgrade📖 Table of Contents🚀 Installation🔥 Get Started !🪟 0. Fancier UIContribute your background image!🙏 1. help command⚙️ 2. Guest mode / User mode2.1 Guest mode2.2 User mode2.3modecommand🔒 3. Register🔓 4. Login / Logout📚 5. Category commands5.1.showcat5.2.addcat5.3.mvcat5.4.rmcat5.5.rncat📕 6. Task Commands6.1.addtask6.2.showtask6.3.done6.4.chdate6.5.chpri6.6.chtag6.8.chname6.9.showtag📅 7. Calendar Commands7.1 Calendar Key Bindings7.2 Calendar Demonstrations🚒 Report Bugs😭 Uninstall💌 Contributions🚀 InstallationGirok supports all operating systems including Linux, MacOS, Windows.However, it works well on Unix-based shells such asbash,zsh,fish,wsl, etc.Some shells likepowershellmight break some UIs.Make sure you have Python>=3.9version installed.To install,pipinstallgirokNow you have installedgirokon your machine. To make sure that it works, enter the following.girok--helpNow, let's dive into Girok!🔥 Get Started🪟 0. Fancier UIIf you're a mac user (or other device supporting terminal transparency),enhance your UI by setting up a (dark theme) background for your mac desktopandmake it transparent!My settings are54 %transparency20 %opacityThe photo used in the demo:dark-chinese-doorIf 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.defaultswritecom.apple.finderCreateDesktop-boolfalsekillallFinderTo get back the icons, enterdefaultswritecom.apple.finderCreateDesktop-booltrue;killallFinderAs I just found out about this transparency (and I'm lazy), I'll leave the below demonstrations as before. I'll update later.. :)Contribute your favorite background images!If you think your background image is awesome, you can contribute by sharing it with other people! Please visit thedetailed guide.🙏 1. Help commandIn order to seeall the commandsofGirok, entergirok --helpin your terminal.In order to see the details of each command, enter the following in your terminal.girok <command> --helpFor example, if you entergirok addtask --helpthen you'll see the following help message🔒 3. RegisterTo register a new account enter the following in your terminal.girokregisterEnter your email address to receive the verificaiton codeCheck your email inbox and enter the verification code. If you can't find it, check junk email.Finally enter your password to register. Note that password must be at least7 characterslong and contain at least onelowercase, oneuppercase, and onespecial character(@,#,$,%,*,!)[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.🔓 4. Login and LogoutIn order to login,girokloginNow you're ready to use all the features!📚 5. Category CommandsYou can pre-definecategoriessuch asSchool,LifeandCareerwith automatically assigned category color.Girok supportsinfinite 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.5.1colorscommandYou can check out all the category colors with,girokcolorsYou can manually assign or update category color with the pre-defined color names.5.1showcatcommandIn order to see all the categories you have created, enter the following command.girokshowcat5.2addcatcommandaddtaskcommand takes a single argumentcategory full path.In order to add a new category, enter the following command.girokaddcat<targetpath>The<target path>is thefull path including the new category name. For example, if you want to add atopmost categorynamedCareer, then entergirokaddcatCareerThen, 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 theFULL PATHstarting from the topmost category delimited by/, ending with the new category name.For example, if you want to create a new category namedResumeunder the previously createdCareercategory, enter the following command.girokaddcatCareer/ResumeThen, you'll seeResumeis created underCareer.In this way, you can create as many categories and sub-categories as you want!5.3mvcatcommandNow you might want to move a category under another category.In order to move acategory A(recursively all its sub-categories) undercategory B, enter the following command.girokmvcat<fullpathofA><fullpathofB>For example, if you want to move the wholeCareercategory underDev/Network(for some weird reason), enter the following command.girokmvcatCareerDev/NetworkIf you want to move a category to theroot category, then pass/as the second argument. Let's moveDev/Network/Careerback to the topmost category.girokmvcatDev/Network/Career/5.4rmcatcommandOf course, you want to delete a category. In that case, enter the following command.girokrmcat<fullpathofcategory>Let's add a dummy category namedDummyunderDevthen remove it.As you already know, entergirokaddcatCareer/DummyNow, 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!girokrmcatCareer/DummyThen, you'll be asked to confirm the deletion. Entery.5.5upcatcommandYou can update category information bygirokupcat-c<color>-n<name>Note that the color must be one of the pre-defined colors fromgirok colorscommand.Great job! Now let's move on to the task commands.📕 6. Task commandsGirokprovides 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.6.1addtaskcommandgirokaddtask<taskname>[Oneofdeadlinedateoptions][-c|--category<categorypath>][-p|--priority<priority>][-t|--time<deadlinetime>][-T|--tag<tagname>]girokaddtask<taskname>-d<startdateoption>6.1.1addtaskrules<task name>(Argument /Required)If the task name has no space you can omit double quotes"". If it does, enclose it double quotes""-d | --date <date>@<time>(Option /Required)Start date and time (or deadline if end date is not present)ex)-d 5/18@17:50,-d 2025/8/15,-d tmr@17:30, ...The datetime value consists of<date>and<time>, concatenated by@. Thetimeportion can be ommitted.Allowed<date>valuesExplicit date:-d 2024/5/19Specify an exact date delimited by/. You can enter the full date in the form ofyyyy/mm/dd. Or, you can omit the year likemm/ddthen the deadline year will be set to the current year.You don't have to enter the exact form filled with0s. If the month is May, then just enter5/23or05/23.This week:-d t1Sometimes, you're not aware of the exact date. If the date is some weekday of this week, you can just passt{1-7}referrting to this monday to this sunday (monday indexed as1).For example, if the deadline is this friday, entergirok addtask "dummy" -d t5Next week:-d n1Similar to the above but referring tonext week.AfterNdays:-d a10Sometimes, you process the deadline in your mind like "it's due 5 days later".In this case, pass the number of days a task is due after.For example, if the deadline is 5 days later, entergirok addtask "dummy" -d a5Today:-d tdy|todayTomorrow:-d tmr|tomorrowAllowed<time>formatex)07:50,23:59You can also set the specific deadline time.You must provide the full time format in24 hour scalesuch as07:23or21:59.In summary, if you want to specify the full date as well as the time, you can do so bygirok addtask "Submit assignment" -d tmr@23:59-e | --end <date>@<time>(Option,Optional)If your task is spanning on multiple days, you can also specify the end dateThe format is the same as-doption.`-r | --repetition <daily | weekly | monthly | yearly>You can also specify a recurring task using-roption.The repetition type must be one ofdaily,weekly,monthly,yearly.Only single-day taskcan be recurring. Recall that we have two datetime options:-d,-eand each consists of "date" and "time". Let's define themstart date,start time,end date,end time. Then, only the following combinations(single-day task) are allowed for repetition.start dateonlystart date,start timeonlystart date,start time,end date,end timeonly, andstart date == end dateThe start day of the recurring event is automatically set to thestart dateyou specified with-doption.-c | --category <category full path>(Option /Optional)Your tasks might belong to a specific category you have previously defined.Provide thefull category path.For example, if your task belongs toCareer/Resume, then entergirok addtask "dummy task 1" -d tmr -c Career/Resume.If you specify a category, then the task color will be automatically linked to that category's color.If no category is provided, the task will belong toNo Categorycategory.-p | --priority <low | medium | high>(Option,Optional)You can set the priority of a task so that you can filter out by priority when you query your tasks.For example, to set the priority of a task aslow, entergirok addtask "dummy task 1" -d tmr -p low.-t | --tag <tag name>(Option,Optional)You can set thetagof a task such asassignmentandmeeting. With tags, you can more efficiently query your tasks with different types.Unlike category, tag doesn't allow nested tags and you don't have to pre-define them.For example, if you want to set the tag of a task asassignment, entergirok addtask "assignment 4" -d 4/24 -t assignment-m | --memo <memo>You can also add a memo for your task with-moptionex)girok addtask "Meeting with Jason" -d tmr -m "don't forget to prepare the documents"In summary, keep the following rules in mind.Always providetask nameand-doption.Although not required, it's better to providecategoryto manage your tasks more effectively.Other options are up to you.For example, the following command is a typical command that I use on everyday basis.girokaddtask"Implement tag filtering feature"-cDev/Girok-dn3-phighIt looks quite complicated, but you'll get used to it quickly after playing out a little bit.6.1.2addtaskdemonstrationNow let's play around withaddtaskcommand.Suppose our category list isIn the demonstration, I will add several tasks and show how it works.Let's add a task namedgo over resume againwhose category isCareer/Resumeand I will do it bynext thursday. This is a quite important task, so I will assign thepriorityhigh.girokaddtask"go over resume again"-cCareer/Resume-dn4-phighNow I'll add another task namedMidterm examwith the categoryHKU/COMP3234and it's a 3-day exam from4/18 09:30 AMto4/20 10:00. Let's also addexamtag and memo.girokaddtask"Midterm exam"-cHKU/COMP3234-d4/18@09:30-e4/20@10:00-texam-m"Do not forget to bring cheatsheet"Lastly, I'll add a task namedGym dayand I will go every day at 7 AM in the morning.girokaddtask"Gym day"-dtmr@07:00-rdaily6.2showtaskcommand.girokshowtask[--tree]Deadlinedateoptions][-c|--category<categorypath>][-p|--priority<priority>][-T|--tag<tagname>]Girok provides powerful commands to effectively query your schedule with many different options. You can filter tasks by category, priority, deadline, and tag.6.2.1 Table view vs List viewYou can typegirok showtaskcommand with no parameter. The default view of the command istable view.Note that I've added some more tasks to make the visualization rich.girokshowtaskBy default, all tasks will be shown in a nice table format.If you want to view your tasks in a tree view, then provide--treeflag.girokshowtask--tree6.2.2 Filter by categoryTo query tasks under a specific category, use the following command,girokshowtask-c<categorypath>For example, to query tasks only for theHKUcategory. Enter the following command.girokshowtask-cHKUorgirokshowtask-cHKU--tree# tree view6.2.3 Filter by date optionsYou can query your tasks filtering by many different date options. Notice that all the options forshowtaskcommand areOPTIONAL.-e | --exact <yyyy/mm/dd | mm/dd>To view tasks due to a specific day, provide the exact date after the flag-d | --day <# days>To view tasks duewithinndays, provide the number of daysnafter the flag-w | --week <# days>To view tasks duewithinnweeks, provide the number of weeksnafter the flag-m | --month <# days>To view tasks duewithinnmonths, provide the number of monthsnafter the flag--tdyTo view tasks due today.--tmrTo view tasks due within tomorrow (today && tomorrow)--tw,--nwTo view tasks due within this week and next week, respectively--tm,--nmTo view tasks due within this month and next month, respectively-t1 ~ -t7 | --thismon ~ --thissunTo view tasks dueexactlythe weekday of this weekMonday is indexed as1-n1 ~ -n7 | --nextmon ~ --nextsunTo view tasks dueexactlythe weekday of next weekMonday is indexed as1-u | --urgentTo view urgent tasks that are within3 daysby default6.2.4 Filter by prioritygirokshowtask-p<priority(1~5)>To view tasks with a specific priority, provide-poption followed by the priority number between1and5.For example, to view tasks with priority 5, enter the following commandgirokshowtask-p5To view tasks with priority 5, but withtree view, enter the following command.girokshowtask-p5--tree6.2.5 Filter by taggirok showtask [-T | --tag <tag name>]6.3donecommandTo complete(delete) a task, provide thedonecommand followed by the task ID.Optionally, you can pass-yor--yesflag if you don't want to see the confirmation message.girok done <task ID> [-y | --yes][IMPORTANT]TheTASK IDis the IDs you can see when you performshowtaskoperations. Note that theONLY the Task IDs of the LATEST showtask operation are valid. In other words, if you consecutively typegirok showtaskandgirok showtask -p 5but try to delete a task with the task IDs shown in the table of the firstgirok showtaskcommand, you might delete an unexpected task!!For example, suppose you entergirok showtaskcommand.If you completed the taskMigrate DB to RDSunderDev/Girokcategory, provide the task ID at the leftmost column.girokdone5Notice that the task is now striked out.6.4chdatecommandTo change the date of an existing task, enter the following command.girokchdate<taskID><Deadlineoptions>The deadline option group is the same asaddtaskcommand.6.5chpricommandTo change the priority of an existing task, enter the following command.girokchpri<taskID><priority(1~5)>6.6chtagcommandTo change the tag of an existing task, enter the following command.girokchtag<taskID><tagname>6.7chnamecommandTo change the name of an existing task, enter the following command.girokchname<taskID><newtasknameenclosedwith"">6.8showtagcommandTo view all the tags you have created so far, enter the following command.girokshowtag📅 7. Calendar CommandsThe beauty ofGirokis thebeautiful and responsive full calendar GUI.To fire up the calendar, enter the following commandgirok calThen you'll be prompted to the calendar GUI.girokcaloffers 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 thesidebar.7.1 Calendar Key BindingsUpongirok calcommand, the starting"focus"is thecategory tree.Select a category/tago- select the current category/tagMove insidecategory treeortag treej- downk- upMove fromcategory treetotag treectrl + jMove fromtag treeto *_category treectrl + kMoving fromcategory treeortag treetocalendareMoving fromcalendarto backsidebar(to category tree by default)wMove inside thecalendarh- leftj- downk- upl- rightSelect acalendar cell(day) to view detailso- select the currently focused calendar cellNext monthiPrevious monthuDirect to the current monthyToggle side barfClose calendarq7.2 Calendar DemonstrationsWhen 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 selectHKUcategory by pressing alphabetokey.Notice that only the tasks with the yellow dots (HKU category color) are shown.Now let's selectAll Categoriesand change our focus from thecategory treeto thetag treeby pressingctrl+jkey. Then, selectexamtag.Yay! I don't have any exams this month.But.. do I have exams next month? To check it out, let's pressito move to the next month.Lastly, let's pressfto close the sidebar to have make the calendar bigger.Great job! Now, it's time to explore all the features ofGirokon your own!!🚒 Report BugsThe first version ofGirokwas 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 raisingissuesthen I will respond and update as soon as possible!!😭 UninstallI'm sorry that there's no way to uninstall this package.Just kidding. Enterpip uninstall girokin your terminal. Bye..😢💌 Contribute to the projectIf 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 firstopen an issuewith thefeaturetag (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.p.s) I'm currently looking for team members to join me to build a web/app version of Girok. Also, if you're a strong Python programmer, you can join me scale it up to build a more robust "Girok"! Drop me an email tochangjin9792@gmail.comif you're interested.