carafe is a tiny management tool for wine bottles carafes.
- 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)
There are two 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.
To start carafe as carafe, you need to install it:
pip install --user -I git+https://github.com/Jelmerro/carafeAlternatively you can run all carafe commands with python instead: python3 carafe.py.
The first option is used in this readme, because it's shorter.
The carafe.py script is all you need to manage carafes,
you can download and move it wherever you want.
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.
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
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
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.
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.
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.
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.
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.4.0
carafe is a tiny management tool for wine bottles/carafes.
optional arguments:
-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,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.
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
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.
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 EXECUTABLE
Location of the external executable to run inside the
carafe
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 run a different program inside the Steam carafe, add the ask argument:
carafe steam start --ask
Or use the location argument to start an executable inside the carafe directly:
carafe steam start -l "Program Files (x86)/Internet Explorer/iexplore.exe"
For the above command, an absolute path from the root of the carafe's C: disk is assumed. The location argument is required for carafes with no program linked yet.
usage: carafe <carafe_name> start
Use 'start' to start a program inside an existing carafe
optional arguments:
-h, --help show this help message and exit
-k, --keep-log Keep the wine log (can be multiple GBs and will slow
down wine)
-a, --ask Instead of starting the link or --location, ask for
the path
-l LOCATION, --location LOCATION
Location of the executable inside the carafe to start
The start command is the only sub-command which does not save the log by default.
With the keep log argument, the start command can return to the default behavior for all other commands.
If --keep-log is provided, the log can be found in ~/.carafe/<carafe_name>/log.
Keep in mind that this file can be multiple gigabytes after playing for a few hours,
and that it will cause a performance hit on wine to constantly write logs to disk.
You can also show the contents of the log file with the 'log' option.
With the rename option you change the name of an existing carafe.
usage: carafe <carafe_name> rename <new_name>
Use 'rename' to change the name of an existing carafe
positional arguments:
newname New name of the carafe
optional arguments:
-h, --help show this help message and exit
For example: carafe steam rename steam-backup.
Rename will actually copy the existing carafe and remove the old one. Running these two options separately will do exactly the same.
With the copy option you can copy an existing carafe to a new location. This is useful for backups, and it works like this:
usage: carafe <carafe_name> copy <new_name>
Use 'copy' to duplicate an existing carafe to a new one
positional arguments:
newname Name of the new carafe
optional arguments:
-h, --help show this help message and exit
For example: carafe steam copy steam-backup.
Once you are done with a carafe, this option can completely remove it from disk.
usage: carafe <carafe_name> remove
Use 'remove' to delete an existing carafe
optional arguments:
-h, --help show this help message and exit
If the removal of a carafe results in an empty config file,
the config file will be deleted from disk.
If either the removal of the config or the carafe result in an empty ~/.carafe folder,
it will be deleted as well, as if carafe had never been used before.
Desktop shortcuts will not be automatically deleted (see 'shortcut' option for creating them).
To view a list of all the existing carafes, use the list option.
This option will ignore all arguments after it, and will show a list like this:
carafe list
The following carafes are currently configured:
steam
rufus
Run 'carafe <carafe_name> info' for more information
All known information about an existing carafe can be listed with the info option.
usage: carafe <carafe_name> info
Use 'info' to print all information about a carafe
optional arguments:
-h, --help show this help message and exit
For example, to get all info about our steam carafe,
the command carafe steam info will return the following:
All information about carafe 'steam':
Configured with default system arch
No link is currently configured
When a carafe is linked, you can start the program with 'carafe steam start'
To modify the link, use 'carafe steam link'
The current list of executables looks like this:
C:/Program Files (x86)/Internet Explorer/iexplore.exe
C:/Program Files (x86)/Common Files/Steam/SteamService.exe
C:/Program Files (x86)/Windows NT/Accessories/wordpad.exe
C:/Program Files (x86)/Steam/uninstall.exe
C:/Program Files (x86)/Steam/Steam.exe
C:/Program Files (x86)/Steam/bin/SteamService.exe
C:/Program Files (x86)/Windows Media Player/wmplayer.exe
C:/Program Files/Internet Explorer/iexplore.exe
C:/Program Files/Windows NT/Accessories/wordpad.exe
C:/Program Files/Windows Media Player/wmplayer.exe
You can add more with 'carafe steam install'
An important feature of carafe is the linking system. It allows the user to pick a default location to execute per carafe.
usage: carafe <carafe_name> link
Use 'link' to connect the startup link (recommended)
optional arguments:
-h, --help show this help message and exit
-l LOCATION, --location LOCATION
Location of the executable inside the carafe to link
After running the 'info' option, a message was displayed regarding the linking.
When running the carafe steam link command now, it will ask us to choose an executable like this:
0: C:/Program Files (x86)/Internet Explorer/iexplore.exe
1: C:/Program Files (x86)/Common Files/Steam/SteamService.exe
2: C:/Program Files (x86)/Windows NT/Accessories/wordpad.exe
3: C:/Program Files (x86)/Steam/uninstall.exe
4: C:/Program Files (x86)/Steam/Steam.exe
5: C:/Program Files (x86)/Steam/bin/SteamService.exe
6: C:/Program Files (x86)/Windows Media Player/wmplayer.exe
7: C:/Program Files/Internet Explorer/iexplore.exe
8: C:/Program Files/Windows NT/Accessories/wordpad.exe
9: C:/Program Files/Windows Media Player/wmplayer.exe
Choose the number of the application shortcut: 4
After choosing number 4 as the linked application,
the command carafe steam info now displays the following:
All information about carafe 'steam':
Configured with default system arch
A link for easy startup is configured to the following:
Program Files (x86)/Steam/Steam.exe
When a carafe is linked, you can start the program with 'carafe steam start'
To modify the link, use 'carafe steam link'
The current list of executables looks like this:
C:/Program Files (x86)/Internet Explorer/iexplore.exe
C:/Program Files (x86)/Common Files/Steam/SteamService.exe
C:/Program Files (x86)/Windows NT/Accessories/wordpad.exe
C:/Program Files (x86)/Steam/uninstall.exe
C:/Program Files (x86)/Steam/Steam.exe
C:/Program Files (x86)/Steam/bin/SteamService.exe
C:/Program Files (x86)/Windows Media Player/wmplayer.exe
C:/Program Files/Internet Explorer/iexplore.exe
C:/Program Files/Windows NT/Accessories/wordpad.exe
C:/Program Files/Windows Media Player/wmplayer.exe
You can add more with 'carafe steam install'
We can now start steam with carafe steam start,
or start a different program inside the carafe: carafe steam start -l "Program Files/Internet Explorer/iexplore.exe".
The list of executables is automatically filled with all exe files inside the carafe.
To create a desktop shortcut, use the shortcut option. By default, it will place shortcuts on the user desktop. This can be altered by changing the output folder location. The executable location can be conveniently set to 'link', so it will be automatically updated when the linked program is changed. It will only auto-update for the carafe shortcut type, but the wine shortcut will continue to work after carafe is (re)moved.
usage: carafe <carafe_name> shortcut
Use 'shortcut' to create a .desktop shortcut to a carafe
optional arguments:
-h, --help show this help message and exit
-l LOCATION, --location LOCATION
Location of the executable inside the carafe to
shortcut. Normally a path, but can be set to 'link' as
well.
-o OUTPUT_FOLDER, --output-folder OUTPUT_FOLDER
Which folder to place the shortcut, default is the
user desktop
-n NAME, --name NAME Name of the new shortcut, default is the name of the
carafe
-t {carafe,wine}, --type {carafe,wine}
The type of shortcut to make
Executable location will be asked interactively when not provided as an argument, in a fairly similar way as is done for the 'link' command.
The name of the shortcut will be set to the name of the carafe automatically, but it can be changed with the optional --name argument like so:
carafe steam shortcut --name "Steam (Windows version)"
To achieve the same but with no interactive questions, the following command could be used to create a carafe shortcut for the linked program:
carafe steam shortcut --name "Steam (Windows version)" --type carafe --location link
Some programs might create a desktop shortcut during the installation, these type of shortcuts are made by wine and don't need carafe to work.
Shortcuts won't be automatically deleted when a carafe is deleted.
Example usage of log for a Steam carafe looks like this:
carafe steam log
This will show the output of the last wine, winetricks or winecfg command.
It simply reads and prints the file that is stored at ~/.carafe/<carafe_name>/log.
Example usage of regedit for a Steam carafe looks like this:
carafe steam regedit
To open the regedit for a Steam carafe without using carafe, the following command could be used:
WINEPREFIX=/home/user/.carafe/steam wine regedit
This is exactly what carafe will do when asked to invoke regedit, but carafe makes sure the winearch and wineprefix are automatically correct.
Example usage of winecfg for a Steam carafe looks like this:
carafe steam winecfg
Running winecfg without carafe works the same as for regedit.
Example usage of winetricks for a Steam carafe looks like this:
carafe steam winetricks
This will open the winetricks GUI, where a lot of extra components can be installed from. To install dxvk for the steam carafe with winetricks, run the command:
carafe steam winetricks dxvk
The help page describes this behavior as follows:
usage: carafe <carafe_name> winetricks <optional_arguments>
Use 'winetricks' to install winetricks components
positional arguments:
arguments Any arguments will directly be passed to winetricks
optional arguments:
-h, --help show this help message and exit
Just like winecfg and regedit, it's also possible to run winetricks commands without carafe:
WINEPREFIX=/home/user/.carafe/steam winetricks dxvk
This again means that you need to manually set the wineprefix and winearch to the correct values, which is something that the carafe command will handle for you.
In short, carafe is aimed to ease the configuration of wine bottles/carafes, without introducing any magic or changing the wine prefix system.
No wine commands executed by carafe will show any output in the terminal.
You can view the latest log using the 'log' option or by reading the 'log' file inside the carafe.
The commands will store the log of the latest executed command as ~/.carafe/<carafe_name>/log.
carafe does not keep a history of all the logs, only the latest one is stored.
The start command will by default disable all logging,
because these logs can get very large and because it slows down wine.
To restore the default logging, provide the --keep-log argument (see the 'start' option for details).
Wine will create menu shortcuts in ~/.local/share/applications,
and store the icons for them in ~/.local/share/icons.
The location ~/.local/share/desktop-directories will also be used,
along with ~/.config/menus for menu related files.
These directories are automatically filled with files by wine, carafe does not create, modify or remove them.
carafe stores all configuration and the prefixes in ~/.carafe,
which will automatically be deleted when all carafes are removed.
carafe itself is made by Jelmer van Arnhem and is licensed as MIT, see LICENSE for details.
Dependencies such as wine have no relation to carafe and are be covered by different licenses.
