Command Reference

This is a reference for commands available in Heighliner. It is sorted by importance but not necessarily by how one would use them.

Global Options

These options can be used with any of the commands below.

-v --verbose Verbose mode

Verbose mode. This tells Heighliner to spit out all the output of the commands it runs so it is clear if something went wrong. By default, Heighliner simply writes a period character for each line of output to avoid being noisy.

heighliner init

This initializes an environment in Heighliner. In reality this assigns your current directory to a particular environment name. For example

heighliner init hats

Will assign this directory to the name hats.

This is an important first step because this will determine the domain name you can use to access this environment. For example if you start it up the domain will be hats.lvh.me if you did not set the suffix. If you did set the suffix the domain will be hats.<whatever the suffix is>. More info on suffixes here.

Errors

• This command requires you be in a directory that has a Steerfile. If you don't have one, you will get the message

Error: No Steerfile in current directory.
Try --help for help.

• If you try to run this command without an environment name you will get

Error: Needs environment name.
Try --help for help.

• If you already initialized the current directory in Heighliner you will get this message:

Error: Already initialized as hats.
Try --help for help.

heighliner up

This command will bring up the app in the current directory, but only if it was initialized using heighliner init.

Usually in user testing we noticed that most people prefer to start up their environment using heighliner up -av.

Options

-a --attach Attach

Attaches to the process after starting up. By default Heighliner will start up the app and run in the background. Using this parameter the process will run in the foreground, which can be useful for debugging or if you are in a GUI where switching terminals is very easy.

If you use this option, and bash exit or Ctrl+C interrupt out and the process you started ends, it will close the process. Unlike if you ran heighliner up without this option, and then ran heighliner attach.

Parameters

This command takes a command line as parameters, which means you can go heighliner up -av bash. This will start the application in the foreground and run bash. You can also use it to go heighliner up -av rails c or heighliner up -av sh -c 'mylongcommand; andmorestuff' or whatever suits your fancy.

Errors

• If you try running this command in a directory that has not been initialized, you will get the error:

Error: No environment? Please use heighliner init <name>.
Try --help for help.

heighliner login <cmd>

If there already exists a running process that was started by heighliner up, you can simply login from the side using the default user as defined in its Dockerfile this way. Usually you want to provide a parameter, such as heighliner login bash or something. It will always be started in TTY and interactive.

Errors

• If you try and run this in a dir where the process is not up and running, you will get a message like this:

Error response from daemon: No such container: hats-app

or one like this:

Error response from daemon: container ceff5f43ca1632294512afd1ed88e30d051bd97438204bb34674fea75e001eab is not running

heighliner root <cmd>

This command is essentially the same as heighliner login except it forces the login to use the root user. This can sometimes be useful if the container was built with very tight perms on the user, or does not have sudo installed in it.

heighliner show <thing>

This shows special globals that were set using heighliner set. Valid parameters right now are

• ports
• cert-source
• http-suffix

Parameters

ports Ports reserved for app

This tells you what ports are reserved for the app. While most traffic should go to the thing through the environment name, sometimes you want the actual port number if you want to connect to it to check stuff. Example output is:

app: 9015
db: 9016

cert-source Certificate source

This tells you the URL or folder from which SSL/HTTPS certificates are read. You can use this to check if you have it set to the right place.

Only cert-url and cert-folder sources are printed. If your source is a 1Password item this prints a blank line — check ~/.heighliner/config.yml to see it.

http-suffix HTTP Suffix

This tells you what the HTTP suffix is. See suffixes. Usually you use this with conjunction with the cert source above so you can request wildcard certificates from domains you own and then tell nginx to serve those suffixes so you can have an SSL setup on your local.

Errors

• If you do not specify what thing, heighliner will try to be helpful and tell you:

Error: Available things to show: ports cert-source http-suffix.
Try --help for help.

heighliner logs

Continuously monitors the application container's logs.

heighliner logs

heighliner shutdown

This command shuts down the shared infrastructure containers (nginx reverse proxy, DNS resolver, Selenium Chrome). It does not stop your app or database containers — use heighliner down for that.

Note: This command is destructive — it removes the shared Docker network and certs volume, which will affect all Heighliner environments on this machine.

heighliner deinit

This command removes the current environment from ~/.heighliner/config.yml. This also runs heighliner down to stop and delete your app containers and database volume. It does not delete the ~/.heighliner/databases/<ENV_NAME> directory.

heighliner db_save

This command saves the current state of the database of the application. By default it saves it in a file in the $HOME/.heighliner directory. But you can also specify a file for it to write to by going heighliner db_save ./mydb.mysql.

Notes

The default save file is actually git branch aware. What this means is that heighliner checks what git branch it is in right now and keys the file on that branch name.

This means that if you

1. checked out the main branch
2. ran heighliner db_save and then
3. checked out mybranch branch and then
4. ran heighliner db_save

it will save the state to a different file and not overwrite the db state saved when you were in the main branch. How it saves this file is actually an implementation detail and we don't make any guarantees about how it really works or if it will not change.

heighliner db_load

This command loads the saved state of the database of an application (if one exists), and destroys the previous state. By default it loads the file for the branch you are on. You can provide a parameter to load a file instead, like heighliner db_load ./mydb.mysql

heighliner db_reset

This command shuts down the database docker container, replaces the database with the default database image stored at ~/.heighliner/<ENV_NAME>/<current_github_branch_name>/default.tar.bz and brings the container up again.

This is the same as running heighliner db_load with no arguments.

heighliner db_reset_hard

Sometimes a db state can become somewhat inconsistent or the command defined by db_reset_command in the Steerfile does not handle all cases of db consistency. This command actually deletes the current state and re-initializes the database from scratch, and then runs the command defined by db_reset_command. This can be used to work around a messed up database state.

heighliner set <key> <value>

Sets the machine-wide settings stored in ~/.heighliner/config.yml. These are not per-environment: every Heighliner environment on this machine sees them.

This command does not need a Steerfile and does not need heighliner init to have been run, so you can run it from anywhere.

Parameters

Valid <key> parameters are:

• http-suffix - Sets the domain suffix for the reverse proxy to use (defaults to lvh.me)
• cert-url - Sets up a URL from which HTTPS certificates can be downloaded.
• cert-folder - Sets up a folder from which HTTPS certificates can be copied.
• cert-1password - Sets up a 1Password item from which HTTPS certificates are read.
• cert-1password-field - Overrides one 1Password field name.
• cert-1password-fields - Overrides all the 1Password field names at once, as JSON.
• help-https - Shows the HTTPS notes.

For example you can go

heighliner set http-suffix local.aweso.me and nginx will serve everything on that suffix, i.e. hats.local.aweso.me.

http-suffix HTTP suffix

heighliner set http-suffix local.aweso.me

The suffix every environment is served under. With the above, the hats environment is served at hats.local.aweso.me. Defaults to lvh.me. See suffixes.

The suffix also decides the names of the certificate files Heighliner looks for. For a suffix of local.aweso.me it always wants these three:

local.aweso.me.crt
local.aweso.me.key
local.aweso.me.chain.pem

cert-url Certificates from a URL

heighliner set cert-url https://internal-site.com/dev-certificates

The three files above are downloaded from that root, e.g. https://internal-site.com/dev-certificates/local.aweso.me.crt.

cert-folder Certificates from a folder

heighliner set cert-folder /home/me/my-certificate-folder

The three files above are copied out of that folder, e.g. /home/me/my-certificate-folder/local.aweso.me.crt.

cert-1password Certificates from a 1Password item

heighliner set cert-1password Vault/Dev-Certs

The value is a Vault/Item reference. Heighliner shells out to the 1Password CLI (op), so op must be installed and authenticated. In the Docker image, authentication is done with a service account token passed as OP_SERVICE_ACCOUNT_TOKEN; Heighliner fails with OP_SERVICE_ACCOUNT_TOKEN is not set if it is missing.

By default the field read for each file is the file name with the suffix stripped off — so key, crt and chain.pem:

op read "op://Vault/Dev-Certs/key"       → local.aweso.me.key
op read "op://Vault/Dev-Certs/crt"       → local.aweso.me.crt
op read "op://Vault/Dev-Certs/chain.pem" → local.aweso.me.chain.pem

Running heighliner set cert-1password with no value prints these notes instead of setting anything.

cert-1password-field Custom 1Password field name

If your 1Password item does not name its fields key, crt and chain.pem, override them one at a time:

heighliner set cert-1password-field key privkey
heighliner set cert-1password-field crt fullchain
heighliner set cert-1password-field chain.pem ca-bundle

which makes Heighliner read:

op read "op://Vault/Dev-Certs/privkey"   → local.aweso.me.key
op read "op://Vault/Dev-Certs/fullchain" → local.aweso.me.crt
op read "op://Vault/Dev-Certs/ca-bundle" → local.aweso.me.chain.pem

The first argument is the certificate file, so it is one of key, crt, chain.pem — note the third is chain.pem, not chain. Anything else is rejected rather than silently ignored:

Error: Unknown certificate field: 'chain'. Valid fields are: chain.pem, crt, key.

Fields you do not override keep their default name. Both arguments are plain words, so there is no quoting to get wrong.

cert-1password-fields All the field names at once

The plural form takes every field as a single JSON object, merging into whatever is already set:

heighliner set cert-1password-fields '{"key":"privkey","crt":"fullchain","chain.pem":"ca-bundle"}'

Prefer the singular cert-1password-field. The JSON here has to survive your shell intact, and on Heighliner 0.10.0 and older the Docker image's entrypoint re-parsed its arguments and stripped the quotes, producing JSON::ParserError: expected object key. Unparseable JSON now says so and points at the singular form.

help-https HTTPS notes

heighliner set help-https

Prints the notes on how the suffix and the certificate sources fit together. Sets nothing.

Notes

• cert-url, cert-folder and cert-1password are mutually exclusive. Setting one erases the other two.
• Certificates are only fetched when the shared nginx container is brought up, so after changing any of these run heighliner down, heighliner shutdown and then heighliner up again.

Errors

• If you do not provide a key and value it will fail like this:

Error: Unknown subcommand: ''.
Try --help for help.

heighliner attach

If you started heighliner using just heighliner up without the --attach option, you can use this command to "takeover" the process and bring it up to the foreground. This is useful if you intend to apply a breakpoint and interrupt the process, which means you want to be able to make it interactive so you can gracefully unbreakpoint it without having to kill it.

You can also Ctrl+C to interrupt out of this without closing the process, unlike if you used the --attach option, which if you used that would close the process.