steamcmd

README

steamcmd-go

steamcmd-go is a standard-library-only Go client for installing and driving SteamCMD on Linux and Windows.

Install

go get github.com/TagamerStudio/steamcmd-go

Usage

package main

import (
	"context"
	"log"

	"github.com/TagamerStudio/steamcmd-go"
)

func main() {
	ctx := context.Background()
	client, err := steamcmd.New(steamcmd.Config{
		SteamCMDDir: "/var/lib/steamcmd",
		InstallDir:  "/var/lib/game",
	})
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.Setup(ctx, steamcmd.UpdateOptions{
		AppID: "1234",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("updated=%t build=%s", result.Updated, result.InstalledBuildID)
}

An empty Login.Username uses anonymous login. Authenticated login is configured explicitly with Login{Username, Password, GuardCode}. An empty Platform uses the host platform; use PlatformLinux or PlatformWindows for cross-platform provisioning.

Setup installs SteamCMD when necessary and updates the requested app. Install and Update are available separately. AppInfo, build ID queries, CheckForUpdate, generic Run, and Workshop downloads are also available.

Update options

UpdateOptions supports beta branches, beta passwords, validation, forced updates, and additional app-update arguments. App IDs and Workshop file IDs must be numeric Steam IDs.

The public build comparison is skipped for beta updates, because the public app-info build is not necessarily the build for a selected branch.

Configuration

Attempts, RetryBackoff, CommandTimeout, DownloadTimeout, and MaxOutputBytes have safe defaults and can be overridden. The default installer tries three official download URLs, retries each mirror, downloads atomically, and extracts through bounded ZIP/TAR.GZ readers.

Downloader and CommandRunner are available for tests and controlled environments. The package has no external runtime dependencies.

Security

SteamCMD is always started directly with os/exec; no shell is used. App IDs are validated before becoming command arguments. Archive extraction rejects absolute paths, traversal, links, special files, oversized entries, and excessive entry counts. SteamCMD installation uses a staging directory and does not replace a valid installation until extraction succeeds.

Operations on one Client are serialized. Applications using the same directories from multiple processes must provide cross-process coordination. The package does not log credentials or command arguments. SteamCMD passwords may still be visible in the operating system's process list while a command is running.

Errors

Command failures are returned as *CommandError. Its bounded Output field contains captured output for diagnostics, while Error() does not include command arguments or output. Context cancellation and deadlines remain detectable with errors.Is.

Development

make check

The check runs the linter, tests with the race detector, and the strict 100% statement coverage gate. Other useful targets are make fmt, make tidy, and make cover; the latter writes coverage.out and prints the per-function coverage report.

CI also runs go vet, scans dependencies with govulncheck, builds on Linux, cross-builds for Windows, and runs the test suite natively on Windows.

Coverage

make cover

Coverage is measured with atomic instrumentation and must remain at 100% statement coverage. CI publishes push coverage reports to Codecov.

License

BSD 3-Clause. See LICENSE.

Documentation

Overview

Package steamcmd provides a small, safe Go client for SteamCMD.

A Client is intended to be the sole coordinator for one SteamCMD directory. The package serializes operations within a Client, but callers must also coordinate separate processes that use the same directories.

Index

• func ParseBuildID(output string) (string, error)
• type Client
  • func New(config Config) (*Client, error)
  • func (c *Client) AppInfo(ctx context.Context, appID string) ([]byte, error)
  • func (c *Client) CheckForUpdate(ctx context.Context, appID string) (UpdateStatus, error)
  • func (c *Client) DownloadWorkshopItem(ctx context.Context, options WorkshopDownloadOptions) error
  • func (c *Client) ExecutablePath() string
  • func (c *Client) Install(ctx context.Context) error
  • func (c *Client) InstalledBuildID(appID string) (string, error)
  • func (c *Client) LatestBuildID(ctx context.Context, appID string) (string, error)
  • func (c *Client) Run(ctx context.Context, args ...string) ([]byte, error)
  • func (c *Client) Setup(ctx context.Context, options UpdateOptions) (UpdateResult, error)
  • func (c *Client) Update(ctx context.Context, options UpdateOptions) (UpdateResult, error)
• type CommandError
  • func (e *CommandError) Error() string
  • func (e *CommandError) Unwrap() error
• type CommandRunner
• type Config
• type Downloader
• type Login
• type Platform
• type UpdateOptions
• type UpdateResult
• type UpdateStatus
• type WorkshopDownloadOptions

Functions

func ParseBuildID

func ParseBuildID(output string) (string, error)

ParseBuildID extracts the first numeric buildid field from SteamCMD output or a raw app manifest.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client controls one SteamCMD installation and its app directory.

func New

func New(config Config) (*Client, error)

New validates config and creates a Client. Platform defaults to runtime.GOOS when omitted. SteamCMDDir and InstallDir must not overlap.

func (*Client) AppInfo

func (c *Client) AppInfo(ctx context.Context, appID string) ([]byte, error)

AppInfo fetches raw app information from SteamCMD.

func (*Client) CheckForUpdate

func (c *Client) CheckForUpdate(ctx context.Context, appID string) (UpdateStatus, error)

CheckForUpdate compares the installed manifest with the public build.

func (*Client) DownloadWorkshopItem

func (c *Client) DownloadWorkshopItem(ctx context.Context, options WorkshopDownloadOptions) error

DownloadWorkshopItem downloads one Steam Workshop item.

func (*Client) ExecutablePath

func (c *Client) ExecutablePath() string

ExecutablePath returns the path to the configured SteamCMD executable.

func (*Client) Install

func (c *Client) Install(ctx context.Context) error

Install installs SteamCMD if its platform entrypoint is not already a regular executable file.

func (*Client) InstalledBuildID

func (c *Client) InstalledBuildID(appID string) (string, error)

InstalledBuildID reads the app manifest from InstallDir.

func (*Client) LatestBuildID

func (c *Client) LatestBuildID(ctx context.Context, appID string) (string, error)

LatestBuildID fetches app information and parses its public build ID.

func (*Client) Run

func (c *Client) Run(ctx context.Context, args ...string) ([]byte, error)

Run executes SteamCMD directly without invoking a shell.

func (*Client) Setup

func (c *Client) Setup(ctx context.Context, options UpdateOptions) (UpdateResult, error)

Setup installs SteamCMD and then performs the requested app update.

func (*Client) Update

func (c *Client) Update(ctx context.Context, options UpdateOptions) (UpdateResult, error)

Update performs an app update using an already installed SteamCMD.

type CommandError

type CommandError struct {
	Output    []byte
	Truncated bool
	Err       error
	// contains filtered or unexported fields
}

CommandError reports a failed SteamCMD invocation. Output is bounded by Config.MaxOutputBytes.

func (*CommandError) Error

func (e *CommandError) Error() string

func (*CommandError) Unwrap

func (e *CommandError) Unwrap() error

Unwrap exposes the underlying process or context error.

type CommandRunner

type CommandRunner func(context.Context, string, []string) ([]byte, error)

CommandRunner is the command execution seam used by tests and callers that need to provide their own process runner.

type Config

type Config struct {
	SteamCMDDir     string
	InstallDir      string
	Platform        Platform
	Login           Login
	DownloadURLs    []string
	HTTPClient      *http.Client
	Downloader      Downloader
	CommandRunner   CommandRunner
	Attempts        int
	RetryBackoff    time.Duration
	CommandTimeout  time.Duration
	DownloadTimeout time.Duration
	MaxOutputBytes  int64
}

Config controls a Client.

type Downloader

type Downloader func(context.Context, string, string) error

Downloader downloads url to destination. The destination is a temporary path when called by Install.

type Login

type Login struct {
	Username  string
	Password  string
	GuardCode string
}

Login contains the credentials used for SteamCMD commands. An empty Username selects anonymous login.

type Platform

type Platform string

Platform identifies the SteamCMD platform override.

const (
	PlatformWindows Platform = "windows"
	PlatformLinux   Platform = "linux"
)

type UpdateOptions

type UpdateOptions struct {
	AppID        string
	Beta         string
	BetaPassword string
	Validate     bool
	Force        bool
	ExtraArgs    []string
}

UpdateOptions controls an app update.

type UpdateResult

type UpdateResult struct {
	AppID            string
	PreviousBuildID  string
	LatestBuildID    string
	InstalledBuildID string
	Updated          bool
	Verified         bool
}

UpdateResult describes an update attempt.

type UpdateStatus

type UpdateStatus struct {
	AppID            string
	PreviousBuildID  string
	LatestBuildID    string
	InstalledBuildID string
	UpdateAvailable  bool
}

UpdateStatus describes whether the installed app differs from the public build reported by SteamCMD.

type WorkshopDownloadOptions

type WorkshopDownloadOptions struct {
	AppID           string
	PublishedFileID string
	Validate        bool
}

WorkshopDownloadOptions controls a workshop item download.