aoc-cli

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

• 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

• 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

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>

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

There are two types of directories

1. Event directories

• These contain puzzle subdirectories

2. Puzzle subdirectories

• These contain puzzles, input and your soution code

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

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.

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.

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.

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.

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

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

aoc puzzle attempts

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

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

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

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.