CLI Reference

hako new <branch> [flags]

Creates an isolated environment including worktree, config, ports, and environment variables.

Flags:

• --start: start services immediately after creation.
• --clobber: if the target directory exists as a non-worktree directory, it's backed up with a timestamp and replaced. It won't clobber tracked worktrees.
• --no-hooks: skip the post_create hook.

If the branch doesn't exist, hako creates it. Existing branches are checked out.

Example:

hako new feature-auth --start

hako rm <branch> [flags]

Removes the worktree, stops services, and cleans up the port registry.

Flags:

• --no-hooks: skip the pre_remove hook.

Example:

hako rm feature-auth

hako start [branch] [flags]

Starts services in bare mode or containers in docker mode.

Flags:

• --no-hooks: skip the post_start hook.

The branch is optional. It's inferred from the current directory if you're inside a worktree.

Example:

hako start feature-auth

hako stop [branch] [flags]

Stops services or containers. It also deregisters portless URLs.

Flags:

• --no-hooks: skip the post_stop hook.

Branch is optional and inferred from the current directory.

Example:

hako stop

hako ls [flags]

Lists all environments.

Flags:

• --json: output as a JSON array.
• --all: list all repositories. This requires the --json flag and uses search_paths from ~/.config/hako/config.yml.

Example:

hako ls --json
hako ls --all --json

hako status [branch] [flags]

Shows environment health.

Flags:

• --json: JSON output with health state, mode, and services.
• --all: show status for all environments.

Branch is optional and inferred from the current directory. Bare mode shows health (healthy, degraded, or stopped) and service states. Docker mode shows container status.

Example:

hako status --json feature-auth

hako ports [branch] [flags]

Shows port mappings.

Flags:

• --json: JSON output. Schema includes repo, branch, branch_slug, path, portless_url, portless_urls, vars, and services.

Branch is optional and inferred from the current directory. Human-readable output shows .env.hako variables, container ports for docker, and portless URLs.

Example:

hako ports --json

hako logs [branch] [service] [flags]

Shows service or container logs.

Flags:

• --follow / -f: follow log output. This uses tail -f in bare mode and docker compose logs -f in docker mode.
• --tail N: show the last N lines.

Bare mode reads from .hako/logs/{service}.log. Docker mode uses docker compose logs.

Example:

hako logs feature-auth dev --follow --tail 50

hako shell [branch] [service]

Opens a shell in the environment.

Bare mode opens a new shell using $SHELL in the worktree directory. The service argument is ignored. Docker mode runs docker compose exec {service} sh. It defaults to the first service if none is specified.

Example:

hako shell feature-auth

hako repair [flags]

Fixes orphaned state.

Flags:

• --json: JSON output. Schema includes pruned_git_worktrees, orphaned_containers, and orphaned_dirs.
• --prune-dirs: also remove orphaned worktree directories.

This command prunes the git worktree list, cleans stale port registry entries, and removes stale PID files.

Example:

hako repair --json --prune-dirs

hako init [shell] [flags]

Prints the shell integration snippet.

Arguments include bash, zsh, or fish. Hako auto-detects the shell from $SHELL if omitted.

Flags:

• --install: auto-append to the shell rc file. This operation is idempotent.
• --shell <type>: explicit shell type.

Example:

eval "$(hako init)"
hako init --install
hako init fish

hako path <branch>

Prints the absolute worktree path. It fails if the environment doesn't exist.

Example:

hako path feature-auth

hako cd <branch> [flags]

Changes the directory to the worktree. This requires shell integration.

Flags:

• --env: also load .env.hako into the current shell.

Example:

hako cd feature-auth --env

hako env list [branch] [flags]

Lists .env.hako variables.

Flags:

• --redact: mask variable values.
• --json: JSON output.

Branch is optional and inferred from the current directory.

hako env get <KEY> [branch] [flags]

Gets a single variable value.

Flags:

• --redact: mask the value.

Example:

hako env get PORT feature-auth

hako env export [branch] [flags]

Exports .env.hako in various formats.

Flags:

• --format <fmt> (required): one of dotenv, json, bash, or fish.
• --redact: mask values.

Example:

hako env export --format json

hako env apply [branch]

Loads .env.hako variables into the current shell session. This requires shell integration.

Branch is optional and inferred from the current directory.

hako hook list [branch]

Lists available hooks from hako.yml.

hako hook run <name> [branch]

Runs a hook by name. This works for both lifecycle and custom hooks.

Example:

hako hook run my_custom_hook feature-auth

hako update

Updates the hako CLI by pulling the latest from the git repo at HAKO_HOME/repo. This only works with install.sh installations and not the macOS app.

hako --version / -v

Prints the version number.

hako --help / -h

Prints the full help text.