carafe

carafe is a tiny management tool for wine ~~bottles~~ carafes.

Features

• A tiny command-line script to create bottles/carafes for different programs
• Automatically manages different wine prefixes
• Never changes the default .wine configuration
• Configure settings for each carafe separately
• Create shortcuts for installed programs and/or easily start them from the carafe CLI
• All configuration and carafes are neatly stored in a single folder (and are auto-deleted when all carafes are deleted)

(carafe is both the name of the program and for a wine bottle created through this program)

Install

Pip

pip install --user -I git+https://github.com/Jelmerro/carafe

Python

Download or clone the repo, then run python carafe.py directly.

Github

Download a stable installer or executable for your platform from Github.

Fedora

I host a custom Fedora repository that you can use for automatic updates.

sudo dnf config-manager addrepo --from-repofile=https://jelmerro.nl/fedora/jelmerro.repo
sudo dnf install carafe

Contribute

You can support my work on ko-fi or Github sponsors. Another way to help is to report issues or suggest new features. Please try to follow recommendations by flake8 and pylint when developing. For an example vimrc that can auto-format based on the included linters, you can check out my personal vimrc.

Building

To create your own builds you can use jfpm. Please clone or download both this repo and jfpm, then run ../jfpm/release_py_simple.sh. This will build releases for various platforms and output them to dist.

Examples

There are two main examples provided here, both of which assume you have the setup stored inside the ~/Downloads folder. It's recommended to read both examples before starting, to get a good idea of the different ways to configure carafe.

Example for Steam installer

The following commands will setup a new carafe with steam installed.

carafe steam create
carafe steam install
carafe steam link

It can now be started by simply running carafe steam start

If you don't like the interactive questions, the same can be achieved like this:

carafe steam create
carafe steam install -e ~/Downloads/SteamSetup.exe
carafe steam link -l "Program Files (x86)/Steam/Steam.exe"
carafe steam start

It's also possible to skip the link step and start like this: carafe steam start -l "Program Files (x86)/Steam/Steam.exe". The link option is recommended to make the start command easier to use (and shorter). Alternatively you could pick a location from a list with this command:

carafe steam start --ask or carafe steam start -a for short.

Example for portable rufus

For portable programs the install step can be skipped. The installation steps could be something like this:

carafe rufus create

Now copy all the portable program files somewhere to the carafe. The location for our new rufus carafe is ~/.carafe/rufus/drive_c.

cp ~/Downloads/rufus.exe ~/.carafe/rufus/drive_c/

After copying the files, we can already execute rufus using this command:

carafe rufus start -l "C:/rufus.exe" or carafe rufus start --ask.

The command carafe rufus start --ask will ask the user to pick a location to start.

To create a link to the exe just like we did for Steam:

carafe rufus link

So we can run the rufus.exe like so:

carafe rufus start

Other options

There are many more sub-commands provided by carafe, the most important ones are listed here:

• All info about the Steam carafe: carafe steam info
• A list of all the carafes: carafe list
• Remove the rufus carafe completely with: carafe rufus remove
• Copy a carafe to a new location (as a backup for example): carafe steam copy steam-backup

Dependencies

carafe is pure python and only uses native imports, some of them are python 3.5+.

Wine is the only dependency of carafe and it can even do some management tasks without wine installed (such as remove, info and list). Creating and starting the carafes is done by wine, and won't work without it installed.

carafe will show a warning when the 'wine' command is not found, and offer instructions to resolve the problem. For some installation methods an alias might be needed, or you can configure the wine location in the config file. You can manually edit the ~/.carafe/config.json to change the default wine command location. It might be needed to create the config file, as it normally will only be stored when links or special arch types are used. The config file also accepts a 'winetricks' field for setting the winetricks location/path separately.

Advanced usage

carafe is a single script which can be started from any location. It will store the configuration and carafes inside ~/.carafe on all supported systems. Most testing was done on Linux, but I'm open to pull requests to broaden OS support or to improve other features.

Wine versions

carafe will need wine as the most important dependency. By default, the system wine is used for all carafes. The following advantages are a direct consequence of this decision:

• All carafes will automatically use the latest/greatest version of wine
• It's not required to manually update a hard-coded version for all the carafes (as carafe does not check the wine version)
• There is no need for carafe to manually add new supported wine versions (if there are no breaking CLI changes)

There is one trade-off to all these advantages:

• A regression in a new version of wine can break compatibility until a new wine version is released

The wine wiki recommends to use a recent or even the latest version of wine, which is automatically configured by using carafe.

Changing a wine version

In the rare cases where you want to use a custom wine version, you can manually update the carafe config. A toplevel "wine" key can be used as the global wine location, while a carafe specific "wine" key can be used to override that per carafe. The value of the configuration should be an absolute path to the wine executable.

Manage carafe

After running carafe a list of the supported options will shown. All of them are listed in the output as shown here:

usage: carafe {<carafe_name>,list} <sub_command>

Welcome to carafe 1.7.0
carafe is a tiny management tool for wine bottles/carafes.

options:
  -h, --help            show this help message and exit

sub-commands:
  All the valid sub-commands to manage the carafes

  {create,install,start,rename,copy,remove,info,link,shortcut,log,regedit,winecfg,winetricks}
    create              Create a new carafe
    install             Install software to the carafe
    start               Start an installed program
    rename              Rename an existing carafe
    copy                Copy an existing carafe
    remove              Remove a carafe
    info                All info about a carafe
    link                Link a program to the carafe
    shortcut            Generate a desktop shortcut
    log                 Show the last command output
    regedit             Run regedit
    winecfg             Run winecfg
    winetricks          Run winetricks

carafe was made by Jelmer van Arnhem and is MIT licensed
For documentation and other information, see the README.md

Most management options can be called without any arguments, some commands will ask questions to fill required information. If no user interaction is possible or wanted after running the command, next time call the command with all arguments which were asked as a question. In the section below, further details are provided on most options.

Create

The first step to using carafe is creating a new carafe to install apps into. This command only accepts --arch as an optional argument. By default the system architecture will be used. You cannot change the arch after creating a carafe (wine limitation), but you can create a new carafe with a different arch.

usage: carafe <carafe_name> create

Use 'create' to make a new carafe, you should start here

optional arguments:
  -h, --help     show this help message and exit
  --arch ARCH    Change the default arch, e.g. to win32
  -v, --verbose  Print the wine log to the screen (log file is always written)

As we did in the example for Steam: carafe steam create.

There are a couple of restrictions for choosing a name:

• There are a few of reserved words, like 'wine', 'list' and similar words
• All spaces are removed from the name
• Forward slashes are replaced with dashes

Aside from that you can choose any name you want, but descriptive names like the name of the main program are recommended.

Install

To install software inside the carafe the install option is used. It can also be used to run other external executables inside the carafe. If the executable argument is not provided, carafe will ask the user to enter the location.

usage: carafe <carafe_name> install

Use 'install' to run an external exe/msi inside the carafe

optional arguments:
  -h, --help            show this help message and exit
  -e, --executable EXECUTABLE
                        Location of the external executable to run inside the
                        carafe
  -v, --verbose         Print the wine log to the screen (log file is always
                        written)

Start

This option is used to start programs inside a carafe. For existing carafes, starting the default/linked program should be as straightforward as:

carafe <name_of_carafe> start

For example, the default program of an existing carafe for Steam could be started as:

carafe steam start

To