The project is in a healthy, maintained state
A command-line interface for the Advent of Code puzzles. Features include downloading puzzles and inputs, solving puzzles and tracking year progress from within the terminal
 Project Readme

Advent of Code - cli

A command-line interface to interact with Advent of Code puzzles, built in Ruby.

Main Features

  • 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

Note to Existing Users

  • If you are having any issues with the calendar table, run aoc -r in your year directory to update and refresh your directory

Whats New

New to 0.2.2

  • Year refresh now creates the calendar table if it does not exist
  • Update terminal-table version requirements
  • Add version flag

New to 0.2.1

  • Day subdir prefix functionality
  • Duplicate incorrect attempts prevented

New to 0.2.0

  • 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_cli

Manual install

$ git clone ""
$ cd aoc-cli
$ rake build install


Finding your Session Key

To 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!

Storing your Session Key

  • 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 -u or --user flags 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:


For example:


Default Alias

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_alias

By default, aoc-cli will determine the default alias in the following order of precedence

  • The alias explicitly set by default=>$alias in your config file or by using the -U command
  • The main alias (if it exists)
  • The first key in your config file

Use Case

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 ruby

You 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 ruby

Alternatively you could add the following line to your config file



aoc-cli is designed to run in a file-tree generated by the interface.

There are two types of directories

  1. Year directories
    • These contain your calendar and all day subdirectories
  2. Day subdirectories
    • These contain the puzzles, your input and your code

Initialising the Year

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 2020

Initialise the year directory using the command

aoc -y 2020

This will set the session key for the year directory to the default alias. To use a different alias run:

aoc -y 2020 -u $alias

This 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)

Initialising a Day

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_number

This 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

Solving Puzzles

From the day subdirectory you can attempt to solve puzzles by running the command

aoc -s $answer

You will then receive one of four responses

  1. The answer is correct
  2. The answer is not correct
  3. You have already tried this incorrect answer
  4. 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:

  1. Your attempts
  2. Your stats
  3. 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 $part

Data 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)


Reddit Integration


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)

Git Integration

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)

Vim Integration

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


Lines can be commented out of the rc file by prefixing with //

List of Configurable Options

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

All Flags

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