Skip to content
Athena User Guide
Esc
↑↓navigate↵open⌘Jpreview
On this page

Use the athena CLI

Install the command-line tool, point it at an event, and drive your CTF from a terminal or a CI job.

athena is a command-line tool that talks to your event’s Admin API. Almost anything you can do from the event dashboard, you can script: publish challenges, post announcements, adjust scores, issue certificates, export data. It’s a single binary with no runtime to install.

The CLI uses the same API keys as any other integration, so it needs a plan that includes API access (Starter and above).

Install

curl -fsSL https://downloads.athena-ctf.com/cli/install.sh | sh
irm https://downloads.athena-ctf.com/cli/install.ps1 | iex

Download the archive for your platform, unpack it, and put the athena binary on your PATH:

Platform File
Linux (x86-64) https://downloads.athena-ctf.com/cli/latest/athena-linux-x64.tar.gz
Linux (ARM64) https://downloads.athena-ctf.com/cli/latest/athena-linux-arm64.tar.gz
macOS (Apple silicon) https://downloads.athena-ctf.com/cli/latest/athena-darwin-arm64.tar.gz
macOS (Intel) https://downloads.athena-ctf.com/cli/latest/athena-darwin-x64.tar.gz
Windows (x86-64) https://downloads.athena-ctf.com/cli/latest/athena-windows-x64.zip
Windows (ARM64) https://downloads.athena-ctf.com/cli/latest/athena-windows-arm64.zip

Each archive is listed in https://downloads.athena-ctf.com/cli/latest/SHA256SUMS, so you can verify what you downloaded:

sha256sum -c SHA256SUMS --ignore-missing

To pin a version, put it in the path in place of latest, as in https://downloads.athena-ctf.com/cli/v1.0.0/athena-linux-x64.tar.gz. Every published version, with its file sizes and checksums, is listed at downloads.athena-ctf.com/releases.

The install scripts take a version too:

curl -fsSL https://downloads.athena-ctf.com/cli/install.sh | ATHENA_CLI_VERSION=v1.0.0 sh

Check it worked:

athena --version

Point it at an event

Every command needs two things: your event’s API URL and an API key. Both come from the event’s API keys page; see Create API keys.

Either URL form works: the value the API keys page gives you, ending in /api/admin, or your event’s address on its own, as in https://winter.example.com. A trailing slash on either is fine.

Save the event under a short name you’ll use locally. --use makes it the current one:

athena event add winter \
  --url https://winter.example.com/api/admin \
  --key <your-api-key> \
  --use

The name is yours alone; it’s stored on your machine and means nothing to the platform.

Then confirm it works:

athena stats

You should see the event’s player, challenge and submission totals. An authentication failure here means the key is wrong, expired, or revoked.

Run more than one CTF? Add each one and switch between them:

athena event list          # every event you've saved
athena event use spring    # change the current event
athena challenge list -e winter   # or target one for a single command

Where the config lives

Saved events go in a JSON file:

Platform Path
macOS / Linux $XDG_CONFIG_HOME/athena/config.json, else ~/.config/athena/config.json
Windows %APPDATA%\athena\config.json

It holds the URL and key for each named event, so treat it like any other credential file. On macOS and Linux it’s written readable only by you; on Windows it inherits whatever the parent folder allows. athena event rm <name> removes an entry.

Use it in CI

Don’t write a config file on a build agent. Set two environment variables instead and skip event add entirely:

export CTF_ADMIN_API_URL="https://winter.example.com"
export CTF_ADMIN_API_KEY="$ATHENA_KEY"   # from your CI secret store

athena challenge apply <challenge-id> \
  --file ./challenges/web-100.json \
  --yes

Which target wins

When more than one source names a target, the most specific wins:

Priority Source
Highest --url and --key on the command itself
--event <name> (-e)
CTF_ADMIN_API_URL and CTF_ADMIN_API_KEY
Lowest Whatever athena event use last selected

Each field resolves on its own, so --url with a key from the environment works fine.

Flags every command takes

Flag What it does
--json Print the raw API response instead of a formatted summary. Use this when piping to jq.
-y, --yes Skip the confirmation prompt on destructive commands. Required in CI, since without a terminal those commands refuse rather than prompt.
-e, --event Target a saved event for this command only.
--url, --key Target an event that isn’t saved. --url takes the event’s address with or without /api/admin on the end.

A few things you’ll do often

# What's on the board
athena challenge list

# Publish a hidden challenge right now
athena challenge show <challenge-id>

# ...or schedule it
athena challenge show <challenge-id> --release-at 2026-03-01T10:00:00Z

# Post an announcement
athena announcement create \
  --title "Hint released" \
  --body "<p>Check challenge 4.</p>"

# Take a challenge out of play mid-event, killing its instances
athena challenge lock <challenge-id> --reason "Flag leaked"

Two commands do more than one API call and are worth knowing:

  • athena challenge apply <id> --file <path> reads a desired-state JSON file, compares it against the challenge as it exists now, and issues only the calls that differ. Safe to re-run, which is what makes challenge definitions reviewable in git.
  • athena storage upload <path> mints a signed upload URL and uploads through it in one step, so attaching a file is storage upload then challenge file add.

What it won’t do

  • Create or revoke API keys. Key management stays in the dashboard on purpose. athena key list shows what exists; minting and revoking are dashboard-only.
  • Change the event’s start, freeze, or end times. Those move automatic teardown with them, so they’re refused over the API and belong on the Settings page.

Every command, group by group, is in the CLI command reference.

Was this page helpful?