elv - Advent of Code CLI

Table of Contents:

1. Introduction
2. Installation
3. Uninstallation
4. Library
5. Examples
6. FAQ
7. Configuration
8. Get Help

Introduction

elv is a command line interface program that lets you interact with Advent of Code API. Advent of Code is a yearly event that happens around Christmas time. Each day of the event, one algorithmic riddle becomes available on its site and everyone can join by solving it and submitting their answers to it.

elv helps you interact with with Advent of Code via your terminal instead of the webpage. So far elv supports:

• downloading riddles' description
• downloading a riddle's input for a given year and day
• submitting answers to a riddle
• automatically guessing what part of the riddle you want to submit
• showing your star progress for a given year including the ASCII art
• getting the official leaderboards for a given year
• guessing the year and day of a riddle based on the current date
• caching AoC responses whenever possible, so you minimize your footprint on AoC's servers
• two functions that let you use elv as a library in your own Rust-based application or code

Installation

Using cargo

cargo is Rust's package manager. You can use it to install elv directly from crates.io. Once you install cargo, you can do it by running the below command in your terminal:

cargo install elv

After the installation, elv should be available from your CLI.

Using homebrew

Homebrew is the self-described "Missing Package Manager for macOS (or Linux)". If you want to install elv using homebrew; first you need to install homebrew itself. Then, run the below in your terminal:

brew install kpagacz/elv/elv

elv is hosted on a private tap (if you are into homebrew's terminology), which is essentially a GitHub repository. By default, homebrew installs the latest version of the application available in the repository. To install one of the previous versions, you must check out a specific commit corresponding to that version.

Downloading a binary

elv publishes several executables for different operating systems and architectures. Head to the releases subpage to check out the latest released version of elv.

Choose the binary matching your operating system and architecture

The archived binaries follow a simple naming scheme: elv-{version}-{target-os-and-arch}.zip. Match your operating system with the file name and the architecture:

• Windows: look for one of the Windows binaries.
• Apple: if you use one of the Silicon processors, download the aarch64-apple-darwin target; otherwise, download the other one.
• Linux: get one of the Linux distributions.

The choice between the GNU version and the other depends on whether you have GNU installed. If yes, then go ahead and grab the appropriate GNU version.

Run the binary

The archives in each release contain a single executable file. Unpack the file. You need to put this executable file on your PATH, which translates to either unpacking the zip file to one of the directories already on PATH or anywhere you want and adding this location to PATH. If inspecting or changing your PATH is unclear, I recommend:

• Windows: https://www.h3xed.com/windows/how-to-add-to-and-edit-windows-path-variable
• Linux/macOS: https://opensource.com/article/17/6/set-path-linux

After that, you should be able to call elv directly in your CLI:

elv

Installing from source

You can create your own executable from this repository if you possess a Rust compiler and cargo. The steps are:

1. Clone the repository. You can use a terminal to clone the repository, e.g.:

   git clone [email protected]:kpagacz/elv.git
   # or
   https://github.com/kpagacz/elv.git

2. Install elv. Navigate towards the elv directory and run:

   cargo install --path .

Uninstallation

Removing configuration files and caches

elv uses a configuration file and caches when running. You can list the directories elv uses by running:

elv list-dirs

The output lists the directories. If you want your configuration file gone and the cache gone as well, just remove these directories from your system.

Cargo

cargo uninstall elv

Installed from binary

Delete the binary from your system.

Installed via brew

brew uninstall kpagacz/elv/elv
brew autoremove

Library

elv exposes a supremely small library that you can use in your scripts or applications. These include:

• elv::get_input - a function that downloads the input for a given year and day
• elv::submit - a function that submits the solution to a given year and day

These functions have decent documentation that you can browse here. Here is a small example from the docs:

// Will succeed if your token is set using another way
get_input(1, 2023, None).unwrap()
submit(20, 2019, "something", 2, Some("Mytoken")).unwrap();

You can also use the Driver object to perform even more actions, but this is not recommended as the API is not stable and may change in the future. The Driver struct is also poorly documented.

Let me know at [email protected] or file an issue if you want to get more functions exposed in the library.

Examples

You need an Advent of Code session token to interact with its API. elv does not support authentication to the API on its own, so you need to get your token beforehand.

Getting and setting the session token - IMPORTANT

You will need to log into Advent of Code. AoC site sends the session token back to you using cookies. So you need to inspect the cookies and get the one named session value. This is your session token you can use with elv. The session token is valid for about a month, so remember to get another once the old one expires.

Once you get your session token, we recommend to set it in elv's configuration. You can do it by running:

elv token <your-session-token>
# or
elv t <your-session-token>

See the section about storing the session key for other ways to store the session token.

If you do not get the session token, you will not be able to interact with Advent of Code API using elv.

Downloading the description

Getting today's riddle description

This works only while the event is being held, not all the time of the year. While the event is not held, you need to specify the year and day of the challenge explicitly using -y and -d parameters.

elv desc

Getting a description of a particular riddle

You specify the day and the year of the riddle.

elv desc -y 2021 -d 1
# Prints the description of the riddle published on the 1st of December 2021

Downloading the input

Getting today's riddle input

This works only while the event is being held, not all the time of the year. While the event is not held, you need to specify the year and day of the challenge explicitly using -y and -d parameters.

elv input

Getting input for a particular riddle

You specify the day and the year of the riddle.

elv input -y 2021 -d 1
# downloads the input for the riddle published on the 1st of December 2021

Submitting the solution

Submitting the solution for today's riddle

This works only while the event is being held, not all the time of the year. While the event is not held, you need to specify the year and day of the challenge explicitly using -y and -d parameters.

elv submit <SOLUTION>
elv submit <SOLUTION>

Submitting the solution for a particular riddle

You specify the day and the year of the riddle.

elv submit -y 2021 -d 1 <SOLUTION>

Specifying the part of the riddle

elv tries to guess the part of the riddle you are solving based on the riddle description. If for some reason you want to override it, or the application fails to guess the part, you can specify it explicitly:

elv submit -y 2021 -d 1 <SOLUTION> one
elv submit -y 2021 -d 1 <SOLUTION> two

Getting the stars and the ASCII art

elv can print the ASCII art and the stars you have collected so far for each year:

elv stars # prints the stars for the latest year
elv stars <YEAR> # prints the stars for the given year
elv stars 2019 # prints the stars for the year 2019

Getting a leaderboard

Getting the global leaderboard for this year

This works only while the event is being held, not all the time of the year. While the event is not held, you need to specify the year explicitly using -y parameter.

elv leaderboard

Getting the global leaderboard for a particular year

You specify the year of the leaderboard.

elv leaderboard -y 2021

Getting a private leaderboard for this year

This works only while the event is being held, not all the time of the year. While the event is not held, you need to specify the year explicitly using -y parameter.

elv private-leaderboard --id <LEADERBOARD ID>
elv pl --id <LEADERBOARD ID>

The private leaderboard command also has an alias pl that you can use instead of writing private-leaderboard.

Getting a private leaderboard for a particular year

You specify the year of the leaderboard.

elv private-leaderboard -y 2021 --id <LEADERBOARD ID>
elv pl -y 2021 --id <LEADERBOARD ID>

Guessing the year and the day of the riddle

elv can guess the year and day of the riddle you are working on. It does so by looking at the current date and arguments year and day passed to elv. The application supports the following scenarios:

• if you do not pass the year and day arguments:
  • if it is December and the event is held, elv will guess you are working on the current day's riddle:

    # Date is December, 6th
    elv desc
    # will download the description of the riddle published on the 6th of December

  • if it is not December, elv will not be able to guess the date and will ask you to provide the year and day arguments

    # Date is November, 24th
    elv desc # will not produce any description

• if you pass only the day argument:
  • if it is December and the event is held, elv will guess you are working on the current year's riddle

    # Date is December, 6th
    elv desc -d 4
    # will download the description of the riddle
    # published on the 4th of December the same year

  • if it is not December, elv will guess you meant the last year's event

    # Date is November, 24th
    elv desc -d 4
    # will download the description of the riddle
    # published on the 4th of December last year

• if you pass only the year argument, elv will not be able to guess the date and will ask you to provide the day argument
• if you pass the year and day arguments, elv will use them regardless of the current date

  elv desc -y 2021 -d 4
  # will download the description of the riddle
  # published on the 4th of December 2021
  # regardless of the current date

FAQ

How can I store the session token?

You can set the session token in elv's configuration using multiple ways, the most convenient being:

1. Set it in the configuration using the CLI:

   elv token 01234567890123456789abcdefghi
   elv t 01234567890123456789abcdefghi
   elv config set aoc.token 01234567890123456789abcdefghi

2. Passed as an argument to elv with the -t parameter:

   elv input -t <YOUR TOKEN HERE>
   # or
   elv input --token <YOUR TOKEN HERE>

   As a live example:

   elv input -t 01234567890123456789abcdefghi

3. As an environment variable. elv looks for an environmental variable AOC_TOKEN while searching for your session token. Example:

   export AOC_TOKEN=0123456789abcdefghi
   elv input

   Despite the fact we have not provided the value for the --token parameter, elv will pick the value of AOC_TOKEN and use it as a token.

4. In a configuration file. elv creates a configuration file in your home directory. You can find the configuration file in a directory listed by running elv list-dirs in your terminal. You should store the token in the [aoc] section, under the token key:

   [aoc]
   token = "<YOUR TOKEN HERE>"

What if I store the session token in the configuration file and pass it as an argument to elv?

elv looks for your token in three places, starting from the first on the below list and moving to the next one if it did not find the token already.

1. elv's configuration file.
2. The AOC_TOKEN environment variable.
3. The -t parameter to the CLI command.

How can I get the value of the session token to pass it to elv?

The session token is sent to your HTTP client (usually your browser) as a cookie when you log into the Advent of Code web page. The easiest way to get the value of a cookie is by using your browser's built-in inspection tools. Look for a way to inspect the cookies specific to your browser.

Where is the configuration file?

All the directories elv uses can be listed by running:

elv list-dirs

Configuration

The application suppports a number of parameters in the configuration file. You can find the configuration file by invoking:

See the current configuration

elv config list
# or
elv config l

Set a configuration parameter

elv config set <PARAMETER> <VALUE>

For example, changing the width of the output to 100 characters:

elv config set cli.output_width 100

Configuration file

elv list-dirs
# cache: /Users/konradpagacz/Library/Caches/elv
# config: /Users/konradpagacz/Library/Application Support/elv

which prints the paths used by elv on your machine. Track down the one named config and open the .config file inside the directory.

Configuration parameters

The configuration file is written in TOML. You can set the following values

• aoc.token - the token used by the application to authenticate you while connecting to AOC servers
• cli.output_width - the column width of the output when calling elv description

Help

If something is not working as expected, or you have an idea for an improvement, feel free to contact me at: [email protected], open an issue or a pull request.