pokemon-damage-calc-cli

Command-line interface for Pokémon damage calculations powered by @smogon/calc. Supports singles and doubles, human-friendly flags, Showdown set paste, and a lossless JSON contract for agents.

Binary: pkmn-calc · Package: @professorragna/pokeapi-cli on npm

Installation

# Global install
npm i -g @professorragna/pokeapi-cli

# Run without global install
npx @professorragna/pokeapi-cli pkmn-calc --help

Prerequisites

• Node.js >= 18.17

Verify

pkmn-calc --version
pkmn-calc --help

Quick start

pkmn-calc -a "Chien-Pao" -m "Icicle Crash" -d "Flutter Mane" \
  --attacker-nature Jolly --attacker-evs "252 Atk / 252 Spe / 4 Def" \
  --defender-nature Modest --defender-evs "164 HP / 100 Def"

pkmn-calc --text -a Pikachu -d Charizard -m Thunderbolt

pkmn-calc --champions -a Pikachu -d Charizard -m Thunderbolt \
  --attacker-evs "32 SpA / 32 Spe"

Pokémon Champions

Use --champions (or -g 0 / "gen": 0 in JSON) for Pokémon Champions calcs.

| Format | Max EV per stat | Max EV total | |--------|-----------------|--------------| | Pokémon Champions (gen: 0) | 32 | 66 | | Standard (gen: 1-9) | 252 | 510 |

Champions EVs add directly to stats (no /4); IVs are ignored. Over-cap spreads are rejected with validation-error.

This package vendors a Champions-capable @smogon/calc build (vendor/smogon-calc-0.11.0.tgz) until an official npm release includes gen 0.

Input modes

Input precedence:

1. --json or piped stdin (full request object)
2. --attacker-set / --defender-set (Showdown set paste)
3. Flags (-a, -d, -m, per-side options, field flags)

Flags (common)

| Flag | Description | |------|-------------| | -a, --attacker <species> | Attacking Pokémon | | -d, --defender <species> | Defending Pokémon | | -m, --move <name> | Move used by attacker | | -g, --gen <n> | Generation (0=Champions, 1-9; default: 9) | | --champions | Pokémon Champions format (gen 0) | | --game-type <Singles\|Doubles> | Game type (default: Singles) | | --doubles | Shorthand for Doubles | | --attacker-evs, --defender-evs | EV spread, e.g. "252 Atk / 4 Spe" | | --attacker-set, --defender-set | Showdown set paste | | --json <object> | Full request JSON | | -f, --format <json\|text\|both> | Output format (default: json) | | --text | Shorthand for --format text |

See pkmn-calc --help for weather, terrain, screens, ruin abilities, crit, Z/Max, and other field flags. Long-tail field conditions can be passed via --json.

JSON request

{
  "gen": 9,
  "attacker": {
    "species": "Chien-Pao",
    "level": 50,
    "nature": "Jolly",
    "evs": { "atk": 252, "spe": 252, "def": 4 }
  },
  "defender": {
    "species": "Flutter Mane",
    "level": 50,
    "nature": "Modest",
    "evs": { "hp": 164, "def": 100 }
  },
  "move": { "name": "Icicle Crash" },
  "field": { "gameType": "Singles" }
}

pkmn-calc --json '{"gen":9,"attacker":{"species":"Pikachu"},"defender":{"species":"Charizard"},"move":{"name":"Thunderbolt"},"field":{}}'
echo '{"gen":9,...}' | pkmn-calc

Output

Default (--format json): structured JSON to stdout:

• desc — Showdown-style calc line
• damage — { min, max, minPercent, maxPercent, rolls }
• koChance — { text, chance, n }
• recovery, recoil — text summaries
• attacker, defender — resolved stats and spread
• move, field — resolved move and field context

--format text: prints only the desc line.

Errors: JSON to stderr with error.code, error.message, and non-zero exit code.

pkmn-calc -a "Chien-Pao" -m "Icicle Crash" -d "Flutter Mane" \
  --attacker-nature Jolly --attacker-evs "252 Atk / 252 Spe / 4 Def" \
  --defender-nature Modest --defender-evs "164 HP / 100 Def" \
  | jq '.damage'

Agent skill

This CLI ships an agent skill at skills/pokemon-damage-calc-cli/SKILL.md.

Install with the skills CLI:

npx skills add jpbullalayao/pokemon-damage-calc-cli

Development

npm install
npm run build
node bin/pkmn-calc.js --help
npm test

Releasing

Pushing a semver tag (v*) triggers .github/workflows/publish.yml to build, test, and publish to npm with provenance.

Cut a release

The tag must match the version in package.json (e.g. tag v0.2.0 requires "version": "0.2.0").

npm version patch   # or minor / major — updates package.json and package-lock.json
git push origin main
git push origin vX.Y.Z

The workflow validates the tag, runs npm ci && npm test, then publishes. Confirm at npmjs.com/package/@professorragna/pokeapi-cli.

Exit codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Generic / not-found error | | 2 | Usage error | | 4 | Validation error (bad species, move, JSON) | | 5 | API error | | 6 | Network error |

License

MIT