portside-cli

name	portside-cli
description	Use when operating or troubleshooting the Portside CLI for GPTK-backed Windows Steam game environments on Apple Silicon Mac. Covers safe CLI workflows, JSON/NDJSON protocol usage, PORTSIDE_HOME boundaries, profile/prefix management, logs, runner diagnostics, and when not to edit state directly.
metadata	{"short-description":"Operate Portside CLI safely"}

Portside CLI

Use this skill when a task involves the local portside command, Portside profiles, prefixes, logs, snapshots, runner checks, or automation through JSON/NDJSON.

Core Rules

• Treat portside as the authority for state changes.
• Do not directly edit PORTSIDE_HOME files unless the user explicitly asks for low-level repair and the CLI cannot do it.
• Use portside --json <command> or <command> --json for query automation.
• Long-running task commands should be consumed as NDJSON once implemented.
• Never hand-build GPTK/Wine launch commands when portside run <game> can express the operation.
• GUI, TUI, helper, scripts, and agents must use the same PORTSIDE_HOME.

First Checks

Run these before making assumptions about a user's Portside installation:

portside --json doctor
portside --json prefix list
portside --json game list

doctor returns the current required actions by default. Use portside --json doctor --verbose only when you need every low-level check.

If doctor reports a missing config or state directories, use:

portside init

Common Workflows

Initialize:

portside init
portside doctor

Configure an existing GPTK runner:

portside runner setup gptk
portside runner use gptk
portside runner use gptk --command /path/to/wine64 --server-command /path/to/wineserver

Use runner setup gptk first. It discovers an installed GPTK-compatible runner from PATH, /Applications/Game Porting Toolkit.app, or Homebrew Caskroom and writes it to config. Use runner use gptk when you explicitly want to persist a known command path. Use runner import gptk --file <path> only to copy and register a local Apple official runtime package for later dmg/pkg import work.

Create a prefix:

portside prefix create steam-main

Install/open Windows Steam in the prefix:

portside steam install --prefix steam-main
portside steam open --prefix steam-main

Add a Steam game profile:

portside game add elden-ring --appid 1245620 --prefix steam-main
portside game install elden-ring

Inspect a launch plan without starting a process:

portside --json run elden-ring --dry-run

Open the terminal UI:

portside tui

References

• For command shapes and JSON contracts, read references/cli.md.
• For diagnostics and recovery order, read references/troubleshooting.md.