---
title: Use the athena CLI
description: Install the command-line tool, point it at an event, and drive your CTF from a terminal or a CI job.
sidebar:
  badge: Starter+
---

`athena` is a command-line tool that talks to your event's [Admin API](/organizers/reference/event-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

**macOS / Linux**

```bash
curl -fsSL https://downloads.athena-ctf.com/cli/install.sh | sh
```

**Windows**

```powershell
irm https://downloads.athena-ctf.com/cli/install.ps1 | iex
```

**Manual**

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:

```bash
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](https://downloads.athena-ctf.com/releases).

The install scripts take a version too:

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

Check it worked:

```bash
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](/organizers/how-to/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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
```

:::tip
Give each pipeline its own API key. Revoking one then stops that pipeline and nothing else.
:::

### 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

```bash
# 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](/organizers/reference/cli-commands).
