A fast, modern Advent of Code CLI with caching, guardrails, leaderboards, and a lightweight Python API.
Works on macOS, Linux, and Windows. Most networked commands require an AoC session cookie (AOC_SESSION).
Advent of Code has become one of my favorite Christmas traditions. I am never the fastest solver, and some puzzles definitely keep me humble, but the challenges always spark new ideas and mark the start of the holiday season for me.
Thank you to Eric Wastl, the creator of Advent of Code. His work brings an incredible community together every December and inspires people around the world to learn, explore new ideas, and enjoy the fun of programming puzzles.
After refining a small helper tool I have used personally for the past few years, I decided to turn it into a package others can benefit from as well. I originally built an early version for my own workflows in my personal AoC repo.
If Advent of Code is part of your December ritual too, I hope this little elf makes the journey smoother, more fun, and a bit more magical.
- Fetch inputs instantly with automatic caching
- Submit answers safely with smart guardrails (duplicate, low, high, locked, cooldown)
- Explore private leaderboards as tables, CSV, JSON, or Pydantic models
- Start interactive puzzle files with
# %%code cells usingelf new - View your status calendar (table, JSON, or model)
- Inspect your guess history with timestamps and per-part details
- Diagnose local configuration safely with
elf doctor - Open any AoC page (puzzle, input, or website) straight from the CLI
- Use elf as a CLI tool or a full Python API
uv tool install elfuv add elfpip install elf- Python 3.11 or newer
- An Advent of Code account
AOC_SESSIONcookie set in your environment for most commands
Most features in elf require your Advent of Code session cookie so the CLI can access your personal puzzle inputs and progress.
To get it:
- Log in to https://adventofcode.com using GitHub, Google, or Reddit.
- Open your browser’s developer tools.
- Chrome: View → Developer → Developer Tools
- Firefox: Tools → Browser Tools → Web Developer Tools
- Go to the Application (Chrome) or Storage (Firefox) tab.
- Look for Cookies for the domain
adventofcode.com. - Find the cookie named
session. - Copy the value (a long hex string).
- Set it as an environment variable:
export AOC_SESSION="your-session-token"On Windows you can persist the cookie with PowerShell:
$env:AOC_SESSION = "your-session-token"
setx AOC_SESSION "your-session-token"Or via CMD:
setx AOC_SESSION "your-session-token"Most commands require this. You can also pass it via --session in the CLI or session= in the API.
Elf follows the guidance from Eric Wastl (creator of Advent of Code) to help keep traffic friendly to the site.
If you run tools that make automated requests, you should provide contact information in your User-Agent header so Eric can reach you if something goes wrong with your traffic. This is optional but strongly recommended.
Set your email address in the environment variable AOC_USER_AGENT:
export AOC_USER_AGENT="[email protected]"Windows PowerShell:
$env:AOC_USER_AGENT = "[email protected]"
setx AOC_USER_AGENT "[email protected]"If this variable is not set or does not look like an email address, elf falls back to a safe default and prints a warning.
Your User-Agent header will look like elf/<version> ([email protected]).
This helps Eric identify the person sending the traffic while still including the library name.
If the warning fires, elf instead sends elf/<version> (+https://github.com/snally-dev/elf) so AoC still sees a recognizable identifier even without your email.
export AOC_SESSION="your-session-token"
elf input # fetch the latest relevant puzzle input
elf answer 2025 1 1 123 # submit answer for part 1
elf status # view progress
elf leaderboard 2025 123456 --view-key ABCDEFIf you prefer to keep your own local copies of puzzle inputs, elf works just like a regular Unix command. You can redirect the output to save any day's input:
elf input > input.txt # save the default event/day input
elf input 2025 2 > day02.txt # save a specific day's inputUsage: elf [OPTIONS] COMMAND [ARGS]...
Advent of Code CLI
Options:
--version, -V
--debug
--install-completion
--show-completion
--help
Commands:
input Fetch the input for a given year/day
answer Submit an answer
leaderboard Fetch/display a private leaderboard
guesses Show cached guesses
status Show yearly star status
open Open puzzle/input/website
new Create an interactive Python solution file
cache Show cache information
doctor Check local configuration without contacting Advent of CodeEnable detailed tracebacks with --debug or ELF_DEBUG=1 when troubleshooting.
Fetch puzzle input with caching. Requires a session cookie.
Usage: elf input [YEAR] [DAY]
Options:
--session TEXT AOC session cookie (env: AOC_SESSION)Defaults:
- In December,
yearanddayfollow the active event (capped at its final day). - Outside December, they select the final day of the latest completed event.
- An explicitly selected archived year defaults to that event's final day.
- Events from 2015 through 2024 have 25 days; the reduced format from 2025 onward has 12.
- Explicit
yearanddayarguments always take precedence.
Submit an answer with safety guardrails. Requires a session cookie. Guardrails use your local guess cache to short-circuit duplicate answers and infer too-high/too-low for integer guesses.
Usage: elf answer YEAR DAY PART ANSWER
Options:
--session TEXT AOC session cookieBehaviors:
- Year and day are required to avoid accidental submissions.
- Detects locked puzzles (future days or future years) and shows unlock timestamp.
- Identifies too high / too low / duplicate guesses from local cache
- Honors and persists AoC's exact cooldown deadline; falls back to 60 seconds if the response format is unfamiliar
- Never sleeps or automatically retries a submission—you remain in control of every POST
- Writes to guess cache automatically (per part)
Exit codes:
0when the answer is correct or already completed on AoC2when AoC rate-limits you (cooldown/WAIT)1for incorrect/too-high/too-low/unknown guesses
Duplicate guesses reuse cached submissions, so the exit code follows the cached result: e.g., a cached correct/completed guess still exits 0, while cached incorrect/high/low responses return 1. A cooldown returns the exact UTC retry time when AoC provides one.
Example errors:
❄️ Puzzle YYYY‑MM‑DD not unlocked yet
1234 is not correct.
You submitted an answer recently. Please wait...
12345 is correct. Star awarded.Display local guess history (per part). Requires a cached guesses.csv from previous submissions. Displays all guesses for both parts automatically.
Usage: elf guesses [YEAR] [DAY]
Options:
--session TEXT Select the account cache (env: AOC_SESSION)elf guesses loads its data solely from the local guesses.csv; it never reaches out to AoC and does not require AOC_SESSION, so it works offline as long as the cache already exists.
If more than one account has cached guesses for the same puzzle, set AOC_SESSION or pass --session so elf can select the right private cache.
Example table:
Time (UTC) Guess Status
2025‑12‑05 ... 959 too_low
2025‑12‑05 ... 6951 correctFetch private leaderboards. Provide a view key for read-only access or a session cookie for authenticated access. A view key is the read-only share token you can generate on your AoC leaderboard page.
Usage: elf leaderboard YEAR BOARD_ID
Options:
--view-key TEXT
--session TEXT
--format table|csv|json|modelSupports:
- table: pretty Rich table
- csv: one summary row per member
- json: raw JSON
- model: structured Pydantic model
Leaderboard JSON is cached for 15 minutes, matching Advent of Code's minimum request interval. Cache entries are isolated by event, leaderboard ID, and a one-way fingerprint of the session cookie or view key.
View your Advent of Code star calendar. Requires a session cookie.
Usage: elf status [YEAR]
Options:
--session TEXT
--format table|json|modelDefaults:
year: the active event during December, otherwise the latest completed event
Prints stars for each day.
Opens puzzle pages in your browser.
Usage: elf open [YEAR] [DAY]
Options:
--kind puzzle|input|websiteDisplay cache directory information.
Usage: elf cacheShows:
- Cache root directory (platform-aware)
- Number of cached files
- Reminder to delete the directory manually to clear cache
Run local diagnostics without contacting Advent of Code:
elf doctorThe report includes the installed version, AoC clock and resolved default puzzle,
whether session and User-Agent variables are configured, and whether the cache is
writable with private permissions. Credential values are never printed. Warnings
do not fail the command; cache-access errors return exit code 1.
- Default cache dir: macOS/Linux
~/.cache/elf, Windows%LOCALAPPDATA%\elf - Override location with
ELF_CACHE_DIR(respectsXDG_CACHE_HOMEon Linux) - Inputs and guesses are isolated by a one-way account fingerprint; session cookies are never written to disk or included in paths
- Inputs stored under:
<cache>/accounts/<fingerprint>/<year>/<day>/input.txt - Guess history stored under:
<cache>/accounts/<fingerprint>/<year>/<day>/guesses.csv - Private leaderboard JSON is scoped by event, board ID, and account/view-key fingerprint and cached for at least 15 minutes
- New cache files use private permissions where supported and are replaced atomically to avoid partial files after interruption
- Cross-process lock files prevent concurrent leaderboard refreshes and lost guess-history writes; abandoned locks expire safely
- Duplicate/high/low guesses are short‑circuited locally when possible
- Cooldown responses retain AoC's server-provided retry deadline; historical entries without one use a 60-second fallback
- Guardrails rely on your local guess history only (new machines/cleared cache = fresh)
- Delete the cache directory to clear everything
Elf 1.2 preserves the original unscoped <cache>/<year>/<day>/ files. On first authenticated use, each legacy file is copied into the current account's private namespace and marked as claimed; it is never deleted or copied into a second account. If an old cache belongs to a different AoC account, set the intended account's session before first accessing that puzzle. The original file remains available for manual recovery.
Existing four-column guesses.csv files are upgraded in place on the next write by adding an optional retry_at column. Historical rows and original timestamps are preserved. Because cache namespaces intentionally use a session-cookie fingerprint, a replacement cookie starts a new namespace rather than risking cross-account data sharing; older caches remain untouched.
Each internal AOCClient owns and closes its httpx.Client when used as a context manager. Advanced callers can inject an existing httpx.Client to control connection pooling and lifecycle; injected clients are never closed by elf.
from elf import (
get_puzzle_input,
submit_puzzle_answer,
get_private_leaderboard,
get_user_status,
OutputFormat,
)
# AOC_SESSION is used automatically if not passed explicitly
input_text = get_puzzle_input(2023, 5)
result = submit_puzzle_answer(2023, 5, 1, "12345")
print(result.is_correct, result.message)
if result.retry_at:
print("Try again after", result.retry_at)
leaderboard = get_private_leaderboard(
2023, session=None, board_id=123456, view_key=None, fmt=OutputFormat.MODEL
)
status = get_user_status(2023, fmt=OutputFormat.TABLE)
print(status)Create a solution file from elf's interactive template:
elf new 2025 1
elf new 2025 2 --output solutions/2025/day02.pyBy default this creates YEAR/dayDD.py; parent directories are created as needed, and elf refuses to overwrite an existing path. Configure AOC_SESSION as described above, open the generated file in Positron, VS Code, Spyder, or another Python editor, and run the # %% cells from top to bottom. The first input cell retrieves the puzzle input through elf's private, account-scoped cache instead of writing input into your project tree. raw, lines, data, part1_answer, and part2_answer remain at module scope so they appear in the active session's Variables pane and can be inspected between runs.
The same file works as a normal script:
python 2025/day01.pyRunning it in a separate terminal process does not populate an IDE's existing interactive session because the Variables pane reflects only its active Python process. Answer submission is intentionally commented out in the final cell; run a submission line manually only after checking the corresponding answer.
elf.helpers includes some small utilities you can use in your own AoC solutions:
from elf.helpers import parse_input, read_input, timer❯ elf leaderboard 2025 3913340
Advent of Code 2025 – Private Leaderboard
┏━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Rank ┃ Name ┃ Stars ┃ Local Score ┃ First Star (UTC) ┃ Last Star (UTC) ┃
┡━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ User A │ 24 │ 900 │ 2025-12-01 00:04:21 │ 2025-12-12 00:53:17 │
│ 2 │ User B │ 24 │ 855 │ 2025-12-01 00:05:02 │ 2025-12-12 00:53:56 │
│ 3 │ User C │ 18 │ 622 │ 2025-12-01 00:07:45 │ 2025-12-12 03:29:21 │
└──────┴────────┴───────┴─────────────┴─────────────────────┴─────────────────────┘JSON format:
elf leaderboard 2025 3982840 --format jsonModel format (Pydantic):
lb = get_private_leaderboard(2025, board_id=3982840, fmt=OutputFormat.MODEL)
members = sorted(lb.members.values(), key=lambda m: (-m.local_score, -m.stars))
print(members[0].name, members[0].stars)CSV provides one summary row per member for tabular analysis. JSON preserves the complete Advent of Code response, including individual star completions. The Python model remains available for more advanced processing, and all formats work with any tool that understands standard CSV or JSON.
elf leaderboard 2025 123456 --format csv > leaderboard.csv
elf leaderboard 2025 123456 --format json > leaderboard.jsonfrom elf import OutputFormat, get_private_leaderboard
csv_data = get_private_leaderboard(2025, board_id=123456, fmt=OutputFormat.CSV)
json_data = get_private_leaderboard(2025, board_id=123456, fmt=OutputFormat.JSON)❯ elf status 2023
Advent of Code
2023 – cak
(AoC++) [34⭐]
┏━━━━━┳━━━━━━━┓
┃ Day ┃ Stars ┃
┡━━━━━╇━━━━━━━┩
│ 1 │ ★★ │
│ 2 │ ★★ │
│ 3 │ ★★ │
│ 4 │ ★☆ │
│ 5 │ ★☆ │
│ 6 │ ★★ │
│ 7 │ ★★ │
│ 8 │ ★☆ │
│ 9 │ ☆☆ │
│ 10 │ ☆☆ │
│ .. │ .. │
│ 25 │ ☆☆ │
└─────┴───────┘JSON format:
elf status 2023 --format jsonModel format:
status = get_user_status(2023, fmt=OutputFormat.MODEL)
print(status.days[0].day, status.days[0].stars)Run the test suite via:
uv run pytestRun the complete local quality pass via:
uv run ruff check elf tests
uv run ruff format --check elf tests
uv run mypy
uv buildGitHub Actions runs the full Python 3.11–3.14 suite on Linux, plus Python 3.14 smoke jobs on macOS and Windows. Tests block external network access, mock every Advent of Code interaction, and never fetch inputs or submit answers.
Alternatively, you can still run:
python -m pytestRunning python -m pytest directly requires pytest to be installed in your environment. Install it via pip install pytest>=9.0.1 (or use uv sync --group dev and uv run pytest) before running the command outside of uv.
This project exists thanks to the generosity and creativity of others.
Thanks to Solos for donating the elf PyPI name.
