hk is a new command line client to the Heroku platform, designed to be fast and lightweight. While hk is intended to replace the Heroku Ruby CLI, it's designed as a completely new tool rather than a drop-in replacement.

Installing hk

hk is distributed as an auto-updating executable. Once you've installed it, hk will periodically perform a version check in the background. If a newer version is found, hk will update itself automatically.

hk is currently only being distributed for Mac OS X and Linux users. More user-friendly installers, including one for Windows, are planned.

To install a pre-built binary release, run the following in a command line terminal:

L=/usr/local/bin/hk && curl -sL -A "`uname -sp`" https://hk.heroku.com/hk.gz | zcat >$L && chmod +x $L

If you wish, you can customize the install location by modifying the L= variable at the beginning of that command.

The URL https://hk.heroku.com/hk.gz will attempt to detect your OS and CPU architecture based on the User-Agent, then redirect you to the latest release for your platform.

If you've installed hk on a machine that already had the Heroku Ruby CLI, you can start using hk immediately. If it's a new machine or you've never logged in, you'll need to do so by running hk login.

Getting help with hk

hk has a simple help system. The most common commands are listed in the basic help output, which is also available via hk help:

$ hk help
Usage: hk <command> [-a app] [options] [arguments]


Commands:

    create          create an app
    apps            list apps
    dynos           list dynos
    releases        list releases
    release-info    show release info
    rollback        roll back to a previous release
    addons          list addons
    addon-add       add an addon
    addon-destroy   destroy an addon
    scale           change dyno quantities and sizes
    restart         restart dynos
    set             set env var
    unset           unset env var
    env             list env vars
    run             run a process in a dyno
    log             stream app log lines
    info            show app info
    rename          rename an app
    destroy         destroy an app
    domains         list domains
    domain-add      add a domain
    domain-remove   remove a domain
    version         show hk version

Run 'hk help [command]' for details.


Additional help topics:

    commands  list all commands with usage
    environ   environment variables used by hk
    plugins   interface to plugin commands
    more      additional commands, less frequently used
    about     information about hk (e.g. copyright, license, etc.)

Commands that are used less frequently are listed under hk help more. For any specific command, you can run hk help <command> to get the detailed help and usage info for that command.

Important differences from the Heroku Ruby CLI

The Heroku Ruby CLI organized its commands under nested namespaces, separated with colons (i.e. domains:add). Most, but not all, of these namespaces were pluralized.

hk, however, uses a simple, flat command space (i.e. domains and domain-add). Commands use pluralized nouns where it's logical to do so, such as lists of items (apps, dynos, addons, releases). The rest of the commands are named with singular nouns because they deal with a single resource (addon-add, domain-remove, release-info).

The Heroku Ruby CLI allowed users to specify an app for commands via a -a <app> flag, or via a git remote with -r <remote>. hk combines these flags into a single -a <app or remote> flag.

Guide to hk commands for Heroku users

Many commands are similar in both the Heroku Ruby CLI and hk. However, some commands have different names and take different arguments. This is a list of frequently used commands, showing how to accomplish the same thing with either CLI.

Apps

Create an app

$ heroku create myapp

$ hk create myapp

With a region specified:

$ heroku create --region eu myapp

$ hk create -r eu myapp

List apps

$ heroku list

$ hk apps

Show an app's info

$ heroku info

$ hk info

Destroy an app

$ heroku destroy -a myapp

$ hk destroy myapp

The heroku destroy command can infer your app name from the current directory's git remotes. For safety, however, hk destroy always requires you to specify the name of the app you want to destroy.

This command can permanently destroy data, so it prompts for confirmation.

Rename an app

$ heroku rename -a oldappname newappname

$ hk rename oldappname newappname

View your application log

$ heroku logs --tail

$ hk log

The hk log command follows your application log stream by default (which required a --tail flag in the Toolbelt).

Dynos

Change dyno scale

$ heroku ps:scale web=2 worker=4:PX

$ hk scale web=2 worker=4:PX

This command is mostly identical in hk, except that it doesn't support scaling by relative increments (i.e. web+2).

List dynos

$ heroku ps

$ hk dynos

App configuration (environment)

Set an environment variable on an app

$ heroku config:set KEY=value

$ hk set KEY=value

List app's environment settings

$ heroku config

$ hk env

Show a single environment variable

$ heroku config:get KEY

$ hk get KEY

Unset an environment variable on an app

$ heroku config:unset KEY1 KEY2

$ hk unset KEY1 KEY2

Domain Names

List domain names

$ heroku domains

$ hk domains

Add a domain name

$ heroku domains:add www.test.com

$ hk domain-add www.test.com

Remove a domain name

$ heroku domains:remove www.test.com

$ hk domain-remove www.test.com

Add-ons

List add-ons on an app

$ heroku addons

$ hk addons

Add an add-on

$ heroku addons:add heroku-postgresql

$ hk addon-add heroku-postgresql

With additional provisioning options:

$ heroku addons:add heroku-postgresql --fork RED

$ hk addon-add heroku-postgresql fork=red

Additional add-on config is provided as key=value pairs rather than --key value flags.

Destroy an add-on

$ heroku addons:remove redistogo

$ hk addon-remove redistogo

Next, a Heroku Postgres addon:

$ heroku addons:remove heroku-postgresql:dev

$ hk addon-remove heroku-postgresql-blue

Add-ons in hk are referenced by their name. Usually this is just the addon provider's name, but for Heroku Postgres, it's of the form: heroku-postgresql-color. In either case, the name matches what's displayed in hk addons.