hermes-rank

Submit your Hermes Agent achievements to the public leaderboard at hermes-rankings.com.

Install + run

npx hermes-rank submit

You'll be prompted to pick a public handle. Skip the prompt with the flag:

npx hermes-rank submit --handle your-name

Or install globally:

npm install -g hermes-rank
hermes-rank submit

What happens on first run

1. The CLI reads your local state.json + scan_snapshot.json from the Hermes Achievements plugin (no other files, no prompts, no code).
2. You're asked to pick a public handle (3–40 chars, lowercase letters, digits, hyphens). The auto-suggestion is the default — just hit Enter to accept it. Skip the prompt entirely with --handle your-name.
3. It opens hermes-rankings.com/cli/verify in your browser. Click the Cloudflare Turnstile widget once.
4. The CLI gets an API key, saves it to ~/.hermes-rank/identity.json (chmod 600), and uploads your achievements.
5. You see your handle, score, and rank. Subsequent runs are silent.

Commands

hermes-rank submit                          # upload (registers on first run)
hermes-rank submit --handle <name>          # first-run with chosen handle, no prompt
hermes-rank status                          # current handle, score, last submit
hermes-rank rename <new-handle>             # change handle later (2h cooldown)
hermes-rank doctor                          # diagnose paths + server reachability
hermes-rank link-github                     # attach GitHub for the Verified ring
hermes-rank reset                           # wipe local identity (with confirm)

Where the files live

The CLI looks for the standard Hermes Achievements plugin paths:

macOS / Linux  ~/.hermes/plugins/hermes-achievements/
Windows        %USERPROFILE%\.hermes\plugins\hermes-achievements\
Override       export HERMES_HOME=/path/to/.hermes

Run hermes-rank doctor to confirm what the CLI sees.

Keep your rank fresh

After first run, every hermes-rank submit is a single HTTP POST — no browser. Recommended cadence is once a week (achievements only change at session boundaries; weekly is plenty and gentle on the server). You can also just run it manually whenever you want a fresh push.

# crontab (macOS / Linux): every Sunday at 3am
0 3 * * 0 /usr/local/bin/hermes-rank submit >/dev/null 2>&1

Full install + scheduling guide: https://www.hermes-rankings.com/docs/install

What we send

Only your unlocked achievement IDs, tiers, and timestamps — derived from the files Hermes already writes locally. No prompts, code, file contents, or session text leaves your machine.

How we keep the leaderboard clean: https://www.hermes-rankings.com/docs/anti-abuse

License

MIT.