Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/apexatoll/aoc-cli
Command line interface for Advent of Code, built in Ruby using Kangaru
https://github.com/apexatoll/aoc-cli
advent-of-code aoc cli kangaru ruby
Last synced: about 1 month ago
JSON representation
Command line interface for Advent of Code, built in Ruby using Kangaru
- Host: GitHub
- URL: https://github.com/apexatoll/aoc-cli
- Owner: apexatoll
- License: mit
- Created: 2021-02-08T13:15:37.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-01-28T13:53:53.000Z (11 months ago)
- Last Synced: 2024-08-31T17:48:46.361Z (4 months ago)
- Topics: advent-of-code, aoc, cli, kangaru, ruby
- Language: Ruby
- Homepage:
- Size: 81.5 MB
- Stars: 55
- Watchers: 4
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# `aoc-cli`
[](https://badge.fury.io/rb/aoc_cli)  [](https://codecov.io/gh/apexatoll/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](https://github.com/apexatoll/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
```bash
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:
```yaml
session:
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
- These contain puzzle subdirectories
2. Puzzle subdirectories
- 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:
```bash
aoc event init
```
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:
```bash
aoc puzzle init
```
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
```bash
aoc puzzle solve --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
1. 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:
```bash
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.
```bash
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 ` or `aoc --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.