Dota Agent CLI

dota-agent-cli

Description

Live provider-backed Dota 2 knowledge and live-match CLI for agent-friendly hero, item, match state, and source lookups.

This skill uses live providers for hero, item, and match discovery. OpenDota is the default public source. STRATZ is modeled as an optional richer provider and status surface, but this revision does not yet resolve encyclopedia hero/item indexes through STRATZ.

The default publish channel is the repository's own GitHub Release. Released archives are expected to ship with release-evidence.json, .release-manifest.json, and the clone-first install helper scripts/install-current-release.sh.

Prerequisites

• A working Rust toolchain (rustup, cargo) to compile and test the binary.
• Network access is required for fresh live-provider reads and cache warming.
• No additional system packages are required for the default build.

Invocation

dota-agent-cli [OPTIONS] <COMMAND>
dota-agent-cli help [COMMAND_PATH ...] [--format yaml|json|toml]
dota-agent-cli run [OPTIONS] <QUERY>
dota-agent-cli show <hero|item> <NAME> [OPTIONS]
dota-agent-cli list <hero|item> [OPTIONS]
dota-agent-cli source <status|warm> [OPTIONS]
dota-agent-cli match live [OPTIONS]
dota-agent-cli match show <MATCH_ID> [OPTIONS]
dota-agent-cli match recent [OPTIONS]
dota-agent-cli daemon <start|stop|restart|status> [OPTIONS]
dota-agent-cli daemon run [OPTIONS]
dota-agent-cli paths [OPTIONS]
dota-agent-cli context <show|use> [OPTIONS]
dota-agent-cli --repl [OPTIONS]

The canonical agent-facing contract uses the bare command name shown above. cargo run -- ... and ./target/release/dota-agent-cli ... are development and release-verification forms only.

Global Options

Commands

Input

• run requires one positional <QUERY> argument.
• show requires a <hero|item> type and a <NAME>.
• list requires a type and accepts optional filters such as --tag.
• run, show, and list accept --source and --freshness.
• show also accepts --overlay basic|stats|full.
• list also accepts --sort name|popularity|winrate|updated.
• source status accepts --source and --freshness.
• source warm accepts --source, --scope, and --force.
• match live accepts --source, --freshness, --limit, --league-id, and --min-mmr.
• match show requires a positional <MATCH_ID> and accepts --source, --freshness, and --expand.
• match recent accepts --player-id, --hero, --source, --freshness, --limit, --sort, and --won.
• --repl starts an interactive session; it accepts --format as a global option.

Output

Standard command results are written to stdout. Errors and diagnostics are written to stderr.

Help Channels

• --help is the plain-text help channel. It always prints text and exits 0.
• help is the structured help channel. It supports yaml, json, and toml, with YAML as the default.
• Top-level invocation and non-leaf invocation such as context display plain-text help automatically and exit 0.

Structured Results

The default one-shot result format is YAML.

Example run result:

query: blink initiation
requested_type: item
match_count: 1
source:
  requested_source: opendota
  resolved_sources:
    - opendota
results:
  - kind: item
    name: Blink Dagger

Example source status result:

requested_source: auto
providers:
  - provider: opendota
    reachability: reachable
  - provider: stratz
    auth: missing

GitHub Release Installation

• Repo-native GitHub Release is the primary distribution path for this skill.
• Released checkouts should be installable with ./scripts/install-current-release.sh <version>.
• Release evidence is expected in release-evidence.json, with .release-manifest.json mirroring the same released version.

Runtime Directories and Active Context

• paths exposes config, data, state, cache, and optional logs.
• Defaults are user-scoped unless explicitly overridden.
• context show exposes the persisted and effective Active Context.
• Explicit selectors on run, show, or list override the persisted Active Context for that invocation only.

Managed Daemon Contract

• Public daemon control uses daemon start, daemon stop, daemon restart, and daemon status.
• Daemonizable leaf commands (run, show, list, match live, match show, match recent) accept --via local|daemon.
• --ensure-daemon can auto-start or reuse the managed daemon before a daemon-routed leaf command runs.
• Local-only surfaces such as help, source, paths, context, and daemon reject daemon routing with structured errors.
• The contract standardizes only managed background daemon mode.
• Attached foreground execution is out of scope.
• daemon run exists only as an internal managed-process entrypoint.
• daemon start, daemon restart, and daemon run accept transport/auth/TLS binding options for the managed process surface.
• Managed daemon artifacts persist under the runtime state directory's daemon/ subtree.

REPL Mode

• Start interactive mode with --repl.
• The prompt is dota-agent-cli> and is written to stderr.
• help inside the REPL is plain text only and explains available commands, context inspection controls, and output behavior.
• Each input line is handled as one command and the result is written to stdout. Default session output is human-readable YAML; explicit --format json or --format toml preserves structured output.
• Command history persists under the runtime state directory (repl_history.txt).
• Tab completion is available for command names, option names, and visible Active Context values.
• exit, quit, or EOF end the session with exit code 0.
• Per-command errors are written to stderr and do not terminate the REPL.

Errors

Structured errors preserve the selected output format and include stable code and message fields.

Examples

$ dota-agent-cli run blink initiation --type item --source opendota --freshness recent
$ dota-agent-cli show hero Axe --overlay stats
$ dota-agent-cli list item --tag vision
$ dota-agent-cli source status --source auto --freshness recent
$ dota-agent-cli source warm --source opendota --scope indexes --force
$ dota-agent-cli match live --freshness live --limit 5
$ dota-agent-cli match show 7890123456 --expand
$ dota-agent-cli match recent --player-id 12345 --limit 10
$ dota-agent-cli match recent --player-id 12345 --won --sort kills
$ dota-agent-cli context use --selector role=support --selector lane=safelane
$ dota-agent-cli --repl
$ dota-agent-cli --repl --format json