elf
Advanced tools
Advent of Code helper for Python: fetch and cache inputs, submit answers, and pull private leaderboards.
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.
uv tool install elf
uv add elf
pip install elf
AOC_SESSION cookie set in your environment for most commandsMost features in elf require your Advent of Code session cookie so the CLI can access your personal puzzle inputs and progress.
To get it:
adventofcode.com.session.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="you@example.com"
Windows PowerShell:
$env:AOC_USER_AGENT = "you@example.com"
setx AOC_USER_AGENT "you@example.com"
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/ (you@example.com) 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/cak/elf) so AoC still sees a recognizable identifier even without your email.
export AOC_SESSION="your-session-token"
elf input # fetch today's input
elf answer 2025 1 1 123 # submit answer for part 1
elf status # view progress
elf leaderboard 2025 123456 --view-key ABCDEF
If 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 today's input
elf input 2025 2 > day02.txt # save a specific day's input
elf --helpUsage: 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
cache Show cache information
Enable detailed tracebacks with --debug or ELF_DEBUG=1 when troubleshooting.
elf inputFetch puzzle input with caching. Requires a session cookie.
Usage: elf input [YEAR] [DAY]
Options:
--session TEXT AOC session cookie (env: AOC_SESSION)
Defaults:
year: current yearday: current day in December, otherwise 1 (Dec 1)~/.cache/elf/<year>/<day>/input.txt (or platform equivalent)elf answerSubmit 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 cookie
Behaviors:
Exit codes:
0 when the answer is correct or already completed on AoC2 when AoC rate-limits you (cooldown/WAIT)1 for incorrect/too-high/too-low/unknown guessesDuplicate 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.
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.
elf guessesDisplay 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]
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.
Example table:
Time (UTC) Guess Status
2025‑12‑05 ... 959 too_low
2025‑12‑05 ... 6951 correct
elf leaderboardFetch 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|json|model
Supports:
elf statusView your Advent of Code star calendar. Requires a session cookie.
Usage: elf status [YEAR]
Options:
--session TEXT
--format table|json|model
Defaults:
year: current year if omittedPrints stars for each day.
elf openOpens puzzle pages in your browser.
Usage: elf open [YEAR] [DAY]
Options:
--kind puzzle|input|website
elf cacheDisplay cache directory information.
Usage: elf cache
Shows:
~/.cache/elf, Windows %LOCALAPPDATA%\elfELF_CACHE_DIR (respects XDG_CACHE_HOME on Linux)<cache>/<year>/<day>/input.txt<cache>/<year>/<day>/guesses.csvThe library reuses a process-global httpx.Client to keep CLI calls fast. For heavy multi-threaded usage, create separate elf.aoc_client.AOCClient instances per thread to avoid sharing the global session.
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)
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)
elf.helpers includes some small utilities you can use in your own AoC solutions:
from elf.helpers import parse_input, read_test_input, timer
❯ elf leaderboard 2025 3913340
Advent of Code 2025 – Private Leaderboard
┏━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Rank ┃ Name ┃ Stars ┃ Local Score ┃ Last Star (UTC) ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ User A │ 45 │ 900 │ 2025-12-26 00:53:17 │
│ 2 │ User B │ 45 │ 855 │ 2025-12-26 00:53:56 │
│ 3 │ User C │ 36 │ 622 │ 2025-12-26 03:29:21 │
└──────┴────────────────┴───────┴─────────────┴─────────────────────┘
JSON format:
elf leaderboard 2025 3982840 --format json
Model 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)
❯ 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 json
Model 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 pytest
Alternatively, you can still run:
python -m pytest
Running python -m pytest directly requires pytest to be installed in your environment. Install it via pip install pytest>=9.0.1 (or use uv run pytest / pip install .[dev] if you maintain the dev extras) 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.
FAQs
Advent of Code helper for Python: fetch and cache inputs, submit answers, and pull private leaderboards.
We found that elf demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
TeamPCP and BreachForums are promoting a Shai-Hulud supply chain attack contest with a $1,000 prize for the biggest package compromise.
Security News
Packagist urges PHP projects to update Composer after a GitHub token format change exposed some GitHub Actions tokens in CI logs.
Research
GemStuffer abuses RubyGems as an exfiltration channel, packaging scraped UK council portal data into junk gems published from new accounts.