Skip to content

CLI Reference ​

The @valoranchi/riot-client package includes the riotclient command-line executable. It connects to the local Riot Client session and writes structured JSON to standard output.

Overview ​

Commands can be invoked directly if installed globally, or via npx:

bash
riotclient <command> [options]
npx @valoranchi/riot-client <command> [options]

All mutations run in dry-run mode by default. Pass --yes to authorize live changes, and both --yes and --confirm for operations that alter currency balances, dodge queues, or leave active matches.

Exit Codes ​

CodeSymbolMeaning
0SUCCESSSuccessful execution. Output JSON is printed to stdout.
1UNEXPECTEDUnhandled error or runtime crash.
2RIOT_CLIENT_NOT_RUNNINGRiot Client lockfile was not found. Start Riot Client and log in.
3RIOT_CLIENT_NOT_READYRiot Client is running but local loopback API is not yet ready.
4REGION_UNKNOWNActive region and shard could not be determined.
5RIOT_API_ERRORRemote Riot PVP service returned an HTTP error.
6VALIDATIONLocal pre-flight validation check failed.

Command Reference ​

The command and option tables below are generated automatically at build time from the source definition in src/cli.ts.

Account ​

CommandDescription
whoamiPrint signed-in player profile and region
owned-itemsPrint owned inventory items
collection-valueCalculate estimated VP and Radianite value of owned collection
loadoutPrint currently equipped loadout
walletPrint VP, Radianite, and Kingdom Credits balances
xpPrint account level, XP progression and recent match XP history
contractsPrint progression across agent, battlepass and event contracts
missionsPrint active daily and weekly missions and objectives
masteryPrint mastery level and points of every agent, most points first
dailiesPrint the four daily checkpoints and what each queue adds
penaltiesPrint active penalties and restrictions
favouritesPrint favorited weapon skins
sessionPrint current client session loop state and playtime
configPrint shared client configuration mapping
clientPrint client identity, locale, region, and Valorant running state
settingsPrint cloud player settings (--raw for unprocessed dump)
settings-saveSave player settings from JSON file (<file.json>, requires --yes --confirm)
equipEquip skins, buddies, sprays, card, title, border, flex (dry-run, --yes to apply)
equip-collectionEquip a collection of skins (<skinUuid,...>) (dry-run, --yes to apply)
loadout-exportExport current loadout as a preset JSON
loadout-diffCompare current loadout against preset JSON file (<preset.json>)
loadout-applyApply loadout preset from JSON file (<preset.json>, dry-run, --yes to apply)
contract-activateActivate an agent contract (<uuid>) (dry-run, --yes to apply)
favourite-addAdd skin to favourites (<skin>) (dry-run, --yes to apply)
favourite-removeRemove skin from favourites (<skin>) (dry-run, --yes to apply)
privacyUpdate account privacy toggles (--badge on|off, --leaderboard on|off)

Social ​

CommandDescription
friendsPrint friends roster and presence
friend-requestsPrint incoming and outgoing friend requests
blockedPrint blocked players
conversationsPrint whisper and match chat conversations
messagesPrint chat messages (filter with --cid <id>)
participantsPrint chat participants (filter with --cid <id>)
sendSend chat message (--to <puuid|name#tag|cid> --text <msg>)
friend-requestSend friend request (<name#tag>)
friend-acceptAccept friend request (<puuid>)
friend-declineDecline friend request (<puuid>)
friend-cancelCancel friend request (<puuid>)
friend-removeRemove friend (<puuid>)
blockBlock player (<puuid|name#tag>)
unblockUnblock player (<puuid>)

Store ​

CommandDescription
storePrint storefront (daily, night market, bundles, accessories)
store-historyPrint recorded daily store rotations [--days <n>]
store-seenPrint when a skin was last seen in daily store (<skin>)
offersPrint full item offers catalog and pricing
order <id>Print store order details
night-market-revealReveal night market offers (dry-run, --yes to apply)
buyPurchase offer or bundle (--offer <id> | --bundle <id>, requires --yes --confirm)
wishlistPrint skin wishlist or manage items (add <skin>, remove <skin>, check)

Matches ​

CommandDescription
matchesPrint recent match history summaries
matches-syncSynchronize match history to local cache [--pages <n>]
match <id>Print full match details by ID
match-progress <id>Print the mastery points, XP and Kingdom Credits a match gave
mmrPrint current rank, rating, and MMR breakdown
rank-historyPrint competitive rating adjustments and tier changes
livePrint live pregame or in-game lobby status and loadouts
matches-for <puuid>Print recent match history summaries for player
mmr-for <puuid>Print rank, rating, and MMR for player
rank-history-for <puuid>Print competitive updates for player
leaderboardPrint competitive leaderboard [--season] [--start] [--size] [--query]
contentPrint active act, episode and live events
premierPrint premier eligibility, roster, and season info
trendPrint competitive rating streak, net RR gains, and climbing pace
summaryPrint player performance summary across recent matches [--count n] [--queue q]
play-sessionPrint today's play session summary [--since <iso>]
instalock <agent>Auto-lock an agent in pregame [--on-map Map=Agent...] [--fallback a...] [--delay n] [--select] [--once] [--yes]
assess [puuid]Assess player rank anomalies, streaks, and warning flags
agent-selectSelect an agent in pregame (<uuid|name>) (dry-run, --yes to apply)
agent-lockLock in an agent in pregame (<uuid|name>) (dry-run, --yes to apply)
dodgeDodge pregame agent select (requires --yes --confirm)
leave-matchLeave active in-game match (requires --yes --confirm)

Party ​

CommandDescription
partyPrint current party details and members
queuesPrint matchmaking queue configurations
custom-game-configsPrint custom game configuration options
party-inviteInvite player to party (<name#tag>)
party-kickKick member from party (<puuid>)
party-promotePromote member to party owner (<puuid>)
party-codeGenerate or revoke party invite code [--revoke]
party-joinJoin party by invite code or party ID (<partyId|code>)
party-invitesPrint incoming party invites
party-requestsPrint incoming party join requests
party-decline-inviteDecline party invite (<id>) (dry-run, --yes to apply)
party-requestRequest to join party (<partyId>) (dry-run, --yes to apply)
party-decline-requestDecline party join request (<id>) (dry-run, --yes to apply)
custom-gameConvert party into a custom game (dry-run, --yes to apply)
custom-game-settingsConfigure custom game (--map <name> --mode <name> [--server <id>] [--rule k=v...])
custom-game-teamSet member custom game team (<puuid> <team>) (dry-run, --yes to apply)
custom-game-startStart custom game match (dry-run, --yes to apply)
custom-game-balanceBalance custom game teams (dry-run, --yes to apply)
party-defaultSet party default queue (<queue>) (dry-run, --yes to apply)
party-serversSet preferred game servers (<id,...>) (dry-run, --yes to apply)
party-moderatorSet member moderator status (<puuid> on|off) (dry-run, --yes to apply)
party-refreshRefresh party member pings and identity (dry-run, --yes to apply)
party-readySet party ready state (on|off)
party-queueChange party queue (<queue>)
party-accessSet party accessibility (open|closed)
party-startStart party matchmaking
party-stopStop party matchmaking
party-leaveLeave current party

Raw (unsupported) ​

CommandDescription
localSend raw request to local Riot client API (<get|post|put|delete> <path> [--body json])
riotSend raw request to remote Riot game servers (<get|post|put|delete> <url> [--body json])

Events ​

CommandDescription
watchStream real-time events as JSON lines until interrupted
watch storeStream store wishlist rotation hits until interrupted [--webhook <url>] [--interval <min>]
watch matchStream match lifecycle events until interrupted [--webhook <url>]
watch-matchStream match lifecycle events until interrupted [--webhook <url>]
watch-friendsStream friend activity and presence events until interrupted

Server ​

CommandDescription
dashboardStart local server and open interactive web dashboard
serveStart local HTTP server with SSE events and OpenAPI docs [--port 47800] [--host 127.0.0.1] [--allow-remote]
mcpStart Model Context Protocol (MCP) server over stdio for AI assistants

Official ​

CommandDescription
official account <name#tag>Print player PUUID and active shard
official matches <name#tag>Print player match history [--queue <q>] [--count <n>]
official match <id>Print full match details (--shard <shard> [--self <puuid>])
official leaderboardPrint competitive leaderboard (--shard <shard> [--act <id>] [--start <n>] [--size <n>])
official statusPrint platform status and maintenance alerts (--shard <shard>)
official summary <name#tag>Print player performance summary [--queue <q>] [--count <n>]
official profile <name#tag>Print player scouting profile [--count <n>]

Options ​

OptionDescription
--yesExecute write command (default is dry-run)
--confirmConfirm write action (required with buy, dodge, leave-match, settings-save)
--offer <id>Store offer ID to purchase
--bundle <id>Store bundle ID to purchase
--badge <on|off>Hide or show act rank badge
--leaderboard <on|off>Anonymize or reveal leaderboard presence
--season <uuid>Season ID for leaderboard
--start <n>Leaderboard starting index
--size <n>Leaderboard page size (max 510)
--query <text>Leaderboard player search query
--revokeRevoke party invite code (used with party-code)
--to <target>Message recipient (puuid, name#tag, or cid)
--text <msg>Message text
--gun <spec>Gun to equip: <weapon>=<skin>[:level[:chroma]] (repeatable)
--buddy <spec>Buddy to equip: <weapon>=<buddy|none> (repeatable)
--spray <spec>Spray to equip: <slot>=<uuid|none> (repeatable)
--card <uuid>Player card UUID
--title <uuid>Player title UUID
--flex <uuid|none>Flex item UUID or none
--border <uuid>Level border UUID
--incognito <on|off>Enable or disable incognito
--hide-level <on|off>Hide or show account level
--count <n>Number of matches or rank history entries to fetch
--queue <queue>Queue filter (e.g. competitive, unrated)
--ranksFetch MMR and rank for each player in live match
--no-loadoutsSkip fetching player loadouts in live match
--map <name>Map name or path for custom game
--mode <name>Game mode name or path for custom game
--server <id>Server pod ID for custom game
--rule <spec>Game rule override: <name>=<value> (repeatable)
--body <json>JSON request body for local and riot raw commands
--only <events>Comma-separated list of event names to print
--rawInclude raw client event frames or unformatted settings
--cid <id>Conversation ID for filtering messages or participants
--api-key <key>Riot Developer API key (or RIOT_API_KEY env)
--shard <shard>Riot shard (na, latam, br, eu, ap, kr)
--self <puuid>Player PUUID for self perspective in official match
--act <uuid>Act or season UUID for official leaderboard
--language <lang>Catalogue language (default: en-US)
--cache <seconds>Reuse Riot responses younger than this many seconds
--no-official-cacheDisable official match disk cache
--webhook <url>Webhook URL for store or match alerts (Discord or generic)
--interval <min>Check interval in minutes for store watcher
--since <iso>ISO timestamp cutoff for play session
--on-map <m=a>Agent for a map in instalock, e.g. Haven=Omen (repeatable)
--fallback <agent>Fallback agent for instalock (repeatable)
--delay <ms>Delay before selecting/locking in milliseconds (0-10000)
--selectSelect agent without locking in instalock
--onceStop instalock after first match
--port <n>Port to bind HTTP server (default: 47800)
--host <ip>Host address to bind HTTP server (default: 127.0.0.1)
--allow-remoteAllow binding HTTP server to non-loopback address
--prettyPretty-print JSON output
--helpShow usage instructions
--versionShow version number

Not affiliated with Riot Games