empire-cli

⚔️ Empire CLI 👑

Status: Feature Complete — 2 maps, diplomacy, buildings, AI narrator. Play it!

A CLI turn-based strategy RPG where you build armies, expand your empire, and conquer the world. Open source, runs in any terminal.

Screenshots

Quick Start

# Play instantly (no install needed)
npx empire-cli

# Or clone for development
git clone https://github.com/lppduy/empire-cli.git
cd empire-cli
npm install
npm start

Quick Tutorial

1. Start a new game → pick a faction (e.g. Iron Legion)
2. "map" — see the world map
3. "info northkeep" — inspect a territory
4. "recruit northkeep 3" — train 3 units (costs 3💰 + 2🍖 each)
5. "move northkeep greenwood 3" — march 3 units to Greenwood
6. "build northkeep walls" — build walls for defense (costs 🪵🪨)
7. "attack greenwood silver" — attack Silver Bay from Greenwood
8. "next" — end your turn (or use all 3 actions, auto-advances)
8. Watch enemy factions react — then plan your next move!

Goal: Conquer all territories to win.

When starting a new game, you pick a map, choose a faction, then customize your leader name, nation name, and slogan (all optional — press Enter to skip).

Commands

You get 3 actions per turn. map, info, status, help, save are free (don't cost actions).

Command	Description
map	Show world map
info <territory>	Show territory details & neighbors
status	Show your resources and army count
move <from> <to> [n]	Move n units between territories (all if omitted)
recruit <territory> <n>	Recruit n units at a territory
attack <from> <to>	Attack enemy territory from yours
build <territory> <type>	Build walls/barracks/market
next	End turn early
save [slot]	Save game
ally <faction>	Propose alliance
peace <faction>	Propose peace treaty
trade <faction> <n> <res> for <res>	Trade resources
diplo	View diplomatic relations
help	Show commands
quit	Exit

Maps

Map	Territories	Factions	Style
The Mainland	12	6 factions	Classic continental war
The Shattered Isles	14	6 factions	Island chain with chokepoints

Factions

The Mainland:

Faction	Personality	Strengths
🔴 Iron Legion	Aggressive	High stone, strong start
🟢 Green Pact	Defensive	High food & wood
🟡 Sand Empire	Mercantile	High gold reserves
🟣 Void Covenant	Diplomatic	Mountain fortress, fertile south
🔵 Frost Wardens	Defensive	Stone-rich northern highlands
🔴 Crimson Horde	Aggressive	Scrappy eastern raiders

The Shattered Isles:

Faction	Personality	Strengths
🔵 Tide Lords	Mercantile	High gold & food, coastal power
🔵 Storm Kin	Aggressive	High wood & stone, mountain base
🔴 Flame Brood	Aggressive	Massive stone, volcanic islands
🟣 Mist Walkers	Diplomatic	Balanced resources, forest cover
🟢 Deep Ones	Defensive	Forest & mountain, hidden islands
🟡 Wraith Fleet	Aggressive	Gold-rich, sunken city raiders

Resources

• 💰 Gold — Recruit armies (3 per unit)
• 🍖 Food — Recruit + army upkeep (2 per unit)
• 🪵 Wood — Build structures
• 🪨 Stone — Build structures

Buildings

Building	Cost	Effect
🧱 Walls	10🪵 15🪨	+0.3 defense bonus
🏛️ Barracks	8🪵 5🪨	Recruit costs 2💰 instead of 3💰
🏪 Market	10💰 5🪵 3🪨	+2💰 income per turn

AI Narrator (Optional)

Enable epic fantasy narration for battles, turn summaries, and victories. The game works perfectly without it.

Setup: Choose "Narrator Settings" from the main menu, then pick a provider:

Provider	Setup
Gemini (recommended)	Free API key from aistudio.google.com/apikey
Ollama	Install ollama.com, run ollama pull llama3, no key needed

Config saved at ~/.empire-cli/config.json.

Roadmap

• Core game loop with turn-based strategy
• 4 factions with AI personalities
• 8-territory map with adjacency
• Combat system with terrain bonuses
• Save/load game
• Action limit per turn (3 actions)
• AI Game Master (Gemini / Ollama) — optional epic narration
• Diplomacy system (alliances, trade, peace)
• Buildings (walls, barracks, markets)
• More maps & factions (The Mainland + The Shattered Isles)
• npm package (npx empire-cli)

Tech Stack

• TypeScript + Node.js 18+
• chalk (terminal colors)
• readline (input)
• JSON saves (~/.empire-cli/saves/)

Development

npm start      # Play the game
npm run build  # Compile TypeScript

License

MIT