teslo-cli

JSON-first CLI wrapper for teslo.

It is designed to be easy to use from a terminal, scripts, and AI agents:

• one command per match type
• JSON in, JSON out
• stable machine-readable errors
• minimal runtime dependencies

Install

npm install -g teslo-cli

Run without installing globally:

npx teslo-cli duel --input '{"players":[{"id":"1","elo":1000},{"id":"2","elo":900}],"winner":"1"}'

Quickstart

Duel

teslo duel --input '{"players":[{"id":"1","elo":1000},{"id":"2","elo":900}],"winner":"1"}'

Free-for-All

teslo free-for-all --input '{"players":[{"id":"1","elo":1000},{"id":"2","elo":950},{"id":"3","elo":900}],"ranking":["1","2","3"]}'

Team Duel

teslo team-duel --input '{"teams":[{"id":"red","players":[{"id":"r1","elo":1000},{"id":"r2","elo":950}]},{"id":"blue","players":[{"id":"b1","elo":980},{"id":"b2","elo":970}]}],"winner":"red"}'

Team Free-for-All

teslo team-free-for-all --input '{"teams":[{"id":"red","players":[{"id":"r1","elo":1000}]},{"id":"blue","players":[{"id":"b1","elo":980}]},{"id":"green","players":[{"id":"g1","elo":960}]}],"ranking":["red","blue","green"]}'

Input Modes

teslo-cli accepts exactly one input source:

• --input <json>
• --file <path>
• stdin

File input

teslo duel --file ./match.json

Stdin input

echo '{"players":[{"id":"1","elo":1000},{"id":"2","elo":900}],"winner":"1"}' | teslo duel

Commands

teslo duel

Payload:

{
  "players": [
    { "id": "1", "elo": 1000 },
    { "id": "2", "elo": 900 }
  ],
  "winner": "1",
  "kFactor": 32
}

teslo free-for-all

Payload:

{
  "players": [
    { "id": "1", "elo": 1000 },
    { "id": "2", "elo": 950 },
    { "id": "3", "elo": 900 }
  ],
  "ranking": ["1", "2", "3"],
  "kFactor": 32,
  "minPlayers": 2,
  "maxPlayers": 256
}

teslo team-duel

Payload:

{
  "teams": [
    {
      "id": "red",
      "players": [
        { "id": "r1", "elo": 1000 },
        { "id": "r2", "elo": 950 }
      ]
    },
    {
      "id": "blue",
      "players": [
        { "id": "b1", "elo": 980 },
        { "id": "b2", "elo": 970 }
      ]
    }
  ],
  "winner": "red",
  "kFactor": 32
}

teslo team-free-for-all

Payload:

{
  "teams": [
    { "id": "red", "players": [{ "id": "r1", "elo": 1000 }] },
    { "id": "blue", "players": [{ "id": "b1", "elo": 980 }] },
    { "id": "green", "players": [{ "id": "g1", "elo": 960 }] }
  ],
  "ranking": ["red", "blue", "green"],
  "kFactor": 32,
  "minTeams": 2,
  "maxTeams": 256
}

Output

Default output is pretty-printed JSON.

teslo duel --input '{"players":[{"id":"1","elo":1000},{"id":"2","elo":900}],"winner":"1"}'

[
  {
    "id": "1",
    "elo": 1012
  },
  {
    "id": "2",
    "elo": 888
  }
]

Compact JSON:

teslo duel --format json --input '{"players":[{"id":"1","elo":1000},{"id":"2","elo":900}],"winner":"1"}'

Errors

Errors are emitted as JSON to stderr.

{
  "error": {
    "name": "MATCH_ERROR",
    "message": "Player not found"
  }
}

AI Agent Usage

The simplest integration pattern is stdin plus JSON output:

echo '{"players":[{"id":"1","elo":1000},{"id":"2","elo":900}],"winner":"1"}' | teslo duel --format json

That makes the CLI easy to call from automation without parsing human-oriented text.

Development

This project uses Bun for local development.

bun install
bun run build
bun test

Watch mode:

bun run dev --help

Programmatic API

teslo-cli also exports thin programmatic wrappers:

• runDuel
• runFreeForAll
• runTeamDuel
• runTeamFreeForAll

License

MIT