ValheimCli

An experimental BepInEx plugin for a local command-line client. A shell-capable AI agent can call the client and parse JSON. No AI model or autonomous gameplay is bundled.

Version 0.1.0, MIT license. Windows Valheim 1.0.17 and Gale 1.23.1 were smoke-tested on 2026-10-10. Compilation references target Valheim 1.0.16. Other game versions/platforms and multiplayer behavior have not been verified in game.

What it does

• status: local player/world state, position, host and teleport permissions.
• players: currently loaded player objects, not the full server roster.
• teleport X Y Z --confirm: opt-in teleport of the local host's own living character.

Joining clients cannot teleport through this release, even if they are server admins. No admin grants, mining, building, combat, arbitrary console or shell commands, remote endpoint, world-file editing, or outbound AI connections.

Upgrading from the old name

This package replaces swear01-ValheimCliBridge. Uninstall the old package before installing ValheimCli; both contain the same bridge DLL. Keep your existing config and token private. The internal plugin name, DLL and configuration filenames still use ValheimCliBridge and are unchanged, so existing CLI commands continue to work.

Installation

Install this package and its BepInEx dependency with Gale, r2modman or Thunderstore Mod Manager, then launch the modded game. Only the computer running the CLI needs this bridge. It is a client game plugin; dedicated-server automation is not supported.

For manual installation, place ValheimCliBridge.dll in BepInEx/plugins/swear01-ValheimCliBridge/ in the game/profile. Exit the game before installing or replacing the DLL. Avoid installing two copies of the bridge.

The command-line client requires Node.js 22+ on the same computer as Valheim. Download valheim-agent-cli-0.1.0.tgz from GitHub Releases, then run:

npm install -g .\valheim-agent-cli-0.1.0.tgz
valheim status --profile "C:\path\to\your\profile"
valheim players --profile "C:\path\to\your\profile"

The CLI is distributed as a GitHub release tarball. Do not assume an npm registry release exists. Installing the CLI tarball has no install hooks; this mod package does not install Node.js or run npm for you.

On first game launch the bridge generates BepInEx/config/swear01.ValheimCliBridge.cfg and a random swear01.ValheimCliBridge.token. Keep the token local. Never share it or include it in exported profiles/modpacks. It inherits the profile folder's OS permissions; restrict that folder if other users share your computer.

Teleport permission

Teleport is off by default:

[Permissions]
AllowTeleport = false

With a configuration manager already installed, open F10 / Mods settings → Valheim CLI Bridge and toggle AllowTeleport. This permission updates immediately through the in-game UI. Alternatively, exit the game, edit the config, and relaunch. Bridge Enabled / Port changes require a restart.

valheim teleport 120 45 -230 --profile "C:\path\to\your\profile" --confirm

Coordinates are X, Y (height), Z. Use a known safe standing position in a test/backup world. Valid coordinate bounds do not guarantee safe ground. A state: "started" response is only the start of a teleport; query status afterward and check teleporting and actual position for arrival.

After a timeout or dropped connection, never automatically retry a write. Inspect the game state. Use --request-id <UUID> to preserve an operation ID. Started or uncertain write IDs are retained until restart, up to 256; reusing one is rejected. Restart clears this history, so this is not persistent exactly-once delivery.

Connection and removal

The bridge listens only on 127.0.0.1:28761 and authenticates every request with the profile token. It exposes no LAN/Internet service. Do not forward the port. For a custom config Port, pass the same port via CLI --port.

If the CLI cannot connect, confirm the correct modded profile is running and the bridge loaded. A successful BepInEx load alone does not prove that the bridge listener started; inspect the log if it fails. If the token is lost, corrupted or exposed, stop the game, delete only its token file and restart to regenerate it. To remove the bridge, exit Valheim and remove its plugin folder or uninstall this mod in the manager.

Verified scope

Real Windows game smoke tests used a copied v20 QoL profile and a new character/world: 138 successful status requests across two rounds, including 8 concurrent requests per round; players; rejection/recovery for invalid authentication, unsupported operations and default-disabled teleport; one approximately 3 m teleport back to an observed safe position, confirmed by arrival status; duplicate-write rejection; logout/re-entry and local world saving. The tested DLL SHA-256 is 859297b57d1566c5d3802d68c8154653523b8d59118331fa7b9d44e65c7ae552.

Automated protocol/dispatcher checks and Node-to-C# integration also pass. Second-player scenarios, distant/unknown terrain, multiplayer map sync, multi-hour endurance and memory leaks remain untested. This release is experimental.

Source, full protocol details and issue reports: swear01/valheim-cli.