hk(1) -- Simplify your access to Heroku on the command-line

SYNOPSIS

hk **alias** _app_string_

hk **any heroku invocation** _app_string_

INSTALL

$ gem install hk

DESCRIPTION

hk is an alias system for Heroku's command-line app that does three things:

Wrap complex or cumbersome commands and options into single-word (or single-letter) aliases (e.g. hk logs will do heroku logs --tail)
Derive application names from shorter-strings (e.g. hk logs f-p will run heroku logs --tail --app=foo-production)
Alleviates you from typing heroku, which is hard to type and prone to misspellings

hk can easily be extended with whatever command aliases you would like. It also passes through any unknown command to the underlying heroku command, but does do the app name derivation.

COMMAND ALIASING

Command aliasing is fairly straightforward - a string is used to generate a more complex heroku command invocation. You can create your own in ~/.hk/commands/commands.rb (boilerplate which can be created via hk init).

desc 'Get app info'
arg_name Hk::ARG_NAME
command :info do |c|
  c.action do |_,_,args|
    Hk.run("apps:info",args)
  end
end

This code is the GLI DSL, so you can use that entire API if you want to, however the above is a minimal example.

You'll note that your command now shows up if you do hk help.

APP NAME DERIVATION

If your team is maintaining various apps on heroku, and using it for staging, it can be quite cumbersome to be constantly typing out the names of apps. It's also somewhat dangerous to rely on the .git/config because it obfuscates what's going to happen behind your current directory.

hk will derive your application name, assuming that you use a canonical naming structure that is app_name-environment_name. app_name is a logical name for your app, e.g. "foobar". environment_name is a logical name for an environment, like "staging" or "production".

So, instead of typing --app=foobar-production, you can simply type f-p. As long as you have no other app that starts with "f", and no other environment that starts with "p" (based on the output of heroku apps), then hk will derive the name. You can add more letters to disambiguate, so if you had an app call "frob-production", you would use "fo-p" for "foobar-production" and "fr-p" for "frob-production"

OPTIONS

--heroku PATH_TO_HEROKU: Specify where the heroku command line app is. If omitted, will just use your path
--verbose: If specified, will output the heroku command being executed
-n,--no-app-derivation: If specified, will skip deriving the app and tacking on a --app option

EXAMPLES

There are three builtin aliases (which you can disable by setting SKIP_DEFAULTS=true in your customizations file): console, logs, and psql:

hk logs f-p
# heroku logs --tail --app=foo-production

hk console f-p
# heroku run rails c --app=foo-production

hk psql f-p
# heroku pg:psql --app=foo-production

Unknown commands will pass through, but app derivation will still take place:

hk run rake db:migrate f-s
# heroku run rake db:migrate --app=foo-staging

You can also be explicit about where heroku is you don't want to rely on your PATH:

hk --heroku=/sbin/herkou logs f-p
# /sbin/heroku logs --tail --app=foo-production

And, you can skip all the magic if you like:

hk -n --heroku=/sbin/herkou pg:info --app=hellblazer
# sbin/herkou pg:info --app=hellblazer

Note that because this is backed by GLI, you only need to specify the command-name with enough characters to disambiguate it. For example, given the three builtins, these two are equivalent:

hk logs f-p
hk l f-p

AUTHOR

David Copeland, davec (at) naildrivin5.com