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
brew install --cask hotcfg/tap/hotcfgOn 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:
$ hotcfg version
hotcfg 0.1.3To 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:
$ 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/credentialsThe 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
hotcfg bins create mobile-flags --schema schema.json --public
hotcfg push flags.json --bin mobile-flags --env staging
hotcfg get acme/mobile-flags --env stagingWhere 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,
getprints the JSON exactly as the API sent it, compact, sohotcfg get mobile-flags | jq .works. - Results go to standard output; errors and hints to standard error.
- Set
NO_COLORto any value to turn colors off. history,bins listandusageprint 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 | Validate 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 create | List or create your organization's bins. |
env delete <bin_id> | Delete an environment and its whole history. |
usage | Show the plan, usage and limits. |
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