USAGE.md

   1 # How to Use Homebrew-cask
   2
   3 ## Getting Started
   4
   5 First ensure you have Homebrew version `0.9.5` or higher:
   6
   7 ```bash
   8 $ brew --version
   9 0.9.5
  10 ```
  11
  12 Install the homebrew-cask tool:
  13
  14 ```bash
  15 $ brew install caskroom/cask/brew-cask
  16 ```
  17
  18 ## Frequently Used Commands
  19
  20 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
  21 commands are:
  22
  23 * `search` — searches all known Casks
  24 * `install` — installs the given Cask
  25 * `uninstall` — uninstalls the given Cask
  26
  27 ## Searching for Casks
  28
  29 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:
  30
  31 ```bash
  32 $ brew cask search chrome
  33 google-chrome
  34 ```
  35
  36 A `search` command with no search term will list all available Casks:
  37
  38 ```bash
  39 $ brew cask search
  40 # <list of all available Casks>
  41 ```
  42
  43 ## Installing Casks
  44
  45 The command `brew cask install` accepts a Cask token as returned by `brew cask search`. Let’s try to install Google Chrome:
  46
  47 ```bash
  48 $ brew cask install google-chrome
  49 ==> Downloading https://dl.google.com/chrome/mac/stable/GGRO/googlechrome.dmg
  50 ==> Success! google-chrome installed to /opt/homebrew-cask/Caskroom/google-chrome/stable-channel
  51 ==> Linking Google Chrome.app to /Users/paulh/Applications/Google Chrome.app
  52 ```
  53
  54 ## Uninstalling Casks
  55
  56 Easy peasy:
  57
  58 ```bash
  59 $ brew cask uninstall google-chrome
  60 ```
  61
  62 This will both uninstall the Cask and remove symlinks which were created in `~/Applications`.
  63
  64 To uninstall all versions of a Cask, use `--force`:
  65
  66 ```bash
  67 $ brew cask uninstall --force google-chrome
  68 ```
  69
  70 Note that `uninstall --force` is currently imperfect. See the man page for more information.
  71
  72 ## Other Commands
  73
  74 * `info` — displays information about the given Cask
  75 * `list` — with no args, lists installed Casks; given installed Casks, lists staged files
  76 * `fetch` — downloads Cask resources to local cache (with `--force`, re-download even if already cached)
  77 * `doctor` — checks for configuration issues
  78 * `cleanup` — cleans up cached downloads (with `--outdated`, only cleans old downloads)
  79 * `home` — opens the homepage of the given Cask; or with no arguments, the homebrew-cask project page
  80 * `update` — a synonym for `brew update`
  81 * `zap` — try to remove *all* files associated with a Cask (including resources which may be shared with other applications)
  82
  83 The following commands are for Cask authors:
  84
  85 * `audit` — verifies installability of Casks
  86 * `cat` — dumps the given Cask to the standard output
  87 * `create` — creates a Cask and opens it in an editor
  88 * `edit` — edits the given Cask
  89
  90 The following aliases and abbreviations are provided for convenience:
  91
  92 * `ls` — `list`
  93 * `-S` — `search`
  94 * `rm`, `remove` — `uninstall`
  95 * `up` — `update`
  96 * `dr` — `doctor`
  97
  98 ## Inspecting Installed Casks
  99
 100 List all installed Casks
 101
 102 ```bash
 103 $ brew cask list
 104 adium          google-chrome     onepassword
 105 ```
 106
 107 Show details about a specific Cask:
 108
 109 ```bash
 110 $ brew cask info caffeine
 111 caffeine: 1.1.1
 112 http://lightheadsw.com/caffeine/
 113 Not installed
 114 https://github.com/caskroom/homebrew-cask/blob/master/Casks/caffeine.rb
 115 ```
 116
 117 ## Updating/Upgrading Casks
 118
 119 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.
 120
 121 It is generally safe to run updates from within an Application.
 122
 123 ## Updating/Upgrading the Homebrew-cask Tool
 124
 125 When a new version homebrew-cask is released, it will appear in the output of `brew outdated` after running `brew update`. You can upgrade it via the normal Homebrew `brew upgrade` workflow:
 126
 127 ```bash
 128 $ brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup
 129 ```
 130
 131 ## Additional Taps (optional)
 132
 133 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.
 134
 135 | Tap name | description |
 136 | -------- | ----------- |
 137 | [caskroom/versions](https://github.com/caskroom/homebrew-versions)     | contains alternate versions of Casks (e.g. betas, nightly releases, old versions)
 138 | [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
 139 | [caskroom/unofficial](https://github.com/caskroom/homebrew-unofficial) | contains Casks that install unofficial builds or forks
 140
 141 There are also [alternate Cask Taps](doc/alternate_cask_taps.md#alternate-cask-taps-maintained-by-users) maintained by users.
 142
 143 You can tap any of the above with a `brew tap` command:
 144
 145 ```bash
 146 $ brew tap <tap_name>
 147 ```
 148
 149 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.
 150
 151 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`:
 152
 153 ```bash
 154 $ brew cask install caskroom/fonts/font-symbola
 155 ```
 156
 157 ## Options
 158
 159 `brew cask` accepts a number of options:
 160
 161 * `--version`: print version and exit
 162 * `--debug`: output debug information
 163 * `--no-binaries`: skip symlinking executable binaries into `/usr/local/bin`
 164
 165 You can also modify the default installation locations used when issuing `brew cask install`:
 166
 167 * `--caskroom=/my/path` determines where the actual applications will be located.
 168 Should be handled with care — setting it outside `/opt` or your home directory might mess up your system.
 169 Default is `/opt/homebrew-cask/Caskroom`.
 170 * `--appdir=/my/path` changes the path where the symlinks to the applications (above)
 171 will be generated. This is commonly used to create the links in the _root_ Applications directory
 172 instead of the _home_ Applications directory by specifying `--appdir=/Applications`. Default is `~/Applications`.
 173 * `--prefpanedir=/my/path` changes the path for PreferencePane symlinks.
 174 Default is `~/Library/PreferencePanes`
 175 * `--qlplugindir=/my/path` changes the path for Quicklook Plugin symlinks.
 176 Default is `~/Library/QuickLook`
 177 * `--fontdir=/my/path` changes the path for Fonts symlinks.
 178 Default is `~/Library/Fonts`
 179 * `--binarydir=/my/path` changes the path for binary symlinks.
 180 Default is `/usr/local/bin`
 181 * `--input_methoddir=/my/path` changes the path for Input Methods symlinks.
 182 Default is `~/Library/Input Methods`
 183 * `--screen_saverdir=/my/path` changes the path for Screen Saver symlinks.
 184 Default is `~/Library/Screen Savers`
 185
 186 To make these settings persistent, you might want to add the following line to your `.bash_profile` or `.zshenv`:
 187
 188 ```bash
 189 # Specify your defaults in this environment variable
 190 export HOMEBREW_CASK_OPTS="--appdir=/Applications --caskroom=/etc/Caskroom"
 191 ```
 192
 193 Note that you still can override the environment variable `HOMEBREW_CASK_OPTS` by _explicitly_ providing options in the command line:
 194
 195 ```bash
 196 # Will force the Chrome app to be linked to ~/Applications
 197 # even though HOMEBREW_CASK_OPTS specified /Applications
 198 $ brew cask install --appdir="~/Applications" google-chrome
 199 ```
 200
 201 ## Advanced searching
 202
 203 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:
 204
 205 ```bash
 206 $ brew cask search '/^google.c[a-z]rome$/'
 207 google-chrome
 208 ```
 209
 210 ## Other Ways to Specify a Cask
 211
 212 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:
 213
 214 * A token as returned by `brew cask search`, _eg_: `google-chrome`.
 215 * A fully-qualified token which includes the Tap, _eg_: `caskroom/fonts/font-symbola`.
 216
 217 `brew cask` also accepts three other forms as arguments
 218
 219 * A path to a Cask file, _eg_: `/usr/local/Cellar/brew-cask/0.25.0/Casks/google-chrome.rb`.
 220 * A `curl`-retrievable URI to a Cask file, _eg_: `https://raw.github.com/caskroom/homebrew-cask/f54bbfaae0f2fa7210484f46313a459cb8a14d2f/Casks/google-chrome.rb`.
 221 * 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`.
 222
 223 The last three forms are intended for users who wish to maintain private Casks.
 224
 225 ## Taps
 226
 227 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.