2016-01-11 20:00:37 +08:00
# How to Use Homebrew-Cask
2013-04-29 03:20:03 +08:00
2013-12-08 02:16:58 +08:00
## Getting Started
2013-04-29 03:20:03 +08:00
2015-09-07 21:33:37 +08:00
First ensure you have Homebrew version `0.9.5` or higher:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew --version
0.9.5
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Frequently Used Commands
2013-11-10 21:36:03 +08:00
2016-01-11 20:00:37 +08:00
Homebrew-Cask is implemented as a subcommand of Homebrew. All Homebrew-Cask commands begin with `brew cask` . Homebrew-Cask has its own set of command verbs many of which are similar to Homebrew’ s. The most frequently-used
2014-01-15 22:55:30 +08:00
commands are:
2013-12-16 05:08:27 +08:00
2015-09-07 21:33:37 +08:00
* `search` — searches all known Casks
* `install` — installs the given Cask
* `uninstall` — uninstalls the given Cask
2013-12-16 05:08:27 +08:00
2014-01-15 22:55:30 +08:00
## Searching for Casks
2013-12-16 05:08:27 +08:00
2015-09-16 06:24:11 +08:00
The `brew cask search` command accepts a series of substring arguments, and returns tokens representing matching Casks. Let’ s see if there’ s a Cask for Google Chrome:
2013-12-16 05:08:27 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask search chrome
google-chrome
```
2013-11-10 21:36:03 +08:00
2014-01-15 22:55:30 +08:00
A `search` command with no search term will list all available Casks:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask search
# <list of all available Casks>
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Installing Casks
2013-04-29 03:20:03 +08:00
2015-09-16 06:24:11 +08:00
The command `brew cask install` accepts a Cask token as returned by `brew cask search` . Let’ s try to install Google Chrome:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask install google-chrome
==> Downloading https://dl.google.com/chrome/mac/stable/GGRO/googlechrome.dmg
2016-06-01 03:49:19 +08:00
==> Moving App 'Google Chrome.app' to '/Applications/Google Chrome.app'
2016-06-12 19:07:20 +08:00
🍺 google-chrome staged at '/usr/local/Caskroom/google-chrome/latest' (3 files, 288K)
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Uninstalling Casks
Easy peasy:
```bash
$ brew cask uninstall google-chrome
```
2016-06-01 03:23:21 +08:00
This will both uninstall the Cask and remove applications which were moved to `/Applications` .
2014-01-15 22:55:30 +08:00
2014-09-16 01:50:09 +08:00
To uninstall all versions of a Cask, use `--force` :
```bash
$ brew cask uninstall --force google-chrome
```
2015-09-16 06:24:11 +08:00
Note that `uninstall --force` is currently imperfect. See the man page for more information.
2014-09-16 01:50:09 +08:00
2014-01-15 22:55:30 +08:00
## Other Commands
2015-09-07 21:33:37 +08:00
* `info` — displays information about the given Cask
* `list` — with no args, lists installed Casks; given installed Casks, lists staged files
2016-01-06 01:57:29 +08:00
* `fetch` — downloads remote application files for the given Cask to the local cache (with `--force` , re-download even if already cached)
2015-09-07 21:33:37 +08:00
* `doctor` — checks for configuration issues
* `cleanup` — cleans up cached downloads (with `--outdated` , only cleans old downloads)
2016-01-11 20:00:37 +08:00
* `home` — opens the homepage of the given Cask; or with no arguments, the Homebrew-Cask project page
2015-09-07 21:33:37 +08:00
* `update` — a synonym for `brew update`
2016-01-06 01:57:29 +08:00
* `zap` — try to remove *all* files associated with a Cask (may include resources shared with other applications)
2014-01-15 22:55:30 +08:00
The following commands are for Cask authors:
2013-04-29 03:20:03 +08:00
2015-09-07 21:33:37 +08:00
* `audit` — verifies installability of Casks
* `cat` — dumps the given Cask to the standard output
* `create` — creates a Cask and opens it in an editor
* `edit` — edits the given Cask
2013-04-29 03:20:03 +08:00
2014-02-24 21:06:46 +08:00
The following aliases and abbreviations are provided for convenience:
2015-09-07 21:33:37 +08:00
* `ls` — `list`
* `-S` — `search`
* `rm` , `remove` — `uninstall`
* `up` — `update`
* `dr` — `doctor`
2014-02-24 21:06:46 +08:00
2015-10-23 12:29:12 +08:00
## Tab Completion
[Homebrew/homebrew-completions ](https://github.com/Homebrew/homebrew-completions ) supports `bash` and `fish` completions (only for `brew-cask` right now). Install them with:
```bash
2015-10-24 00:39:01 +08:00
$ brew install homebrew/completions/brew-cask-completion
2015-10-23 12:29:12 +08:00
```
For `zsh` completion support, simply run:
```bash
2016-03-24 06:58:07 +08:00
$ brew install zsh-completions
2015-10-23 12:29:12 +08:00
```
2013-04-29 03:20:03 +08:00
## Inspecting Installed Casks
2016-01-11 20:00:37 +08:00
List all installed Casks:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask list
adium google-chrome onepassword
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
Show details about a specific Cask:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask info caffeine
caffeine: 1.1.1
2016-01-11 20:00:37 +08:00
Caffeine
2014-01-15 22:55:30 +08:00
http://lightheadsw.com/caffeine/
Not installed
2014-06-21 07:19:07 +08:00
https://github.com/caskroom/homebrew-cask/blob/master/Casks/caffeine.rb
2016-01-11 20:00:37 +08:00
==> Contents
Caffeine.app (app)
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
## Updating/Upgrading Casks
2016-01-11 20:00:37 +08:00
Since the Homebrew-Cask repository is a Homebrew Tap, you’ ll pull down the latest Casks every time you issue the regular Homebrew command `brew update` . Currently, Homebrew-Cask cannot always detect if an application has been updated. You can force an update via the command `brew cask install --force` . We are working on improving this.
2013-04-29 03:20:03 +08:00
2016-01-11 20:00:37 +08:00
It is generally safe to run updates from within an application.
2013-04-29 03:20:03 +08:00
2016-01-11 20:00:37 +08:00
## Updating/Upgrading the Homebrew-Cask Tool
2014-01-15 22:55:30 +08:00
2016-07-07 05:13:56 +08:00
Homebrew [automatically taps and keeps Homebrew-Cask updated ](https://github.com/caskroom/homebrew-cask/pull/15381 ). `brew update` is all that is required.
2014-01-15 22:55:30 +08:00
## Additional Taps (optional)
2016-01-11 20:00:37 +08:00
The primary Homebrew-Cask Tap includes most of the Casks that a typical user will be interested in. There are a few additional Taps where we store different kinds of Casks.
2014-01-15 22:55:30 +08:00
| Tap name | description |
| -------- | ----------- |
2016-02-19 23:37:25 +08:00
| [caskroom/versions ](https://github.com/caskroom/homebrew-versions ) | contains alternate versions of Casks (e.g. betas, nightly releases, old versions)
| [caskroom/fonts ](https://github.com/caskroom/homebrew-fonts ) | contains Casks that install fonts, which are kept separate so we can educate users about the different licensing landscape around font installation/usage
2016-02-20 23:55:39 +08:00
| [caskroom/eid ](https://github.com/caskroom/homebrew-eid ) | contains Casks that install electronic identity card software of various countries
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
You can tap any of the above with a `brew tap` command:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew tap < tap_name >
```
2015-09-16 06:24:11 +08:00
after which, Casks from the new Tap will be available to `search` or `install` just like Casks from the main Tap. `brew update` will automatically keep your new Tap up to date.
2014-01-15 22:55:30 +08:00
2015-09-16 04:47:35 +08:00
You may also specify a fully-qualified Cask token (which includes the Tap) for any `brew cask` command. This will implicitly add the Tap if you have not previously added it with `brew tap` :
2014-01-15 22:55:30 +08:00
```bash
$ brew cask install caskroom/fonts/font-symbola
```
2013-04-29 03:20:03 +08:00
## Options
2014-01-06 04:30:53 +08:00
`brew cask` accepts a number of options:
* `--version` : print version and exit
* `--debug` : output debug information
2014-01-15 22:55:30 +08:00
* `--no-binaries` : skip symlinking executable binaries into `/usr/local/bin`
2016-06-26 03:29:53 +08:00
* `--require-sha` : abort installation of cask if no checksum is defined
2014-01-06 04:30:53 +08:00
2014-05-13 22:46:32 +08:00
You can also modify the default installation locations used when issuing `brew cask install` :
2013-12-14 17:07:26 +08:00
2013-12-14 17:10:50 +08:00
* `--caskroom=/my/path` determines where the actual applications will be located.
2016-06-12 19:07:20 +08:00
Default is `$(brew --repository)/Caskroom`
2016-06-01 03:23:21 +08:00
* `--appdir=/my/path` changes the path where the applications (above)
will be moved. Default is `/Applications` .
* `--prefpanedir=/my/path` changes the path for PreferencePanes.
2013-12-14 17:07:26 +08:00
Default is `~/Library/PreferencePanes`
2016-06-01 03:23:21 +08:00
* `--qlplugindir=/my/path` changes the path for Quicklook Plugins.
2013-12-14 17:07:26 +08:00
Default is `~/Library/QuickLook`
2016-06-01 03:23:21 +08:00
* `--fontdir=/my/path` changes the path for Fonts.
2013-12-14 17:07:26 +08:00
Default is `~/Library/Fonts`
2016-01-11 20:00:37 +08:00
* `--binarydir=/my/path` changes the path for Binary symlinks.
2014-01-06 04:30:53 +08:00
Default is `/usr/local/bin`
2016-06-01 03:23:21 +08:00
* `--input_methoddir=/my/path` changes the path for Input Methods.
2014-01-14 01:21:44 +08:00
Default is `~/Library/Input Methods`
2016-06-01 03:23:21 +08:00
* `--screen_saverdir=/my/path` changes the path for Screen Savers.
2014-01-28 23:17:50 +08:00
Default is `~/Library/Screen Savers`
2014-01-15 22:55:30 +08:00
To make these settings persistent, you might want to add the following line to your `.bash_profile` or `.zshenv` :
2013-04-29 03:20:03 +08:00
```bash
2013-12-14 17:10:50 +08:00
# Specify your defaults in this environment variable
2016-06-01 03:23:21 +08:00
export HOMEBREW_CASK_OPTS="--appdir=~/Applications --caskroom=/etc/Caskroom"
2013-12-14 17:07:26 +08:00
```
2013-04-29 03:20:03 +08:00
2015-09-16 06:24:11 +08:00
Note that you still can override the environment variable `HOMEBREW_CASK_OPTS` by _explicitly_ providing options in the command line:
2013-04-29 03:20:03 +08:00
2013-12-14 17:07:26 +08:00
```bash
2016-06-02 05:31:35 +08:00
# Will force the Chrome app to be moved to /Applications
2016-06-01 03:23:21 +08:00
# even though HOMEBREW_CASK_OPTS specified ~/Applications
$ brew cask install --appdir="/Applications" google-chrome
2013-04-29 03:20:03 +08:00
```
2016-01-11 20:00:37 +08:00
## Advanced Searching
2014-01-23 01:56:37 +08:00
2015-09-16 06:24:11 +08:00
The default search algorithm is a lax substring approach, which does not use the command-line arguments exactly as given. If you need to specify a search more precisely, a single search argument enclosed in `/` characters will be taken as a Ruby regular expression:
2014-01-23 01:56:37 +08:00
```bash
$ brew cask search '/^google.c[a-z]rome$/'
google-chrome
```
2014-01-15 22:55:30 +08:00
## Other Ways to Specify a Cask
2015-09-16 06:24:11 +08:00
Most `brew cask` commands can accept a Cask token as an argument. As described above, the token on the command line can take the form of:
2014-01-15 22:55:30 +08:00
2015-09-16 06:24:11 +08:00
* A token as returned by `brew cask search` , _eg_ : `google-chrome` .
* A fully-qualified token which includes the Tap, _eg_ : `caskroom/fonts/font-symbola` .
2014-01-15 22:55:30 +08:00
2016-01-11 20:00:37 +08:00
`brew cask` also accepts three other forms as arguments:
2014-01-15 22:55:30 +08:00
2015-12-21 04:09:16 +08:00
* A path to a Cask file, _eg_ : `/usr/local/Library/Taps/caskroom/homebrew-cask/Casks/google-chrome.rb` .
* A `curl` -retrievable URI to a Cask file, _eg_ : `https://raw.githubusercontent.com/caskroom/homebrew-cask/f25b6babcd398abf48e33af3d887b2d00de1d661/Casks/google-chrome.rb` .
2015-09-16 06:24:11 +08:00
* A file in the current working directory, _eg_ : `my-modfied-google-chrome.rb` . Note that matching Tapped Cask tokens will be preferred over this form when there is a conflict. To force the use of a Cask file in the current directory, specify a pathname with slashes, _eg_ : `./google-chrome.rb` .
2014-01-15 22:55:30 +08:00
2014-06-03 22:21:42 +08:00
The last three forms are intended for users who wish to maintain private Casks.
2014-01-15 22:55:30 +08:00
## Taps
2013-04-29 03:20:03 +08:00
2015-09-16 06:24:11 +08:00
You can add Casks to your existing (or new) Taps: just create a directory named `Casks` inside your Tap, put your Cask files there, and everything will just work.