nog

nog is a small Advent of Code helper CLI for managing puzzle workflows from the terminal.

The goal is to reduce friction while solving Advent of Code challenges: authenticate, fetch and cache puzzle inputs, scaffold solution files, run local solutions, and eventually submit or validate answers without constantly switching back to the browser.

Status

Early development. As of v0.3.0, nog includes usable authentication and puzzle-input workflows:

• nog auth login opens a browser-assisted Advent of Code login flow.
• Users can log in with their preferred Advent of Code login provider.
• nog extracts the Advent of Code session cookie and saves it locally as a normalized session record.
• nog input YEAR DAY prints the requested puzzle input to stdout.
• Puzzle inputs are cached locally and reused without another network request.
• A cached input can be read even when no valid session is currently available.
• --force bypasses the cache and fetches a fresh copy.
• Puzzle dates are validated before retrieval.
• Authentication, network, HTTP-response, cache, orchestration, validation, and CLI behavior have automated test coverage.

Puzzle-description fetching, solution scaffolding, running, validation, progress tracking, and answer submission are not implemented yet.

Current Commands

Authenticate with Advent of Code:

nog auth login

Retrieve a puzzle input:

nog input 2024 1

Force a fresh download and replace the cached copy:

nog input 2024 1 --force

Puzzle input is written directly to stdout, so it can also be redirected or piped:

nog input 2024 1 > input.txt

Development-only authentication:

nog auth login --dev

The --dev option is intended for local development and testing. It is not part of the normal user workflow.

Input Retrieval Behavior

By default, nog input:

1. validates the requested puzzle date;
2. returns the locally cached input when available;
3. requires a valid saved Advent of Code session only when a network request is required;
4. fetches and caches the input when it is not already available locally;
5. prints the input without adding an extra newline.

Use --force to bypass the cache. A valid saved session is required whenever nog must contact Advent of Code.

Planned Direction

nog is intended to expand into:

• fetching and caching puzzle descriptions
• generating starter files from language templates
• running local solutions
• submitting or locally validating answers
• tracking local progress by language
• avoiding duplicate or unnecessary submissions

Planned Command Shape

nog new 2024 1
nog run 2024 1
nog submit 2024 1
nog status 2024 1

The default workflow should stay simple, with options added over time for manual overrides such as language, puzzle part, or answer value.

Notes

Puzzle inputs, cached puzzle text, session records, and other local Advent of Code data should stay local and should not be committed to public repositories.