Metadata-Version: 2.4
Name: gog-cli
Version: 1.0.0
Summary: CLI tool for backing up DRM-free GOG games.
Author: gog-cli contributors
License: MIT License
        
        Copyright (c) 2026 gog-cli contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/aleksandarristic/gog-cli
Project-URL: Repository, https://github.com/aleksandarristic/gog-cli
Project-URL: Bug Tracker, https://github.com/aleksandarristic/gog-cli/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: responses>=0.25; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# gog-cli

[![CI](https://github.com/aleksandarristic/gog-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/aleksandarristic/gog-cli/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/gog-cli)](https://pypi.org/project/gog-cli/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

`gog` is a Python CLI for backing up a user's owned DRM-free GOG game library.

It is focused on safe, scriptable workflows:

- list owned games with filtering and fuzzy search
- plan and execute backups to a local directory
- preserve metadata needed to audit and restore backups
- download installers and related files with resumable behavior
- verify downloaded files when checksums are available

It's also comfortable as a quick, interactive tool:

```sh
gog list                    # your purchased library
gog list civilization       # fuzzy title search
gog search "baldurs gate"   # public catalog, with an "owned" column
gog dl "civilization iv"    # download by name or id in the current directory
gog dl 1760534591 --win     # unambiguous by id, Windows files only
gog help dl                 # contextual help for any command
```

## Install

Requires Python 3.12 or newer.

```sh
pip install gog-cli
```

To install the latest development version directly from GitHub:

```sh
pip install git+https://github.com/aleksandarristic/gog-cli.git
```

## Development

```sh
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pytest
```

Run the CLI locally:

```sh
gog --help
gog list
gog plan --all --summary
gog dl --games-from games.txt --dry-run
```

## Roadmap

See [docs/TODO.md](docs/TODO.md) for planned features and improvements.

## Reference

- [CLI Reference](docs/cli-reference.md)
- [Config Reference](docs/config-reference.md)

## Basic Workflow

```sh
gog auth login
gog refresh
gog list
gog plan --destination /path/to/backups --all --storage --check-free-space
gog backup --destination /path/to/backups --all --yes
gog list --backup --destination /path/to/backups
gog sync --destination /path/to/backups --all --yes
```

`gog refresh` updates the local purchased-library and download-metadata caches.
It does not download game installers. Run it before browsing or filtering newly
added library metadata.

`--destination` is optional everywhere above — it defaults to the current
directory, so `cd` into a backup folder and drop it from every command.

## Browsing Purchased Games

`gog list` reads the local cache written by `gog refresh`; it does not contact
GOG. Human output includes ID, title, release year, genre/category, and
platforms when those fields are available. JSON output also includes scriptable
metadata such as `owned`, `release_date`, `genres`, and `is_installable`.

`gog list` alone lists everything; `gog list TEXT` fuzzy-searches by title.
Neither `purchased` nor `backup` is a reserved word — a game actually titled
either one is never shadowed. `gog list --backup`/`--back` lists games
recorded in a backup manifest instead.

Examples:

```sh
gog list
gog list --format json
gog list witcher
gog list "baldurs gate"
gog list --platform windows
gog list ftl --platform linux
gog list --year 1998..2005
gog list --year 2010..2020 --include-unknown-year
gog list --genre strategy
gog list --genre arcade,rts
gog list --genre strategy --include-unknown-genre
gog list "baldurs gate" --platform linux --format json
```

Use `gog search TEXT` to search the public GOG catalog instead of your local
library — results include an `owned` column/field so you can see at a glance
whether you already have a game.

Year filters omit games with unknown years by default; use
`--include-unknown-year` to keep them. Genre filters similarly omit unknown
genres by default; use `--include-unknown-genre` to keep those rows.

## Planning Backups

`gog plan` shows the same dry-run plan as `gog backup --dry-run` without
downloading files or creating backup directories. Use it before long backup runs
to estimate size, inspect filters, and check destination free space.

Examples:

```sh
gog plan --destination /path/to/backups --all
gog plan --destination /path/to/backups --all --summary
gog plan --destination /path/to/backups --all --storage
gog plan --destination /path/to/backups --all --check-free-space
gog plan --destination /path/to/backups --all --format json
gog plan --destination /path/to/backups cyberpunk_2077
```

Platform and language filters can reduce backup size:

```sh
gog plan --destination /path/to/backups --all --platform linux --storage
gog plan --destination /path/to/backups --all --platform windows --language en --storage
```

## Selecting Games

The simplest way to select a game is a bare positional argument — a product
ID, slug, or title. Titles don't need to be exact: if there's no exact
id/slug/title match, the selector falls back to fuzzy title matching.

```sh
gog dl "civilization iv"          # fuzzy title match
gog dl 1760534591                 # exact id, never ambiguous
gog backup witcher_3 --yes
```

If a fuzzy selector matches more than one game, `gog` prompts you to pick one
at an interactive terminal, or exits with an error listing the candidates
otherwise (scripts, `--no-interactive`, or CI). Use an exact id or slug to
sidestep ambiguity entirely.

`--game`/`-g` behaves the same but only ever matches exactly (product id,
slug, or exact title) — no fuzzy fallback — which is what you want for
scripts and `games.txt` files where the match must be deterministic. It's
repeatable:

```sh
gog plan --destination /path/to/backups --game witcher_3 --game cyberpunk_2077
gog backup --destination /path/to/backups --game 123456789 --yes
```

Platform and role filters have shortcut flags on top of the general
`--platform`/`--role` options:

```sh
gog dl "civilization iv" --win              # shortcut for --platform windows
gog dl "baldurs gate 3" --mac --lin         # --mac / --lin (or --linux)
gog dl "civilization iv" --extras           # shortcut for --role extra
```

For larger curated lists, put selectors in a UTF-8 text file and pass
`--games-from`. Blank lines and lines whose first non-whitespace character is
`#` are ignored.

Example `games.txt`:

```text
# first NAS batch
witcher_3
cyberpunk_2077
123456789
```

Use the selector file in plan, backup, or sync workflows:

```sh
gog plan --destination /path/to/backups --games-from games.txt --storage
gog backup --destination /path/to/backups --games-from games.txt --downloader aria2c --yes
gog sync --destination /path/to/backups --games-from games.txt --dry-run
```

`--games-from` is repeatable and combines with repeated `--game` flags. Do not
combine explicit game selectors with `--all`.

## Downloading

`gog backup`/`gog download`/`gog dl` are the same command. If `aria2c` is
installed and on `PATH`, it's used automatically; otherwise the built-in
direct downloader is used. Pass `--downloader` explicitly to override either
way:

```sh
gog dl --games-from games.txt --yes                    # aria2c if present, else direct
gog dl --games-from games.txt --downloader direct --yes # force the built-in downloader
```

When file size metadata is available, `gog` chooses `aria2c` connection settings
by size: very small files use one connection, mid-size files use two or four,
and multi-GB installers use eight or sixteen. Configure
`aria2c_policy = "conservative"` or `aria2c_policy = "aggressive"` to tune this
behavior.

Without `--yes`, backup and sync commands print a dry-run plan and exit without
downloading or modifying backup files.
