Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bernardopg/steam-utility-multiplataform

Cross-platform Steam utility CLI for discovery, compatibility reports, ownership checks, and Steamworks achievement/stat commands.
https://github.com/bernardopg/steam-utility-multiplataform

cli cross-platform csharp dotnet gaming linux proton steam steamworks windows

Last synced: 3 months ago
JSON representation

Cross-platform Steam utility CLI for discovery, compatibility reports, ownership checks, and Steamworks achievement/stat commands.

Awesome Lists containing this project

README 

          
# steam-utility-multiplataform



[![Version](https://img.shields.io/github/v/release/bernardopg/steam-utility-multiplataform?display_name=tag&sort=semver)](https://github.com/bernardopg/steam-utility-multiplataform/releases)

[![CI](https://github.com/bernardopg/steam-utility-multiplataform/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bernardopg/steam-utility-multiplataform/actions/workflows/ci.yml)

[![.NET](https://img.shields.io/badge/10-512BD4?logo=dotnet&logoColor=fff)](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)

[![Steam](https://img.shields.io/badge/Steam-%23000000.svg?logo=steam&logoColor=white)](https://store.steampowered.com/)

[![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11&logoColor=white)](docs/RELEASE.md)

[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](docs/RELEASE.md)



Cross-platform .NET 10 CLI port of the original [`zevnda/steam-utility`](https://github.com/zevnda/steam-utility), focused on Linux and Windows.



This project lets you:

- discover Steam installations, library folders, and installed apps;

- inspect Proton/compatdata and compatibility-tool assignments;

- summarize Steam environment state in text or JSON;

- query ownership through the native Steam client;

- read and mutate achievements/stats through Steamworks;

- keep an app in an active idle session.



## What this project is



`steam-utility-multiplataform` is a multiplatform reimplementation of the upstream `steam-utility` command surface in C#/.NET 10.



It combines two main capabilities:



1. Discovery/reporting

   - detect Steam roots

   - parse VDF files

   - enumerate library folders

   - read app manifests

   - inspect compatdata and compatibility tools

   - generate structured reports



2. Steam-native operations

   - check ownership through the running Steam client

   - read achievement/stat data

   - mutate achievements/stats

   - keep a game session idle



## Current platform status



| Platform | Status | Notes |

| --- | --- | --- |

| Linux | Supported and validated | Real Steam-session validation was executed successfully. See [REPORT_REAL_VALIDATION_TEST_LINUX.md](REPORT_REAL_VALIDATION_TEST_LINUX.md). |

| Windows | Supported in code and release pipeline | Runtime services and release artifacts exist, but dedicated Windows validation for locator/loaders/resolvers is still a known gap. |

| macOS | Not supported | No macOS runtime implementation is currently shipped. |



## Release assets



GitHub releases currently publish self-contained single-file binaries for:

- `linux-x64`

- `linux-arm64`

- `win-x64`



Each release also includes SHA-256 checksums generated by the release workflow.



## Requirements



### For source usage

- .NET 10 SDK

- Steam installed on Linux or Windows



### For Steam-native commands

The following commands require a real Steam session:

- `check_ownership`

- `idle`

- `get_achievement_data`

- `unlock_achievement`

- `lock_achievement`

- `toggle_achievement`

- `unlock_all_achievements`

- `lock_all_achievements`

- `update_stats`

- `reset_all_stats`



For those commands, Steam should be running and the user should be logged in.



## Installation



### Option 1: Run from source

```bash

dotnet restore

dotnet build steam-utility-multiplataform.sln -c Release

```



### Option 2: Use a release binary

Download the latest archive from the [GitHub Releases page](https://github.com/bernardopg/steam-utility-multiplataform/releases), extract it, and run the published CLI binary for your platform.



## Quick start



### Build and validate locally

```bash

dotnet restore

dotnet build steam-utility-multiplataform.sln -c Release

dotnet run --project tests/SteamUtility.Tests -c Release

```



Note: the test project uses a custom test runner, so `dotnet run --project tests/SteamUtility.Tests -c Release` is the most direct validation path for the current repository.



### Basic discovery examples

```bash

# detect the Steam root

dotnet run --project src/SteamUtility.Cli -- detect



# list library folders

dotnet run --project src/SteamUtility.Cli -- libraries



# list installed apps

dotnet run --project src/SteamUtility.Cli -- apps



# generate a higher-level environment summary

dotnet run --project src/SteamUtility.Cli -- state-report



# same report with JSON output

dotnet run --project src/SteamUtility.Cli -- state-report --json

```



### Proton / compatibility examples

```bash

# list compatdata entries

dotnet run --project src/SteamUtility.Cli -- compatdata



# list discovered compatibility tools

dotnet run --project src/SteamUtility.Cli -- compat-tools



# list explicit compatibility mappings

dotnet run --project src/SteamUtility.Cli -- compat-mapping



# merge apps + compatdata + mappings into one report

dotnet run --project src/SteamUtility.Cli -- compat-report --json

```



### Steam-native examples

```bash

# check ownership for explicit AppIDs and write an upstream-compatible games.json

dotnet run --project src/SteamUtility.Cli -- check_ownership /tmp/games.json "[730,570,440]"



# read achievement/stat data

dotnet run --project src/SteamUtility.Cli -- get_achievement_data 440 /tmp/steam-utility-cache



# keep an app idle

dotnet run --project src/SteamUtility.Cli -- idle 440 "Team Fortress 2"



# mutate achievements/stats

dotnet run --project src/SteamUtility.Cli -- unlock_achievement 440 ACH_ID

dotnet run --project src/SteamUtility.Cli -- lock_achievement 440 ACH_ID

dotnet run --project src/SteamUtility.Cli -- toggle_achievement 440 ACH_ID

dotnet run --project src/SteamUtility.Cli -- unlock_all_achievements 440

dotnet run --project src/SteamUtility.Cli -- lock_all_achievements 440

dotnet run --project src/SteamUtility.Cli -- update_stats 440 "[{\"name\":\"STAT\",\"value\":100}]"

dotnet run --project src/SteamUtility.Cli -- reset_all_stats 440

```



## Command reference



### Discovery and reporting



| Command | Description | Live Steam required |

| --- | --- | --- |

| `detect` | Detect the local Steam installation path | No |

| `libraries` | List discovered Steam library folders | No |

| `apps` | List installed Steam apps from app manifests | No |

| `compatdata` | List per-app compatdata directories | No |

| `compat-tools` | List bundled and custom compatibility tools | No |

| `compat-mapping` | List explicit compatibility-tool mappings from `config.vdf` | No |

| `compat-report` | Merge apps, compatdata, and config mappings into one report | No |

| `state-report` | Summarize Steam library, compat, and user state files | No |



### Steam-native / upstream-parity commands



| Command | Description | Live Steam required |

| --- | --- | --- |

| `check_ownership` | Query owned apps through the native Steam client and write `games.json` | Yes |

| `idle` | Keep an app session active | Yes |

| `get_achievement_data` | Read and cache achievement/stat data for an app | Yes |

| `unlock_achievement` | Unlock one achievement | Yes |

| `lock_achievement` | Lock one achievement | Yes |

| `toggle_achievement` | Toggle one achievement | Yes |

| `unlock_all_achievements` | Unlock all achievements for an app | Yes |

| `lock_all_achievements` | Lock all achievements for an app | Yes |

| `update_stats` | Update stat values from a JSON payload | Yes |

| `reset_all_stats` | Reset all stats for an app | Yes |



## Global options



- `--json` — emit JSON output instead of text

- `--diagnostics` — emit additional diagnostic logging to stderr

- `--app-id ` — filter by a specific AppID where applicable

- `--match ` — case-insensitive text filter where applicable

- `--help` / `-h` — show command help



## Command aliases



The CLI accepts underscore and hyphen variants for selected commands:

- `check_ownership` / `check-ownership`

- `get_achievement_data` / `get-achievement-data`

- `unlock_achievement` / `unlock-achievement`

- `lock_achievement` / `lock-achievement`

- `toggle_achievement` / `toggle-achievement`

- `unlock_all_achievements` / `unlock-all-achievements`

- `lock_all_achievements` / `lock-all-achievements`

- `update_stats` / `update-stats`

- `reset_all_stats` / `reset-all-stats`



## JSON output contracts



The project currently has two JSON-output categories:



### Versioned report outputs

These are the structured discovery/report commands. Their output shape is treated as a versioned contract (currently schema version 1):

- `apps`

- `libraries`

- `compatdata`

- `compat-tools`

- `compat-mapping`

- `compat-report`

- `state-report`



### Compatibility-first legacy outputs

These commands intentionally preserve legacy/upstream-oriented payload behavior and should not yet be treated as stable versioned report contracts:

- `check_ownership`

- `idle`

- `get_achievement_data`

- achievement/stat mutation commands



More detail lives in [docs/JSON_OUTPUTS.md](docs/JSON_OUTPUTS.md).



## Repository structure



- `src/SteamUtility.Core` — core models, scanners, parsers, platform services, and native interop

- `src/SteamUtility.Cli` — CLI entrypoint and command dispatch

- `tests/SteamUtility.Tests` — custom automated test runner and regression coverage

- `docs/` — deeper documentation for release, parity, platform behavior, and JSON outputs

- `TODO.md` — live project checklist and known remaining work



## Documentation index



- [docs/LIBRARY_DISCOVERY.md](docs/LIBRARY_DISCOVERY.md)

- [docs/PROTON_AND_COMPATDATA.md](docs/PROTON_AND_COMPATDATA.md)

- [docs/WINDOWS_DEPENDENCIES.md](docs/WINDOWS_DEPENDENCIES.md)

- [docs/CLI_PARITY_MATRIX.md](docs/CLI_PARITY_MATRIX.md)

- [docs/LINUX_REAL_STEAM_VALIDATION.md](docs/LINUX_REAL_STEAM_VALIDATION.md)

- [docs/PORTING_PLAN.md](docs/PORTING_PLAN.md)

- [docs/JSON_OUTPUTS.md](docs/JSON_OUTPUTS.md)

- [docs/RELEASE.md](docs/RELEASE.md)

- [CHANGELOG.md](CHANGELOG.md)

- [REPORT_REAL_VALIDATION_TEST_LINUX.md](REPORT_REAL_VALIDATION_TEST_LINUX.md)



## Known limitations



- Linux is the most thoroughly validated platform today.

- Windows support exists in code and release artifacts, but dedicated validation for some Windows-specific locator/loader paths is still pending.

- Proton/compatdata-oriented commands are primarily meaningful on Linux/Proton environments and may legitimately return little or no data on Windows.

- Steam-native commands depend on the target app exposing the necessary Steamworks data and on a valid local Steam session.

- macOS is not currently supported.



## Relationship to the upstream project



This repository is based on the original [`zevnda/steam-utility`](https://github.com/zevnda/steam-utility) and aims to preserve the upstream command surface while adding a modern .NET >=8, cross-platform architecture for Linux and Windows.