github.com/koron/hk@v0.0.0-20150303213137-b8aeaa3ab34c/README.md (about) 1 # hk 2 3 A fast Heroku CLI client. 4 5 ## Overview 6 7 hk is a command line client to the Heroku runtime platform, designed to be as fast as possible. 8 9 ### Disclaimer 10 11 This is beta software. It may still undergo substantial changes during the 12 coming months. You should expect that some functionality may break or be altered without warning. 13 14 ## Motivation 15 16 ### Fast as a feature 17 18 ```bash 19 ## version 20 21 $ time heroku version >/dev/null 22 real 0m1.813s 23 24 $ time hk version >/dev/null 25 real 0m0.016s 26 27 ## list 28 29 $ time heroku apps >/dev/null 30 real 0m3.830s 31 32 $ time hk apps >/dev/null 33 real 0m0.785s 34 ``` 35 36 ### Iterative Development 37 38 A release mechanism was created for hk in the beginning: the binary updates 39 itself. This gives us confidence in iterative development, which we value 40 highly, because it gives us the ability to release very often knowing users will 41 see the updates in a timely manner. 42 43 ### The power of Go 44 45 hk demonstrates the power of the Go language, runtime, systems access, and 46 distribution story (a single, statically linked binary with no dependencies) 47 which are all very appealing to Heroku. 48 49 ### Unix 50 51 Heroku loves Unix. This client should reflect that. Commands map to their unix 52 ancestors’ names and flags where applicable. 53 54 ## Installation 55 56 > Please note that versions of hk installed from source are unsupported and 57 > should only be installed for development purposes. 58 59 ### Mac OS X, Linux, BSD 60 61 Pre-built binaries are available for Mac OS X, Linux, and BSD. Once installed, 62 these binaries will automatically update themselves when new releases are 63 available. 64 65 To install a pre-built binary release, run the following one-liner: 66 67 ```bash 68 $ L=/usr/local/bin/hk && curl -sL -A "`uname -sp`" https://hk.heroku.com/hk.gz | zcat >$L && chmod +x $L 69 ``` 70 71 The URL [https://hk.heroku.com/hk.gz](https://hk.heroku.com/hk.gz) will attempt 72 to detect your OS and CPU architecture based on the User-Agent, then redirect 73 you to the latest release for your platform. 74 75 ### Windows 76 77 Currently, you need to have a [Go development environment][go-install] to 78 install hk on Windows. Compiled binaries with automatic updating are available 79 for Windows, but the installer is not ready yet. 80 81 $ go get github.com/heroku/hk 82 83 Please note that this installation method is unsupported. 84 85 ## Usage 86 87 The basic usage of hk is: 88 89 ``` 90 Usage: hk <command> [-a app] [options] [arguments] 91 ``` 92 93 For more details, and to learn about differences between hk and the Heroku Ruby 94 CLI, please see the [getting started guide](./doc/guide.md). 95 96 ## Shell Completion 97 98 Shell completion scripts for hk have been written for zsh and bash. Both files 99 are located in [./contrib](./contrib/). 100 101 The zsh completion script completes all command names and help topics. It also 102 completes flags and other arguments for many commands: 103 104 ![](http://cl.ly/image/3n1X0q3y2E17/Screen%20Shot%202014-03-07%20at%201.52.26%20PM.png) 105 106 ![](http://cl.ly/image/0u3v0T2m352h/Image%202014-03-09%20at%2011.34.17%20AM.png) 107 108 ![](http://f.cl.ly/items/2X200V0h2M0L1Q1w0x38/Image%202014-03-11%20at%203.12.23%20PM.png) 109 110 The bash completion script completes only command names at this time. 111 112 ## Config 113 114 hk allows some configuration using git config. 115 116 ### Use strict flag ordering / disable interspersed flags and non-flag arguments 117 118 Enable: 119 120 ``` 121 $ git config --global --bool hk.strict-flag-ordering true 122 ``` 123 124 Disable: 125 126 ``` 127 $ git config --global --unset hk.strict-flag-ordering 128 ``` 129 130 ## Plugins 131 132 hk currently has a minimal plugin system. It may see substantial changes in the future, and those changes may break existing plugins or change the architecture at any time. Use this functionality at your own risk. 133 134 Plugins are executables located in HKPATH or, if HKPATH does not exist, in /usr/local/lib/hk/plugin. They are executed when hk does not know command X and an installed plugin X exists. The special case default plugin will be executed if hk has no command or installed plugin named X. 135 136 hk will set these environment variables for a plugin: 137 138 * HEROKU_API_URL - The url containing the username, password, and host to the api endpoint. 139 * HKAPP - The app as determined by the git heroku remote, if available. 140 * HKUSER - The username from either HEROKU_API_URL or .netrc 141 * HKPASS - The password from either HEROKU_API_URL or .netrc 142 * HKHOST - The hostname for the API endpoint 143 144 ## Development 145 146 hk requires Go 1.2 or later and uses [Godep](https://github.com/kr/godep) to manage dependencies. 147 148 $ cd hk 149 $ vim main.go 150 $ godep go build 151 $ ./hk apps 152 153 Please follow the [contribution guidelines](./CONTRIBUTING.md) before submitting 154 a pull request. 155 156 [go-install]: http://golang.org/doc/install "Golang installation"