A command-line interface to interact with Advent of Code puzzles, built in Ruby.
- Download puzzles as markdown and raw inputs directly from the command line
- Submit answers for puzzles and receive feedback
- Track progress through your calendar file which is automatically updated as you progress
- View data about how you answer puzzles, for example your previous attempts, how long it takes to solve a puzzle successfully and how many attempts it took you
- Inputs and puzzles are cached locally to prevent strain on AoC server
- Automatic git initialisation
- Hot keys to open solution megathreads in Reddit if you get stuck
- Support for multiple AoC accounts by use of session-key aliases
- If you are having any issues with the calendar table, run
aoc -rin your year directory to update and refresh your directory
- Bug fix for text-only answers
- Year refresh now creates the calendar table if it does not exist
- Update terminal-table version requirements
- Add version flag
- Day subdir prefix functionality
- Duplicate incorrect attempts prevented
- Calendar progress tables
- Quick-print calendar from any directory
- Configuration expansion
- Auto-generate config file
- Turn on/off creation of calendar file
- Turn on/off leaderboard stats in calendar file
- Basic git integration
- Better key validation
- Better default alias handling
- General bug fixes
- aoc-cli uses Pandoc, make sure it is installed
- Homebrew users can run
brew install pandoc - Mac OS users need to make sure developer tools is installed (thank you yspreen)
Install gem
$ gem install aoc_cliManual install
$ git clone "https://github.com/apexatoll/aoc-cli"
$ cd aoc-cli
$ rake build installTo use aoc-cli you must first find and store your unique session cookie. To find this, log into the Advent of Code website as usual and load any page.
Open developer tools and open the network tab. Refresh the page and you should see a file that contains your session cookie.
It will contain a field that looks something like:
cookie: session=HEXADECIMAL_STRING
This is unique to your account, and allows aoc-cli to interact with the AoC server - do not share this!
- Copy the session key (including "session=") to the clipboard and open your terminal
- Run the following command
aoc -k $your_key
- aoc-cli stores this key under the alias 'main' if no custom alias is specified
- To store the key under a different alias use the
-uor--userflags followed by the desired alias. - Session keys are stored in the aoc config file located at
~/.config/aoc-cli/aoc.rc.
Keys can also be stored manually in your config file using the format:
cookie=>$alias=>$key
For example:
cookie=>account2=>session=123abc
aoc-cli allows for multiple keys to be stored within the config file.
To see which alias is currently default run aoc -U or aoc --default
- You can update the default alias by running
aoc -U $new_default_aliasBy default, aoc-cli will determine the default alias in the following order of precedence
- The alias explicitly set by
default=>$aliasin your config file or by using the-Ucommand - The
mainalias (if it exists) - The first key in your config file
Say for example you wanted to learn a new language and decided to try out Advent of Code from scratch to get stuck in. You could set up a new account and grab the session key, which for example is abc123
Lets use Ruby as our new language. You could then store this new key under the alias ruby
aoc -k session=abc123 -u rubyYou could then set ruby as your default alias so that you do not have to specify -u ruby explicitly when initialising a year directory each time
aoc -U rubyAlternatively you could add the following line to your config file
default=>ruby
aoc-cli is designed to run in a file-tree generated by the interface.
There are two types of directories
- Year directories
- These contain your calendar and all day subdirectories
- Day subdirectories
- These contain the puzzles, your input and your code
To begin using the cli you must first initialise the year directory.
aoc-cli will intialise within your current working directory, so first create a directory for the year and change directory into it
mkdir 2020
cd 2020Initialise the year directory using the command
aoc -y 2020This will set the session key for the year directory to the default alias. To use a different alias run:
aoc -y 2020 -u $aliasThis command will create necessary metafiles, download the year calendar and fill it with your current progress (if any). This is stored in a markdown file in the year directory.
By default, your stats in the leaderboard are also added to this file. This can be changed - see Configuration
aoc-cli can also intialise a git directory on year intialisation (turned off by default)
You can now get day data!
To fetch puzzle instructions and inputs you can run the following command from within the year directory
aoc -d $day_numberThis command performs the following actions
- Creates a day subdirectory
- Fetches the puzzle as markdown
- Fetches raw puzzle input
- The time you downloaded the puzzle is logged
All puzzles and inputs are cached in aoc-cli on a per-user basis. This means that if you have previously initialised this day under the same alias before, your puzzle and input will be transferred from the cache locally rather than downloading from the aoc server.
NB: if you wish to add a prefix to your day subdirectory names, you can add day_dir_prefix=>$prefix to your config file
From the day subdirectory you can attempt to solve puzzles by running the command
aoc -s $answerYou will then receive one of four responses
- The answer is correct
- The answer is not correct
- You have already tried this incorrect answer
- You have time to wait before submitting an answer
If your answer is correct, aoc-cli will automatically update the puzzle instructions and your calendar file. Additionally aoc-cli will calculate how long and how many attempts it took to solve the puzzle (see the Tables section)
Incorrect attempts will be logged along with any hint as to whether your answer was too high or too low.
Trying to answer with the same incorrect answer for the second time will throw an error
If you have sent multiple incorrect attempts AoC will ask you to wait before trying again - be patient!
aoc-cli uses a local database to store information about your progress with puzzles. This tracks data on:
- Your attempts
- Your stats
- Your progress in the year
This data can be visualised in terminal-friendly tables
Previous attempts for a puzzle can be viewed from the day directory by the use of the command
aoc -a (--attempts)To specify which attempts to show from outside the day subdirectory you can use the command
aoc -a -u $user_alias -Y $year -D $day -p $partData is shown in a formatted table with incorrect attempts shown in red and the correct answer in green.
You need to specify the part explicitly using -p or --part to view attempts for puzzles that are already completed
aoc-cli also tracks data related to your performance in puzzles, namely:
- The time taken to complete a puzzle
- How many attempts it took
To view stats on a specific puzzle run the following command from the day subdirectory
aoc -S (--stats)To view the stats for the year as a whole run the same command from the year directory.
Flags can be also be added manually for showing data for other users, years and days in a similar way to that of the attempts table
To view your progress in the year you can run the commands
aoc -c (--simple-cal)This will print a simple table showing your stars for each day. This is created on year initialisation and updated as you complete puzzles
If you have calendar_file set to true in your configuration (default setting), you can quickly print your calendar file by using the command
aoc -C (--fancy-cal)You can run the command aoc -R (--reddit) from the day subdirectory, or by manual flags to open the solution megathread for the specified day in Reddit
If one is installed, aoc-cli will default to opening the thread within a reddit-cli such as rtv or ttrv.
If one isn't found however, the thread will be opened within your default browser.
To open the reddit megathread in your browser, regardless of whether you have a CLI installed, run aoc -B (--browser)
aoc-cli currently supports basic integration with git. At present aoc-cli can:
- Initialise a git directory on year initialisation
- Create a gitignore file
- Configurable to add markdown and metafiles by default
These settings can be configured in your config file (see configuration)
If you use vim you may wish to set a keybinding to automatically run your code and submit it for validation once you have solved a puzzle.
Using Ruby as an example, you could add the following line to your .vimrc:
autocmd filetype ruby nmap <silent><leader>ac :! aoc -s $(ruby %)<CR>Executing leader + ac would then run your program and send the answer to the server for verification (as long as your program only outputs an answer and no other text).
aoc-cli can be configured using the config file at ~/.config/aoc-cli/aoc.rc
To generate an example configuration file you can run aoc -G or aoc --gen-config. (Note this will throw an error if ~/.config/aoc-cli/aoc.rc already exists)
There is also an example aoc.rc file in the sample directory of this repo
Settings are added to the aoc-cli config file in the format
setting_name=>setting
Lines can be commented out of the rc file by prefixing with //
| Flag | Type | Description | Default |
|---|---|---|---|
| calendar_file | bool | Write calendar as a markdown file | true |
| day_dir_prefix | string | Add prefix to day subdirectory nam | nil |
| default | string | Default alias | main |
| ignore_md_files | bool | Auto add md files (calendar and puzzles) to gitignore | true |
| ignore_meta_files | bool | Auto add meta files to gitignore | true |
| init_git | bool | Initialise a git repository on year initialisation | false |
| lb_in_calendar | bool | Include leaderboard stats in calendar file | true |
| reddit_in_browser | bool | Always open reddit links in browser | false |
| unicode_tables | bool | Display tables in unicode format. Otherwise ascii format used | true |
| Flag Short | Flag Long | Action |
|---|---|---|
-a |
--attempts |
Print attempts table |
-B |
--browser |
View reddit megathread in your browser |
-c |
--simple-cal |
Print simplified calendar progress |
-C |
--fancy-cal |
Print styled calendar (requires calendar_file=>true) |
-d |
--init-day |
Initialise day subdirectory |
-D |
--day |
Manual day specification for aoc command |
-G |
--gen-config |
Write example config file |
-h |
--help |
Show help screen |
-k |
--key |
Store session key |
-p |
--part |
Manual part specification for aoc command |
-r |
--refresh |
Refresh calendar (year dir) |
| Refresh puzzle (day subdir) | ||
-R |
--reddit |
Open solution megathread |
-s |
--solve |
Solve puzzle |
-S |
--stats |
Print stats table |
-u |
--user |
Specify alias for aoc command |
-U |
--default |
View default alias, list all aliases (no argument) |
-y |
--init-year |
Initialise year directory |
-Y |
--year |
Specify year for aoc command |
I am in no way affiliated with AoC, but I would like to take this opportunity to thank the creator Eric Wastl for the taking the time and great effort to produce these fantastic puzzles!
Please let me know if there are any bugs or issues with the cli within the issues section - I will try to address them as quickly as I can