hart

The hart command line: global flags, settings, every command and the exit codes.

hart manages Harthelm workspaces, landscapes, domains and more through the API.

Settings come from flags, then HART_API, HART_TOKEN, HART_TEAM and HART_WORKSPACE, then the current context in ~/.config/hart/config.yaml.

hart [command]

hart is Harthelm's command line. It does what the console does, through the same REST API, so you can script it and use it in CI. Every workspace has it installed and set up; on your own machine, install it first.

Terminal

hart login --api https://console.example.com
hart whoami

hart login opens the console in your browser, where you approve the sign-in; --code shows a code to approve on any device instead (the default over SSH and in workspaces). It stores an API key in a context: the installation, the key and your default team and workspace. hart ctx switches between contexts.

Where settings come from

Each setting is taken from the first of:

the flag (--api, --team, --workspace, --context),
the environment variable (HART_API, HART_TOKEN, HART_TEAM, HART_WORKSPACE, HART_CONTEXT),
the current context in ~/.config/hart/config.yaml.

In CI, set HART_API, HART_TOKEN and HART_TEAM and skip hart login; see Use hart in CI. Teams are named by their id; workspaces by their id or their name.

Output

Lists print as tables. -o json and -o yaml print the API's objects for scripts:

Terminal

hart ws list -o json

When a command fails, hart prints the error and exits with an exit code that says what kind of error it was.

Commands

Signing in

Command	What it does
`hart ctx`	List, switch and remove contexts (installations and their default team and workspace)
`hart login`	Sign in and save an API key in a context
`hart logout`	Delete the context's API key and remove it from the contexts file
`hart whoami`	Show who the API key belongs to, and the context

Workspaces

Command	What it does
`hart exec`	Run a command in the workspace
`hart git`	Git in the workspace: pull, status
`hart keep-awake`	Keep the workspace from sleeping for a while
`hart ws`	List, create, open, wake and delete workspaces

Landscape and stages

Command	What it does
`hart logs`	Show the logs of stages and services
`hart prepare`	Run the prepare stage in the workspace
`hart run`	Start the run stage: every service starts its steps
`hart scale`	Set the replicas of services without a Sync
`hart stop`	Stop the run stage, one service, or a running prepare or test
`hart sync`	Sync the landscape with harthelm.yml: review the plan, then apply it
`hart test`	Run the test stage in the workspace

Env vars, secrets and managed services

Command	What it does
`hart env`	Workspace environment variables: list, set, unset
`hart ms`	Managed services (databases and more): list, create, rotate, delete
`hart secret`	Vault secrets of the workspace: keys, set, generate, delete

Custom domains

Command	What it does
`hart domain`	Custom domains of the team: add, verify, route

Tools

Command	What it does
`hart completion`	Generate the autocompletion script for the specified shell
`hart curl`	Make a request to a workspace's dev domain with your API key
`hart smoke`	Check an installation end to end with a scratch workspace
`hart validate`	Check a harthelm.yml without a workspace
`hart version`	Show hart's version and the server's

Administration

Command	What it does
`hart admin`	Cluster administration: doctor, users, audit, licence

Global flags

Every command takes these flags.

Flag	Description
`--api string`	the console's URL, e.g. https://console.example.org (`HART_API`)
`--config string`	the contexts file (default ~/.config/hart/config.yaml; `HART_CONFIG`)
`--context string`	the context to use (default: current-context; `HART_CONTEXT`)
`--contexts string`	the contexts file, as `--config`; also where a command's own `--config` hides it (ms create)
`-o, --output string`	output format: table, json or yaml (default "table")
`-t, --team int`	team id (`HART_TEAM`)
`-w, --workspace int`	workspace id (`HART_WORKSPACE`)

Exit codes

hart exits with one of these codes, so scripts can branch without parsing messages.

Code	Meaning
0	Success.
1	Anything else (network, server errors, a local failure).
2	Unknown command or flag, wrong arguments, a missing setting (no API, no team, no workspace).
3	No or an invalid key (401); run hart login.
4	The key's user may not do this (403).
5	The object does not exist or is not visible (404).
6	The API refused the change in the current state (409, 412, 428).

Sign inCopy Anchor Link

Where settings come fromCopy Anchor Link

OutputCopy Anchor Link

CommandsCopy Anchor Link

Signing inCopy Anchor Link

WorkspacesCopy Anchor Link

Landscape and stagesCopy Anchor Link

Env vars, secrets and managed servicesCopy Anchor Link

Custom domainsCopy Anchor Link

ToolsCopy Anchor Link

AdministrationCopy Anchor Link

Global flagsCopy Anchor Link

Exit codesCopy Anchor Link

On this page

Sign in