Skip to main content

​
Overview

Epics are the strategic layer in Apollo’s work hierarchy: 
Project -> Epic -> Release -> Task
An epic groups related releases under a single initiative. The CLI lets you list epics, drill into their releases and tasks, track completion, and manage epic lifecycle — all from the terminal.
Tasks connect to epics indirectly through releases. When you run apollo epic tasks, the CLI fetches all releases for the epic, then batch-fetches tasks across those releases.

​
Epic Statuses

StatusMeaning
draftPlanning phase, not yet active
activeCurrently in progress
completedAll work finished
archivedNo longer relevant

​
List Epics

# List epics in a project
apollo epic list -p "Apollo"

# Filter by status
apollo epic list -p "Apollo" -s active

# Limit results
apollo epic list -p "Apollo" --limit 20
Options:
FlagDescription
-p, --project <name>Project name or ID (required)
-s, --status <status>Filter by status (draft, active, completed, archived)
--limit <n>Max results (default: 50)

​
View Epic Details

Shows epic metadata, a progress bar, release breakdown, and task stats: 
apollo epic view "Authentication Overhaul"

Authentication Overhaul
────────────────────────────────────────────────────────────
  Status:  active
  Project: Apollo
  Quarter: Q2 2026
  ID:      550e8400-...

  Progress
  ████████████░░░░░░░░ 60%  12/20 tasks done
  Releases: 1/3 completed
  In Progress: 4 | Todo: 3 | Blocked: 1

  Releases (3)
  completed      Auth v1.0       12/12 tasks
  in_progress    Auth v1.1       0/5 tasks
  planned        Auth v2.0       0/3 tasks
The JSON output includes the full epic object, releases array, and computed task_stats: 
apollo epic view "Authentication Overhaul" --json

{
  "id": "550e8400-...",
  "title": "Authentication Overhaul",
  "status": "active",
  "releases": [...],
  "task_stats": {
    "total": 20,
    "done": 12,
    "in_progress": 4,
    "todo": 3,
    "blocked": 1,
    "backlog": 0,
    "completed_releases": 1,
    "total_releases": 3,
    "progress_pct": 60
  }
}

​
Create an Epic

apollo epic create \
  -t "Authentication Overhaul" \
  -p "Apollo" \
  --status active \
  --quarter "Q2 2026" \
  --description "Migrate from session-based to JWT auth"
Options:
FlagDescription
-t, --title <title>Epic title (required)
-p, --project <name>Project name or ID (required)
-s, --status <status>Initial status (default: draft)
--description <desc>Epic description
--quarter <text>Target quarter (e.g., Q2 2026)
--color <hex>Color hex code (default: #6366f1)

​
Update an Epic

Update any epic field after creation: 
# Change status
apollo epic update "Auth Overhaul" -s active

# Update quarter and description
apollo epic update "Auth Overhaul" --quarter "Q3 2026" --description "Scope expanded"

# Rename
apollo epic update "Auth Overhaul" -t "Auth & SSO Overhaul"
Options:
FlagDescription
-t, --title <title>New title
-s, --status <status>New status (draft, active, completed, archived)
--description <desc>New description
--quarter <text>New target quarter
--color <hex>New color hex code

​
Complete an Epic

Shortcut to set status to completed: 
apollo epic complete "Auth Overhaul"

​
Archive an Epic

Shortcut to set status to archived: 
apollo epic archive "Auth Overhaul"

​
List Epic Tasks

Fetches all tasks across all releases belonging to the epic. This is the recursive drill-down view: 
apollo epic tasks "Auth Overhaul"

 ID       Title                        Status       Release      Assignee
─────────┼────────────────────────────┼────────────┼────────────┼──────────
 550e8400 Implement JWT middleware     done         Auth v1.0    Ian Soares
 7a3b1c2d Add refresh token rotation  in_progress  Auth v1.1    Ana Lima
 9e4f2a8b Fix token expiry edge case  blocked      Auth v1.1    Ian Soares
 ...

12 task(s) across 3 release(s)
JSON output returns the full tasks array: 
apollo epic tasks "Auth Overhaul" --json
Options:
FlagDescription
--limit <n>Max tasks per release (default: 200)