aoc-cli

A command-line interface for Advent of Code, built in Ruby.

[!IMPORTANT] aoc_cli has gone through a complete rewrite as of 1.0.0 in order to improve resilience and the overall user interface. The core application has been swapped out to use the Kangaru command line framework, with a completely new API and removal of bloated features. There are also some other improvements on performance, and removal of some hefty dependencies such as pandoc. These are breaking changes, so please pin your version to 0.2.3 if you wish to continue using the previous version.

Main Features

  • Download puzzles as markdown and raw inputs directly from the command line
  • Submit answers for puzzles and receive feedback
  • Track data on your progress through the event

Installation

  • As of 1.0.0, aoc_cli no longer requires pandoc
  • Other system requirements are curl and sqlite3 and ruby >= 3.2.0

Install aoc_cli with the following command

gem install aoc_cli

Setup

Setting 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 on your behalf - do not share this or check this into version control.

Your session token should be copied into your configuration file (~/.config/aoc_cli/config.yml) under the session.token nested key:

session:
  token: <YOUR TOKEN>

[!IMPORTANT] Make sure to strip the session= prefix from the copied token.

[!NOTE] Multiple users used to be a feature pre the 1.0.0 overhaul. This will be reimplemented and released in an upcoming release if there is need for it.

Usage

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

There are two types of directories

  1. Event directories

  2. These contain puzzle subdirectories

  3. Puzzle subdirectories

  4. These contain puzzles, input and your soution code

Directory Structure Example

  2023 <--- Event Directory
  │     
  ├── 1 <-- Puzzle Directory
  │   │ 
  │   ├── day_1.md
  │   ├── input
  │   └── solution.rb
  └── 2
      ├── day_2.md
      ├── input
      └── solution.rs

Initialising an Event

To begin using the cli you must first initialise an event directory. An event directory is the parent directory in which your puzzle directories (and your code solutions) exist.

[!NOTE] If you are planning on tackling multiple Advent of Code events, it is probably wise to create a root for your event directories, eg ~/aoc.

To initialize an event, run the following command:

aoc event init <YEAR>

This will:

  • Fetch your latest stats and setup your progress
  • Create an event directory

At the time of writing, the valid years are 2015 - 2023.

Initialising a Puzzle

[!CAUTION] Please do not check puzzle or input files into your version control system, as this is against Advent of Code rules.

Run the following command from an event directory to fetch and initialize a puzzle directory and associated files:

aoc puzzle init <DAY>

This command performs the following actions

  • Creates a puzzle subdirectory
  • Fetches the puzzle as markdown and writes to the puzzle dir
  • Fetches raw puzzle input and writes to the puzzle dir

This directory is a good place to write your solution code adjacent to your input and puzzle files.

Solving Puzzles

From the puzzle subdirectory you can solve puzzles by running the command 

aoc puzzle solve --answer <ANSWER>

You will then receive one of three responses

  1. The answer was correct
  2. The answer was not correct
  3. You have time to wait before submitting an answer

If your answer is correct, aoc-cli will automatically update the puzzle instructions and your event progress.

Incorrect attempts will be logged along with any hint as to whether your answer was too high or too low. You can recall these using the puzzle attempts command.

If you have sent multiple incorrect attempts AoC will ask you to wait before trying to answer the puzzle again.

Tables

aoc-cli uses a local SQLite database to store information about your progress with puzzles. This tracks data on:

  1. Your progress for the current event
  2. Your attempts for the current puzzle

This data can be visualised in terminal-friendly tables

Attempts

Previous attempts for a puzzle can be viewed from the puzzle directory by the use of the command:

aoc puzzle attempts

Progress

To view your progress in the year you can run the following command from within an event or a puzzle directory.

aoc event progress

This will print a simple table showing your stars for each day. This is created on year initialisation and updated as you complete puzzles

Help

aoc-cli also has built in documentation. You can view this from the terminal using either aoc help <COMMAND> or aoc <COMMAND> --help.

Contributing

Please create an issue if there are any bugs or problems using aoc-cli. Contributions and questions are always welcome.

Acknowledgments

aoc-cli is in no way affiliated with Advent of Code, but I would like to take this opportunity to thank the creator, Eric Wastl, for his efforts in producing these fantastic puzzles year on year.