Bench CLI

The command-line interface: bench.exe

Version: 0.22.0

The Bench CLI allows to interact with a Bench environment on the command line.

It supports a hierarchy of sub-commands with flags and options, which can be specified as command line arguments. Additionally it supports an interactive mode when called without a sub-command specified. Help texts can be displayed for each sub-command with the -? argument. The help texts can be printed in different formats.

Take a look at the project website for a description of the Bench system.

Commands

bench

The bench command is the executable of the Bench CLI. You can call it without a sub-command to enter the interactive mode.

Usage

  • bench ( <flag> | <option>)*
  • bench ( <flag> | <option>)* <command> …

Help

Showing the help can be triggered by one of the following flags: /?, -?, -h, --help.

  • bench -?
  • bench <command> -?

Flags

--verbose | -v

Activate verbose output.

--yes | --force | -y

Suppress all assurance questions.

Options

--help-format | -f <value>

Specify the output format of help texts.

Expected: Plain | Markdown
Default: Plain

--logfile | --log | -l <value>

Specify a custom location for the log file.

Expected: A path to the log file.
Default: Auto generated filename in <bench root>\log.

--root | --base | -r <value>

Specify the root directory of the Bench environment.

Expected: A path to a valid Bench root directory.
Default: The root directory of the Bench environment, this Bench CLI belongs to.

Commands

app, a

Manage individual apps.

Syntax: bench app <sub-command>

dashboard, gui, b

Start the Bench Dashboard.

help, h

Display the full help for all commands.

list, l

List different kinds of objects in the Bench environment.

manage, m

Manage the Bench environment and its configuration.

project, prj, p

Manage projects in the Bench environment.

Syntax: bench project

Searches for apps.

transfer, t

Copy or export this Bench environment.

bench app

Command: bench app

The app command allows interacting with Bench apps.

Use the sub-commands to select the kind of interaction.

Usage

  • bench app -?
  • bench ( <flag> | <option>)* app
  • bench ( <flag> | <option>)* app <command> …

Commands

activate, enable, a

Activates an app.

Syntax: bench app activate <App ID>

deactivate, disable, d

Deactivates an app.

Syntax: bench app deactivate <App ID>

download, cache, c

Downloads an apps resource.

Syntax: bench app download <App ID>

execute, exec, launch, run, e

Starts an apps main executable.

Syntax: bench app execute <flag>* <App ID> …

info, i

Shows a detailed, human readable info of an app.

Syntax: bench app info <option>* <App ID>

install, setup, s

Installs an app, regardless of its activation state.

Syntax: bench app install <App ID>

list-properties, list, l

Lists the properties of an app.

Syntax: bench app list-properties ( <flag> | <option>)* <App ID>

property, prop, p

Reads an app property value.

Syntax: bench app property <App ID> <Property Name>

reinstall, r

Reinstalls an app.

Syntax: bench app reinstall <App ID>

uninstall, remove, x

Uninstalls an app, regardless of its activation state.

Syntax: bench app uninstall <App ID>

upgrade, u

Upgrades an app.

Syntax: bench app upgrade <App ID>

bench app activate

Command: bench app activate

The activate command marks an app as activated.

To actually install the app, you have to run the setup command.

If the app is currently active as a dependency, it is marked as activated anyways. If the app is required by Bench, it is not marked as activated. If the app is marked as deactivated, this mark is removed.

Usage

  • bench app activate -?
  • bench ( <flag> | <option>)* app activate <App ID>

Positional Arguments

1. App ID

Specifies the app to activate.

Expected: An app ID is an alphanumeric string without whitespace.

bench app deactivate

Command: bench app deactivate

The deactivate command removes an app from the activation list or marks it as deactivated.

To actually uninstall the app, you have to run the setup command.

If the app is currently on the activation list, it is removed from it. If the app is required by Bench, or as a dependency, it is marked as deactivated.

Usage

  • bench app deactivate -?
  • bench ( <flag> | <option>)* app deactivate <App ID>

Positional Arguments

1. App ID

Specifies the app to deactivate.

Expected: An app ID is an alphanumeric string without whitespace.

bench app download

Command: bench app download

The download command downloads the app resources, in case it is not cached already.

Usage

  • bench app download -?
  • bench ( <flag> | <option>)* app download <App ID>

Positional Arguments

1. App ID

Specifies the app to download the resource for.

Expected: An app ID is an alphanumeric string without whitespace.

bench app execute

Command: bench app execute

The execute command starts the main executable of the specified app.

Usage

  • bench app execute -?
  • bench ( <flag> | <option>)* app execute <flag>* <App ID> …

Flags

--detached | --async | -d

Do not wait for the end of the process.

Positional Arguments

1. App ID

Specifies the app to execute.

Expected: An app ID is an alphanumeric string without whitespace.

Additional Arguments

All additonal arguments are passed as command line arguments to the executable.

bench app info

Command: bench app info

The info command displayes a detailed description for an app in human readable form.

Usage

  • bench app info -?
  • bench ( <flag> | <option>)* app info <option>* <App ID>

Options

--format | -f <value>

Specify the output format.

Expected: Plain | Markdown
Default: Plain

Positional Arguments

1. App ID

Specifies the app to display the description for.

Expected: An app ID is an alphanumeric string without whitespace.

bench app install

Command: bench app install

The install command installes the specified app, regardless of its activation state.

Missing app resources are downloaded automatically.

Usage

  • bench app install -?
  • bench ( <flag> | <option>)* app install <App ID>

Positional Arguments

1. App ID

Specifies the app to install.

Expected: An app ID is an alphanumeric string without whitespace.

bench app list-properties

Command: bench app list-properties

The list-properties command displayes the properties of an app.

This command supports different output formats. And you can choose between the expanded or the raw properties.

Usage

  • bench app list-properties -?
  • bench ( <flag> | <option>)* app list-properties ( <flag> | <option>)* <App ID>

Flags

--raw | -r

Shows the raw properties without expansion and default values.

Options

--format | -f <value>

Specify the output format.

Expected: Plain | Markdown
Default: Plain

Positional Arguments

1. App ID

Specifies the app of which the properties are to be listed.

Expected: The apps ID, an alphanumeric string without whitespace.

bench app property

Command: bench app property

The property command reads the value of an app property.

Usage

  • bench app property -?
  • bench ( <flag> | <option>)* app property <App ID> <Property Name>

Positional Arguments

1. App ID

Specifies the app to get the property from.

Expected: The apps ID, an alphanumeric string without whitespace.

2. Property Name

Specifies the property to read.

Expected: The property name, an alphanumeric string without whitespace.

bench app reinstall

Command: bench app reinstall

The reinstall command reinstalles the specified app.

Usage

  • bench app reinstall -?
  • bench ( <flag> | <option>)* app reinstall <App ID>

Positional Arguments

1. App ID

Specifies the app to reinstall.

Expected: An app ID is an alphanumeric string without whitespace.

bench app uninstall

Command: bench app uninstall

The uninstall command uninstalles the specified app, regardless of its activation state.

Usage

  • bench app uninstall -?
  • bench ( <flag> | <option>)* app uninstall <App ID>

Positional Arguments

1. App ID

Specifies the app to install.

Expected: An app ID is an alphanumeric string without whitespace.

bench app upgrade

Command: bench app upgrade

The upgrade command upgrades the specified app to the most current release.

Updates app resources are downloaded automatically.

Usage

  • bench app upgrade -?
  • bench ( <flag> | <option>)* app upgrade <App ID>

Positional Arguments

1. App ID

Specifies the app to upgrade.

Expected: An app ID is an alphanumeric string without whitespace.

bench dashboard

Command: bench dashboard

The dashboard command starts the graphical user interface Bench Dashboard.

Usage

  • bench dashboard -?
  • bench ( <flag> | <option>)* dashboard

bench help

Command: bench help

The help command displays the full help for all commands.

Usage

  • bench help -?
  • bench ( <flag> | <option>)* help ( <flag> | <option>)*

Flags

--append | -a

Append to an existing file, in case a target file is specified.

--no-index | -i

Suppress the index of the commands.

--no-title | -t

Suppress the output of the tool name as the document title.

--no-version | -v

Suppress the output of the tool version number.

Options

--target-file | --out | -o <value>

Specifies a target file to write the help content to.

Expected: A path to a writable file. The target file will be created or overridden.
Default: None

bench list

Command: bench list

The list command lists different kinds of objects from the Bench environment.

Choose a sub-command to specify the kind of object, you want to list.

Usage

  • bench list -?
  • bench ( <flag> | <option>)* list ( <flag> | <option>)*
  • bench ( <flag> | <option>)* list ( <flag> | <option>)* <command> …

Flags

--table | -t

Prints properties of the listed objects as a table. Otherwise only a short form is printed.

Options

--format | -f <value>

Specifies the output format of the listed data.

Expected: Plain | Markdown
Default: Plain

Commands

applibs, l

List app libraries with ID and URL.

apps, a

List apps from the app library.

files, f

List configuration and app library index files.

bench list applibs

Command: bench list applibs

The applibs command lists all loaded app libraries.

Usage

  • bench list applibs -?
  • bench ( <flag> | <option>)* list ( <flag> | <option>)* applibs

bench list apps

Command: bench list apps

The apps command lists apps from the app library.

You can specify the base set of apps and filter the apps to list.

Usage

  • bench list apps -?
  • bench ( <flag> | <option>)* list ( <flag> | <option>)* apps <option>*

Options

--filter | -f <value>

Specifies a filter to reduce the number of listed apps.

Expected: A comma separated list of criteria. E.g. ID=JDK*,!IsInstalled,IsCached.
Default: no filter

--properties | -p <value>

Specifies the properties to display in the listed output. This option only has an effect, if the flag list --table is set.

Expected: A comma separated list of property names.

--set | -s <value>

Specifies the set of apps to list.

Expected: All | Active | NotActive | Activated | Deactivated | NotSupported | Installed | NotInstalled | Cached | NotCached | DefaultApps | Groups | MetaApps | ManagedPackages | ManagedPackagesFromRemote
Default: All

--sort-by | -o <value>

Specifies a property to sort the apps by.

Expected: The name of an app property.
Default: ID

bench list files

Command: bench list files

The files command lists the paths of all loaded configuration files.

Usage

  • bench list files -?
  • bench ( <flag> | <option>)* list ( <flag> | <option>)* files <option>*

Options

--type | -t <value>

Specify the type of files to show.

Expected: BenchConfig | UserConfig | SiteConfig | Config | BenchAppLib | UserAppLib | AppLib | Activation | Deactivation | AppSelection | All
Default: All

bench manage

Command: bench manage

The manage command manages the Bench environment via a number of sub-commands.

Usage

  • bench manage -?
  • bench ( <flag> | <option>)* manage
  • bench ( <flag> | <option>)* manage <command> …

Commands

config, cfg, c

Read or write values from the user configuration.

Syntax: bench manage config <sub-command>

initialize, init, i

Initialize the Bench configuration and start the setup process.

load-app-libs, l

Load the latest app libraries.

Syntax: bench manage load-app-libs <flag>*

reinstall, r

Remove all installed apps, then install all active apps.

renew, n

Redownload all app resources, remove all installed apps, then install all active apps.

setup, s

Run the auto-setup for the active Bench apps.

update, u

Update the app libraries and upgrades all apps.

update-env, e

Update the paths in the Bench environment.

upgrade, g

Download and extract the latest Bench release, then run the auto-setup.

bench manage config

Command: bench manage config

The config command gives access to the Bench user configuration.

Usage

  • bench manage config -?
  • bench ( <flag> | <option>)* manage config
  • bench ( <flag> | <option>)* manage config <command> …

Commands

edit, e

Opens the user configuration in the default Markdown editor.

Syntax: bench manage config edit <flag>*

get, read, g

Reads a configuration value.

Syntax: bench manage config get <Property Name>

set, write, s

Writes a configuration value.

Syntax: bench manage config set <Property Name> <New Value>

bench manage config edit

Command: bench manage config edit

The edit command opens the user configuration in the default Markdown editor.

Usage

  • bench manage config edit -?
  • bench ( <flag> | <option>)* manage config edit <flag>*

Flags

--detached | --async | -d

Do not wait for the editor to be closed.

bench manage config get

Command: bench manage config get

The get command reads a configuration value.

Usage

  • bench manage config get -?
  • bench ( <flag> | <option>)* manage config get <Property Name>

Positional Arguments

1. Property Name

The name of the configuration property to read.

bench manage config set

Command: bench manage config set

The set command writes a configuration value to the user configuration file.

Usage

  • bench manage config set -?
  • bench ( <flag> | <option>)* manage config set <Property Name> <New Value>

Positional Arguments

1. Property Name

The name of the configuration property to write.

2. New Value

The new value for the configuration property.

bench manage downloads

Command: bench manage downloads

The downloads command manages the cached app resources.

Usage

  • bench manage downloads -?
  • bench ( <flag> | <option>)* manage downloads
  • bench ( <flag> | <option>)* manage downloads <command> …

Commands

clean, cl, c

Deletes obsolete app resources.

download, dl, d

Downloads the app resources for all active apps.

purge, x

Deletes all cached app resources.

bench manage initialize

Command: bench manage initialize

The initialize command initializes the Bench configuration and starts the setup process.

Usage

  • bench manage initialize -?
  • bench ( <flag> | <option>)* manage initialize

bench manage load-app-libs

Command: bench manage load-app-libs

The load-app-libs command loads missing app libraries.

Usage

  • bench manage load-app-libs -?
  • bench ( <flag> | <option>)* manage load-app-libs <flag>*

Flags

--update | -u

Clears the cache and loads the latest version of all app libraries.

bench manage reinstall

Command: bench manage reinstall

The reinstall command removes all installed apps, then installs all active apps.

Usage

  • bench manage reinstall -?
  • bench ( <flag> | <option>)* manage reinstall

bench manage renew

Command: bench manage renew

The renew command redownloads all app resources, removes all installed apps, then installs all active apps.

Usage

  • bench manage renew -?
  • bench ( <flag> | <option>)* manage renew

bench manage setup

Command: bench manage setup

The setup command runs the auto-setup for the active Bench apps.

Usage

  • bench manage setup -?
  • bench ( <flag> | <option>)* manage setup

bench manage update

Command: bench manage update

The update command updates the app libraries and upgrades all apps.

Usage

  • bench manage update -?
  • bench ( <flag> | <option>)* manage update

bench manage update-env

Command: bench manage update-env

The update-env command updates the paths in the Bench environment.

Usage

  • bench manage update-env -?
  • bench ( <flag> | <option>)* manage update-env

bench manage upgrade

Command: bench manage upgrade

The upgrade command checks if a new version of Bench is available and installs it.

Usage

  • bench manage upgrade -?
  • bench ( <flag> | <option>)* manage upgrade

bench project

Command: bench project

The project command allows you to perform certain tasks on projects in the Bench environment.

WARNING: This command is not implemented yet.

Usage

  • bench project -?
  • bench ( <flag> | <option>)* project

Command: bench search

The search command searches for apps in the Bench environment.

Choose a sub-command to specify the kind of object, you want to list.

Usage

  • bench search -?
  • bench ( <flag> | <option>)* search ( <flag> | <option>)* …

Flags

--table | -t

Prints the search result as a table. Otherwise only the IDs of found apps are printed.

Options

--format | -f <value>

Specifies the output format of the listed data.

Expected: Plain | Markdown
Default: Plain

Additional Arguments

All additional arguments are used as search keywords.

bench transfer

Command: bench transfer

The transfer command supports different kinds of a copying the whole Bench environment.

Usage

  • bench transfer -?
  • bench ( <flag> | <option>)* transfer
  • bench ( <flag> | <option>)* transfer <command> …

Commands

clone, c

Copy this Bench environment to a different place.

export, e

Create a transfer package of this Bench environment

Syntax: bench transfer export <option>* <target-file>

install, i

Install a Bench environment from an extracted Bench transfer package

Syntax: bench transfer install ( <flag> | <option>)*

bench transfer clone

Command: bench transfer clone

The clone command creates and initializes a clone of this Bench environment in a different location.

Usage

  • bench transfer clone -?
  • bench ( <flag> | <option>)* transfer clone <option>* <target-dir>

Options

--include | -i <value>

Specifies the content included in the export.

Expected: A comma separated list of the following keywords: SystemOnly, Config, Home, Projects, AppLibs, RequiredCache, Cache, RequiredApps, Apps, All
Default: Config,AppLibs,Cache

Positional Arguments

1. target-dir

The target directory for the clone.

Expected: A path to a directory. The directory must not exist yet.

bench transfer export

Command: bench transfer export

The export command creates a transfer package of this Bench environment.

Usage

  • bench transfer export -?
  • bench ( <flag> | <option>)* transfer export <option>* <target-file>

Options

--include | -i <value>

Specifies the content included in the export.

Expected: A comma separated list of the following keywords: SystemOnly, Config, Home, Projects, AppLibs, RequiredCache, Cache, RequiredApps, Apps, All
Default: Config,AppLibs

Positional Arguments

1. target-file

A path to the output file.

Expected: The filename can have one of the following extensions: .zip, .7z, .exe

bench transfer install

Command: bench transfer install

The install command installs a Bench environment from an extracted Bench transfer package.

Usage

  • bench transfer install -?
  • bench ( <flag> | <option>)* transfer install ( <flag> | <option>)*

Flags

--extract-only | --extract | --no-init | -e

Deactivates automatic initialization and setup after the transfer.

Options

--target-dir | --target | --dir | -d <value>

Specifies the target directory for the installation. If left empty, a directory browser will be displayed to choose the target directory.

Expected: A path to a directory. The directory must not exist yet.