Bottles
Search
K
Links

CLI

Using Bottles via CLI
In 2022.3.28 we have introduced a new CLI interface, which provide more features then the prior.

Launch CLI

The new interface has a dedicated command: bottles-cli .
If using Bottles as Flatpak (the suggested way), launch it with:
flatpak run --command=bottles-cli com.usebottles.bottles --help
Bottles is a tool to manage your bottles
positional arguments:
{info,list,programs,tools,reg,edit,new,run}
sub-command help
info Show information about Bottles
list List entities
programs List programs
tools Launch WINE tools
reg Manage registry
edit Edit a bottle configuration
new Create a new bottle
run Run a program
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-j, --json Outputs in JSON format
for all other packages:
bottles-cli --help

Interfaces/Arguments

Since Bottles has a lot of features, to keep things organized we have divided it in multiple interfaces: info, list, programs, tools, reg, edit, new, run.

Info

The info interface can be used to access Bottles information:
usage: bottles-cli info [-h] {bottles-path,health-check}
positional arguments:
{bottles-path,health-check}
Type of information
optional arguments:
-h, --help show this help message and exit

List

The list command is meant to be used for listing Bottles stuff:
usage: bottles-cli list [-h] [-f FILTER] {bottles,components}
positional arguments:
{bottles,components} Type of entity
optional arguments:
-h, --help show this help message and exit
-f FILTER, --filter FILTER
Filter bottles and components (e.g. '-f 'environment:gaming')
the -f argument for bottles supports the environment prefix:
bottles-cli list bottles -f environment:gaming
while for components the category one can be used:
bottles-cli list components -f category:dxvk

Programs

The programs interface can be used to list all programs in a bottle (only added by users or installers).
usage: bottles-cli programs [-h] -b BOTTLE
optional arguments:
-h, --help show this help message and exit
-b BOTTLE, --bottle BOTTLE
Bottle name

Tools

The tools interface can be used to launch any WINE utility.
usage: bottles-cli tools [-h] -b BOTTLE {cmd,winecfg,uninstaller,regedit,taskmgr,control,explorer}
positional arguments:
{cmd,winecfg,uninstaller,regedit,taskmgr,control,explorer}
Tool to launch
optional arguments:
-h, --help show this help message and exit
-b BOTTLE, --bottle BOTTLE
Bottle name

Reg

The reg interface can be used to access and edit the bottle's Windows registry.
usage: bottles-cli reg [-h] -b BOTTLE -k KEY -v VALUE [-d DATA] [-t {REG_DWORD,REG_SZ,REG_BINARY,REG_MULTI_SZ}] {add,edit,del}
positional arguments:
{add,edit,del} Action to perform
optional arguments:
-h, --help show this help message and exit
-b BOTTLE, --bottle BOTTLE
Bottle name
-k KEY, --key KEY Registry key
-v VALUE, --value VALUE
Registry value
-d DATA, --data DATA Data to be set
-t {REG_DWORD,REG_SZ,REG_BINARY,REG_MULTI_SZ}, --key-type {REG_DWORD,REG_SZ,REG_BINARY,REG_MULTI_SZ}
Data type

Edit

The edit interface can be used to edit a bottle (e.g. any parameter, environment variables, Windows version, runner, dxvk, vkd3d..).
usage: bottles-cli edit [-h] -b BOTTLE [--params PARAMS] [--env-var ENV_VAR] [--win WIN] [--runner RUNNER] [--dxvk DXVK] [--vkd3d VKD3D] [--nvapi NVAPI] [--latencyflex LATENCYFLEX]
optional arguments:
-h, --help show this help message and exit
-b BOTTLE, --bottle BOTTLE
Bottle name
--params PARAMS Set parameters (e.g. '-p dxvk:true')
--env-var ENV_VAR Add new environment variable (e.g. '-env-var WINEDEBUG=-all')
--win WIN Change Windows version (e.g. '--win win7')
--runner RUNNER Change Runner (e.g. '--runner caffe-7.2')
--dxvk DXVK Change DXVK (e.g. '--dxvk dxvk-1.9.0')
--vkd3d VKD3D Change VKD3D (e.g. '--vkd3d vkd3d-proton-2.6')
--nvapi NVAPI Change DXVK-Nvapi (e.g. '--nvapi dxvk-nvapi-1.9.0')
--latencyflex LATENCYFLEX
Change LatencyFleX (e.g. '--latencyflex latencyflex-v0.1.0')

Add

The add interface can be used to add new programs to a bottle:
usage: bottles-cli add [-h] -b BOTTLE -n NAME -p PATH [-l LAUNCH_OPTIONS] [--no-dxvk] [--no-vkd3d]
[--no-dxvk-nvapi]
optional arguments:
-h, --help show this help message and exit
-b BOTTLE, --bottle BOTTLE
Bottle name
-n NAME, --name NAME Program name
-p PATH, --path PATH Program path
-l LAUNCH_OPTIONS, --launch-options LAUNCH_OPTIONS
Program launch options
--no-dxvk Disable DXVK for the program
--no-vkd3d Disable VKD3D for the program
--no-dxvk-nvapi Disable DXVK Nvapi for the program

New

The new interface can be used to create a new bottle.
usage: bottles-cli new [-h] --bottle-name BOTTLE_NAME --environment ENVIRONMENT [--custom-environment CUSTOM_ENVIRONMENT] [--arch ARCH] [--runner RUNNER] [--dxvk DXVK] [--vkd3d VKD3D] [--nvapi NVAPI] [--latencyflex LATENCYFLEX]
optional arguments:
-h, --help show this help message and exit
--bottle-name BOTTLE_NAME
Bottle name
--environment ENVIRONMENT
Envorinment to apply (gaming|application|custom)
--custom-environment CUSTOM_ENVIRONMENT
Path to a custom environment.yml file
--arch ARCH Architecture (win32|win64)
--runner RUNNER Name of the runner to be used
--dxvk DXVK Name of the dxvk to be used
--vkd3d VKD3D Name of the vkd3d to be used
--nvapi NVAPI Name of the dxvk-nvapi to be used
--latencyflex LATENCYFLEX
Name of the latencyflex to be used

Run

The run interface can be used to launch an executable from a given path or any program in a bottle using its name:
usage: bottles-cli run [-h] -b BOTTLE [-e EXECUTABLE] [-a ARGS] [-p PROGRAM]
optional arguments:
-h, --help show this help message and exit
-b BOTTLE, --bottle BOTTLE
Bottle name
-e EXECUTABLE, --executable EXECUTABLE
Path to the executable
-a ARGS, --args ARGS Arguments to pass to the executable
-p PROGRAM, --program PROGRAM
Program to run

Shell

The shell interface can be used to run commands inside a wine shell for the given bottle:
usage: bottles-cli shell [-h] -b BOTTLE -i INPUT
optional arguments:
-h, --help show this help message and exit
-b BOTTLE, --bottle BOTTLE
Bottle name
-i INPUT, --input INPUT
Command to execute

Standalone

The standalone interface can be used to generate a script which can be used to launch commands in a wine shell for the given bottle, without passing trough Bottles:
usage: bottles-cli standalone [-h] -b BOTTLE
optional arguments:
-h, --help show this help message and exit
-b BOTTLE, --bottle BOTTLE
Bottle name

Developers mode

We've added a --json global argument to help developers accessing stuff from the Bottles' CLI. It can be used with any interface and will return the output in JSON format. Some examples:
bottles-cli --json info health-check
{"Display": {"X.org": true, "X.org (port)": ":99.0", "Wayland": false}, "Graphics": {"vendors": {"nvidia": {"vendor": "nvidia", "envs": {"__NV_PRIME_RENDER_OFFLOAD": "1", "__GLX_VENDOR_LIBRARY_NAME": "nvidia", "__VK_LAYER_NV_optimus": "NVIDIA_only"}, "icd": "/usr/lib/x86_64-linux-gnu/GL/vulkan/icd.d/nvidia_icd.json:/usr/lib/i386-linux-gnu/GL/vulkan/icd.d/nvidia_icd.json"}, "amd": {"vendor": "amd", "envs": {"DRI_PRIME": "1"}, "icd": "/usr/lib/x86_64-linux-gnu/GL/vulkan/icd.d/radeon_icd.x86_64.json:/usr/lib/i386-linux-gnu/GL/vulkan/icd.d/radeon_icd.i686.json"}}, "prime": {"integrated": {"vendor": "amd", "envs": {"DRI_PRIME": "1"}, "icd": "/usr/lib/x86_64-linux-gnu/GL/vulkan/icd.d/radeon_icd.x86_64.json:/usr/lib/i386-linux-gnu/GL/vulkan/icd.d/radeon_icd.i686.json"}, "discrete": {"vendor": "nvidia", "envs": {"__NV_PRIME_RENDER_OFFLOAD": "1", "__GLX_VENDOR_LIBRARY_NAME": "nvidia", "__VK_LAYER_NV_optimus": "NVIDIA_only"}, "icd": "/usr/lib/x86_64-linux-gnu/GL/vulkan/icd.d/nvidia_icd.json:/usr/lib/i386-linux-gnu/GL/vulkan/icd.d/nvidia_icd.json"}}}, "Kernel": {"Type": "Linux", "Version": "5.16.15-201.fc35.x86_64"}, "Distro": {"Name": "GNOME", "Version": "\"42 (Flatpak runtime)\""}, "Tools": {"cabextract": true, "p7zip": true, "patool": true, "glibc_min": "2.33"}, "Bottles_envs": null}
bottles-cli --json list components -f category:runners
{"runners": ["vaniglia-7.5", "sys-wine-7.0", "caffe-7.5", "caffe-7.1"]}
in some cases it will return more info then the classic launch, e.g. for the programs interface:
bottles-cli --json programs -b MyBottle
[{"executable": "Battle.net.exe", "arguments": "", "name": "Battle.net", "path": "C:\\Program Files (x86)\\Battle.net\\Battle.net.exe", "folder": "", "icon": "", "script": null, "removed": null}, {"executable": "EpicGamesLauncher.exe", "arguments": "-opengl -SkipBuildPatchPrereq", "name": "Epic Games Store", "path": "C:\\Program Files (x86)\\Epic Games\\Launcher\\Portal\\Binaries\\Win32\\EpicGamesLauncher.exe", "folder": "", "icon": "", "script": null, "removed": null}, {"executable": "GalaxyClient.exe", "arguments": "--in-process-gpu /runWithoutUpdating /deelevated", "name": "GOG Galaxy", "path": "C:\\Program Files (x86)\\GOG Galaxy\\GalaxyClient.exe", "folder": "", "icon": "", "script": null, "removed": null}]