CLI

# CLI

Install the hotcfg CLI, log in, and learn how it finds your key, names bins and reports errors.

`hotcfg` is the command-line tool for hotcfg: push a JSON file as a new version, read it back, diff versions, promote between environments and roll back. It's open source (Apache-2.0) at [github.com/hotcfg/cli](https://github.com/hotcfg/cli), a single static binary with no dependencies, for Linux, macOS and Windows on amd64 and arm64.

## Install

Homebrew (macOS and Linux)

```
brew install --cask hotcfg/tap/hotcfg
```

On Windows, download `hotcfg_<version>_windows_amd64.zip` (or `arm64`) from the [releases page](https://github.com/hotcfg/cli/releases), check it against `checksums.txt`, and put `hotcfg.exe` on your `PATH`.

Check it works:

terminal

```
$ hotcfg version
hotcfg 0.1.3
```

To update, run the same install again (`brew upgrade --cask hotcfg` with Homebrew). To remove it, delete the binary and `~/.config/hotcfg`.

## Log in

Create a **secret** key in the dashboard under **Settings → API keys**, then:

terminal

```
$ hotcfg login
Secret API key (sk_live_...):
✓ Logged in to Acme (acme)
  key      sk_live_4f9a…  Laptop
  api      https://api.hotcfg.run
  saved    /home/alex/.config/hotcfg/credentials
```

The key is checked with the API before it's saved. See [login](https://hotcfg.run/docs/cli/login). In CI, skip `login` and set `HOTCFG_API_KEY` instead: see [Config from CI](https://hotcfg.run/docs/guides/ci).

## Your first push

terminal

```
hotcfg bins create mobile-flags --schema schema.json --public
hotcfg push flags.json --bin mobile-flags --env staging
hotcfg get acme/mobile-flags --env staging
```

## Where settings come from

Each setting comes from the first place that has it:

| Setting | 1. Flag | 2. Environment variable | 3. Saved by `hotcfg login` | Default |
| --- | --- | --- | --- | --- |
| API key | `--key` | `HOTCFG_API_KEY` | `~/.config/hotcfg/credentials` | none |
| API URL | `--api-url` | `HOTCFG_API_URL` | `~/.config/hotcfg/credentials` | `https://api.hotcfg.run` |

The credentials file is at `$XDG_CONFIG_HOME/hotcfg/credentials` when `XDG_CONFIG_HOME` is set, and is written with mode `0600`. Every command takes `--key` and `--api-url`.

Commands that change something need a secret key (`sk_live_…`). Changing production (pushing to it, promoting to it, rolling it back, unpublishing or deleting it) also needs a key that includes production, made by someone who is still an administrator or the owner: otherwise the command fails with a hint, and development and staging keep working. `get` and `diff` also work with a publishable key (`pk_live_…`), or with no key at all for a public bin.

## Naming a bin

A `<bin_id>` is either a bin's id, such as `mobile-flags`, looked up in your key's organization, or `org-slug/id`, such as `acme/mobile-flags`. Without a key there's no organization to look in, so name it in full: `hotcfg get acme/mobile-flags`.

## Output

- On a terminal, JSON is indented and results are colored. When piped, `get` prints the JSON exactly as the API sent it, compact, so `hotcfg get mobile-flags | jq .` works.
- Results go to standard output; errors and hints to standard error.
- Set `NO_COLOR` to any value to turn colors off.
- `history`, `bins list` and `usage` print a table, or the API's JSON with `--json`.

## Exit codes

| Code | Means |
| --- | --- |
| `0` | Success. |
| `1` | The command ran and failed: an API error, a file that isn't JSON, a schema that refused the push. |
| `2` | The command line was wrong: an unknown command, a missing argument or flag. |

## Commands

| Command | Does |
| --- | --- |
| [`login`](https://hotcfg.run/docs/cli/login) | Validate a secret key and save it. |
| [`push <file.json>`](https://hotcfg.run/docs/cli/push) | Upload a file as the next version of a bin. |
| [`get <bin_id>`](https://hotcfg.run/docs/cli/get) | Print a bin's payload, optionally a pinned version or a jq query. |
| [`diff <bin_id>`](https://hotcfg.run/docs/cli/diff) | Show a colored diff between two versions. |
| [`promote <bin_id>`](https://hotcfg.run/docs/cli/promote) | Copy one environment's latest version to another. |
| [`rollback <bin_id>`](https://hotcfg.run/docs/cli/rollback) | Make an earlier version current again. |
| [`history <bin_id>`](https://hotcfg.run/docs/cli/history) | List versions, newest first. |
| [`unpublish <bin_id>`](https://hotcfg.run/docs/cli/unpublish) | Stop serving an environment, keeping its history. |
| [`bins list`, `bins create`](https://hotcfg.run/docs/cli/bins) | List or create your organization's bins. |
| [`env delete <bin_id>`](https://hotcfg.run/docs/cli/env-delete) | Delete an environment and its whole history. |
| [`usage`](https://hotcfg.run/docs/cli/usage) | Show the plan, usage and limits. |
| [`export`](https://hotcfg.run/docs/cli/export) | Download every bin and its history as one JSON file. |

`hotcfg help` lists them, and `hotcfg <command> --help` shows a command's flags. Flags can go before or after the arguments.

Last updated 10 November 2026
