{"id":21262329,"url":"https://github.com/apexatoll/aoc-cli","last_synced_at":"2025-07-11T04:30:34.079Z","repository":{"id":45647654,"uuid":"337081415","full_name":"apexatoll/aoc-cli","owner":"apexatoll","description":"Command line interface for Advent of Code, built in Ruby using Kangaru","archived":false,"fork":false,"pushed_at":"2024-01-28T13:53:53.000Z","size":85441,"stargazers_count":55,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-08-31T17:48:46.361Z","etag":null,"topics":["advent-of-code","aoc","cli","kangaru","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apexatoll.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-02-08T13:15:37.000Z","updated_at":"2024-05-27T13:02:53.000Z","dependencies_parsed_at":"2024-01-28T14:42:09.591Z","dependency_job_id":null,"html_url":"https://github.com/apexatoll/aoc-cli","commit_stats":{"total_commits":54,"total_committers":2,"mean_commits":27.0,"dds":0.03703703703703709,"last_synced_commit":"4e45b418103e3647a68346c778e2b516f6a84889"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apexatoll%2Faoc-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apexatoll%2Faoc-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apexatoll%2Faoc-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apexatoll%2Faoc-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apexatoll","download_url":"https://codeload.github.com/apexatoll/aoc-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225674928,"owners_count":17506272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["advent-of-code","aoc","cli","kangaru","ruby"],"created_at":"2024-11-21T04:58:11.330Z","updated_at":"2024-11-21T04:58:12.015Z","avatar_url":"https://github.com/apexatoll.png","language":"Ruby","readme":"# `aoc-cli`\n\n[![Gem Version](https://badge.fury.io/rb/aoc_cli.svg)](https://badge.fury.io/rb/aoc_cli) ![aoc-ci](https://github.com/apexatoll/aoc-cli/actions/workflows/main.yml/badge.svg) [![codecov](https://codecov.io/gh/apexatoll/aoc-cli/graph/badge.svg?token=7R3GFUAXI5)](https://codecov.io/gh/apexatoll/aoc-cli)\n\nA command-line interface for Advent of Code, built in Ruby.\n\n\u003e [!IMPORTANT]\n\u003e `aoc_cli` has gone through a complete rewrite as of `1.0.0` in order to improve resilience and the overall user interface.\n\u003e 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.\n\u003e There are also some other improvements on performance, and removal of some hefty dependencies such as `pandoc`.\n\u003e These are breaking changes, so please pin your version to `0.2.3` if you wish to continue using the previous version.\n\n\n## Main Features\n\n- Download puzzles as markdown and raw inputs directly from the command line\n- Submit answers for puzzles and receive feedback\n- Track data on your progress through the event\n\n\n## Installation\n\n- As of `1.0.0`, `aoc_cli` no longer requires `pandoc`\n- Other system requirements are `curl` and `sqlite3` and `ruby` \u003e= `3.2.0`\n\n\nInstall `aoc_cli` with the following command\n\n```bash\ngem install aoc_cli\n```\n\n\n## Setup\n\n### Setting your Session Key\n\nTo 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. \n\nOpen developer tools and open the network tab. Refresh the page and you should see a file that contains your session cookie.\n\nIt will contain a field that looks something like:\n\n```\ncookie: session=HEXADECIMAL_STRING\n```\n\nThis 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.\n\nYour session token should be copied into your configuration file (`~/.config/aoc_cli/config.yml`) under the `session.token` nested key:\n\n```yaml\nsession:\n  token: \u003cYOUR TOKEN\u003e\n```\n\n\u003e [!IMPORTANT]\n\u003e Make sure to strip the `session=` prefix from the copied token.\n\n\u003e [!NOTE]\n\u003e Multiple users used to be a feature pre the 1.0.0 overhaul. This will be\n\u003e reimplemented and released in an upcoming release if there is need for it.\n\n\n## Usage\n\n`aoc-cli` is designed to run in a file-tree generated by the application. \n\nThere are two types of directories\n\n1. Event directories\n- These contain puzzle subdirectories\n\n2. Puzzle subdirectories\n- These contain puzzles, input and your soution code\n\n### Directory Structure Example\n\n```\n  2023 \u003c--- Event Directory\n  │     \n  ├── 1 \u003c-- Puzzle Directory\n  │   │ \n  │   ├── day_1.md\n  │   ├── input\n  │   └── solution.rb\n  └── 2\n      ├── day_2.md\n      ├── input\n      └── solution.rs\n```\n\n### Initialising an Event\n\nTo 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.\n\n\u003e [!NOTE]\n\u003e 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`.\n\nTo initialize an event, run the following command:\n\n```bash\naoc event init \u003cYEAR\u003e\n```\n\nThis will:\n\n- Fetch your latest stats and setup your progress\n- Create an event directory\n\nAt the time of writing, the valid years are 2015 - 2023.\n\n\n### Initialising a Puzzle\n\n\u003e [!CAUTION]\n\u003e Please do not check puzzle or input files into your version control system, as this is against Advent of Code rules.\n\nRun the following command from an event directory to fetch and initialize a puzzle directory and associated files:\n\n```bash\naoc puzzle init \u003cDAY\u003e\n```\n\nThis command performs the following actions\n\n- Creates a puzzle subdirectory\n- Fetches the puzzle as markdown and writes to the puzzle dir\n- Fetches raw puzzle input and writes to the puzzle dir\n\nThis directory is a good place to write your solution code adjacent to your input and puzzle files.\n\n\n### Solving Puzzles\n\nFrom the puzzle subdirectory you can solve puzzles by running the command \n\n```bash\naoc puzzle solve --answer \u003cANSWER\u003e\n```\n\nYou will then receive one of three responses\n\n1. The answer was correct\n2. The answer was not correct\n3. You have time to wait before submitting an answer\n\nIf your answer is correct, `aoc-cli` will automatically update the puzzle instructions and your event progress. \n\nIncorrect 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.\n\nIf you have sent multiple incorrect attempts AoC will ask you to wait before trying to answer the puzzle again.\n\n\n## Tables\n\n`aoc-cli` uses a local SQLite database to store information about your progress with puzzles. This tracks data on:\n\n1. Your progress for the current event\n1. Your attempts for the current puzzle\n\nThis data can be visualised in terminal-friendly tables\n\n\n### Attempts\n\nPrevious attempts for a puzzle can be viewed from the puzzle directory by the use of the command:\n\n```bash\naoc puzzle attempts\n```\n\n### Progress\n\nTo view your progress in the year you can run the following command from within an event or a puzzle directory.\n\n```bash\naoc event progress\n```\n\nThis will print a simple table showing your stars for each day. This is created on year initialisation and updated as you complete puzzles\n\n\n## Help\n\n`aoc-cli` also has built in documentation. You can view this from the terminal using either `aoc help \u003cCOMMAND\u003e` or `aoc \u003cCOMMAND\u003e --help`.\n\n\n## Contributing\n\nPlease create an issue if there are any bugs or problems using `aoc-cli`. Contributions and questions are always welcome.\n\n\n## Acknowledgments\n\n`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.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapexatoll%2Faoc-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapexatoll%2Faoc-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapexatoll%2Faoc-cli/lists"}