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, 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, 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. In CI, skip login and set HOTCFG_API_KEY instead: see Config from 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:

Setting1. Flag2. Environment variable3. Saved by hotcfg loginDefault
API key--keyHOTCFG_API_KEY~/.config/hotcfg/credentialsnone
API URL--api-urlHOTCFG_API_URL~/.config/hotcfg/credentialshttps://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

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

Commands

CommandDoes
loginValidate a secret key and save it.
push <file.json>Upload a file as the next version of a bin.
get <bin_id>Print a bin's payload, optionally a pinned version or a jq query.
diff <bin_id>Show a colored diff between two versions.
promote <bin_id>Copy one environment's latest version to another.
rollback <bin_id>Make an earlier version current again.
history <bin_id>List versions, newest first.
unpublish <bin_id>Stop serving an environment, keeping its history.
bins list, bins createList or create your organization's bins.
env delete <bin_id>Delete an environment and its whole history.
usageShow the plan, usage and limits.
exportDownload 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