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"