Repository navigation
Chief v3.2.0 Release Notes
What's New
Core vs user plugins
- Core plugins: built-in, not editable via
chief.plugin. User plugins: fromCHIEF_CFG_PLUGINS_PATH, editable and listed bychief.plugin -?. - Banner and help show Core vs User plugins separately.
Enable/disable plugins
chief.plugin enable|disable [core.|contrib.]<name>;chief.plugin status. Config:CHIEF_CFG_PLUGINS_DISABLED_CORE,CHIEF_CFG_PLUGINS_DISABLED_USER(comma- or space-separated).
Core plugins that are off by default
aws,openshiftandvaultare off on new installs, because they need tools or accounts most users don't have (AWS credentials;ocand a cluster; a HashiCorp Vault server). The template now lists them inCHIEF_CFG_PLUGINS_DISABLED_CORE.- One rule for every core plugin: it loads unless it's in
CHIEF_CFG_PLUGINS_DISABLED_CORE.chief.plugin enable core.awsremoves it from that list;chief.plugin disable core.awsadds it back. There is no separate "enabled" list for core plugins.
Contrib plugins and the Chainguard cg plugin
- New contrib plugin group for optional plugins shipped with Chief for specific teams or workflows (
libs/contrib/plugins/). Chief scans it on every load, but every contrib plugin is off by default. Turn one on withchief.plugin enable contrib.<name>(persisted in the newCHIEF_CFG_PLUGINS_ENABLED_CONTRIB);chief.plugin disable contrib.<name>turns it off.chief.plugin status,chief.statusandchief.help pluginslist contrib plugins separately. - First contrib plugin:
cg, a wrapper for the Chainguard customer-success helper functions. Turn it on withchief.plugin enable contrib.cg. - Chief ships only the wrapper, not the helper functions. The plugin sources your local copy of
.helper_functions.shfromCHIEF_CFG_CG_HELPER_FUNCTIONS. No location is assumed; set it once withchief.config-set cg_helper_functions "/path/to/customer-success/scripts/.helper_functions.sh". Until it's set (or if the file is missing), the plugin prints that command. - Every helper function is available as
cg.<name>(for examplecg.setup_customer_org,cg.cli,cg.tag_history), each with-?/--help. The original function names are unchanged and keep working. cg.helplists the commands and shows which helper file is loaded;cg.reloadre-sources it after you pull updates.
AWS plugin
- Fixed:
chief.aws_set-roleandchief.aws_export-credslooked for their helper script atlibs/plugins/python/aws_creds.py, which doesn't exist. They now uselibs/core/plugins/python/aws_creds.py.
chief.reload
- Plugin names color-coded (green loaded, yellow skipped).
chief.status
- New command: prints the Chief banner followed by a stats summary (function count, core and user plugins, enabled/disabled state). Handy for a quick health check without reloading.
Terminal color handling
- ANSI colors are now emitted only when stdout is a capable TTY (
TERMset and notdumb). Output piped to a file,grep, or CI logs is plain text. - Set
NO_COLOR=1to disable colors everywhere; setCHIEF_FORCE_COLOR=1to force colors even when stdout is not a TTY. - The same policy applies to the core library, the OpenShift plugin, and the
install.sh/uninstall.shscripts.
chief.plugin symlink
chief.plugin <name> <existing_file_path>creates a symlink so an existing script loads as a plugin.- When the existing file lives inside the plugins directory (
CHIEF_CFG_PLUGINS_PATH), Chief uses a relative symlink target so the link stays valid aftergit cloneon another machine (remote plugins repo / shared dotfiles). A file outside the plugins directory gets an absolute target, and Chief prints a note that the link is not portable. - Fixed broken links when the plugins directory is reached through a symlink (for example
~/chief_plugins→~/code/.../common). Chief used to compute the relative target from the symlinked path, but the OS resolves it from the real directory, so the link pointed at a file that did not exist. Paths are now resolved to their real locations first. - Chief now checks that a new link actually resolves. If a relative target does not, it falls back to an absolute one; if that fails too, it removes the link and reports an error instead of claiming success.
chief.whereis
- Now searches plugins that are symlinks (such as ones created with
chief.plugin <name> <file>) and plugin directories reached through a symlink. Previously they were skipped, so a loaded function showed "No definitions found". - Fixed
~/.bashrc.d/~/.bashscanning, which skipped*.shfiles because of afindoperator-precedence bug. - Commented-out lines (for example
# my_func() does X) no longer count as definitions or trigger a false "Multiple definitions" warning.
Cursor / GUI editor
--code/--vscodeprefer Cursor whencursoris in PATH. Config:CHIEF_CFG_EDITOR_GUI_CMDto override.
chief.update
- After update, Chief may prompt to run
chief.config-updateif the config template changed.
Live progress for multi-step commands
- New shared progress output for Chief commands that run several steps:
✓done, a spinner for the step that's running,↷skipped (already done),✗failed (with the reason and how to resume),○"would" in a dry run,·pending in status views. It ends with a summary of exactly what changed. - Append-only: each finished step is printed once and never redrawn; in a terminal only the running step's line updates in place. So it can't duplicate lines, whatever the terminal's size or locale, or whatever else writes to it. Yes/no questions (with a preview of the changes) appear under the running step and are cleared once answered.
- When output goes to a pipe, a file or CI (or
NO_COLORis set) there is no spinner, just one line per finished step. - Step commands run detached from the terminal (their output goes to a log shown on failure); git and other shell-function steps keep it so password and passphrase prompts still work.
- The release tools below are the first commands to use it; other multi-step commands will move to it over time.
Release tooling (maintainers only)
- New dev-only release commands replace
__chief.bumpand the manualgit/ghrelease steps:chief.release_status: where the release stands, what's done and what to run next. Changes nothing.chief.release_prepare: optional. Stages the release on dev: checks, test suite, version bump (VERSION, release notes, badges), then commits "Release vX.Y.Z" and pushes dev.chief.release_publish --next vX.Y.Z: the whole release in one run. Prepares dev if needed, opens the dev → main pull request, waits for CI, merges, tags, creates the GitHub release fromrelease-notes/vX.Y.Z.md, then merges main back into dev and starts the next-devversion.--nextis required, so every release says where development goes next. It asks before each push, merge and publish (--yesskips the questions,--dry-runshows every step and changes nothing).
- Resumable: where a release stands is read from git and GitHub, so if a run stops (CI failure, network, a "no"), running the same command again skips what's done and continues.
chief.release_preparealso takes the required--next, so the release commit's Dev Branch badge (the one people see onmain) shows the real next dev version instead of a guess.- The version bump no longer rewrites the README's install section (which lists both the stable and the dev command on every branch). Rewriting it broke the commands on dev: Perl expanded
$(into a list of group IDs and the section was duplicated. Only the "(Development Version)" title and the dev-branch warning change between releases now. - A rewound release is handled: "already merged" now means the release is tagged or
maincontains dev's release commit, not just thatmain's VERSION matches. --admin: ifmain's branch rules require an approving review (which you can't give your own pull request),chief.release_publishstops at the merge with a plain explanation; re-run with--adminto merge using your admin rights.- Changed your mind about the next version mid-cycle (say
v3.2.1should bev3.3.0)?chief.release_statusprints the exact commands to retarget dev, filled in with your versions. No extra command to learn; the test suite runs those printed commands to keep them correct. - Your own config is no longer changed behind your back. The old bump switched
CHIEF_CFG_UPDATE_BRANCHto main/dev; now that only happens withchief.release_publish --track main|dev. - Not shipped to users. The commands live in
libs/dev/plugins/and load only when Chief's own checkout is on thedevbranch andCHIEF_CFG_DEV_TOOLS=true(chief.config-set dev_tools true). Onmainor any release they never load, and.gitattributeskeepslibs/devout of GitHub release archives.chief.statusshows whether dev tools are active.
Version bump (README)
- README update and warning box work with more title/section variants; bump more tolerant of format.
- Badges are now rewritten by meaning instead of by global find-and-replace: Download Release and Stable always show the latest released version, and Dev Branch always shows the in-progress
-devversion. Previously anext-devbump turned all three badges into the dev version. - Fixed a false "Already up to date" skip of
VERSIONduringrelease(the check matchedv3.2.0insidev3.2.0-dev).
Test suite and CI
- New
tests/bump-tests.sh: runs the version bump (releaseandnext-dev) on a scratch copy and asserts VERSION, badge and release-notes outcomes, and that your config is left alone. Runs on Linux and macOS in CI (BSD vs GNU sed). - New
tests/release-tests.sh: runs the release commands end to end against a scratch copy, with a local bare repository standing in for GitHub and a stubgh. Covers the dev-tools gate (never loads on main),--nextvalidation, dry run and status changing nothing, a full publish, resuming after a failed merge, and re-running after success. - New
tests/config-defaults-tests.sh: plugin defaults and SSH auto-load, including configs from before these changes. - ShellCheck is now a real gate at error severity (previously informational only and hidden). Warnings still only show with
-v.shellcheckis optional locally; the suite skips it with a warning when not installed. - Removed duplicate tests: plugin sourcing was tested in both
source-tests.shandplugin-tests.sh;chief.sh --lib-onlyloading was tested in bothsource-tests.shandintegration-tests.sh. Removed two integration checks that could never fail. - Workflow: the apt cache action is pinned to a commit SHA instead of
@latest; macOS uses the preinstalled shellcheck instead of a Homebrew install on every run.
Banner customization
- Two new config options let you hide individual banner header items without turning the whole banner off (the ASCII logo stays put either way):
CHIEF_CFG_BANNER_SHOW_PLUGINStoggles theplugins:line andCHIEF_CFG_BANNER_SHOW_TRACKINGtoggles thetracking:line. Both default totrueand only apply whenCHIEF_CFG_BANNER=true.
Bash version check (macOS)
- Chief needs Bash 4.0+, but macOS ships 3.2. On the system bash the only symptom used to be cryptic
declare: -A: invalid option/declare: -g: invalid optionerrors at start-up from plugins. - Chief now warns at start-up (stderr, before plugins load) when it runs under Bash older than 4.0. The message names the running Bash, and on macOS gives the fix:
brew install bash, then make the terminal use it (set the terminal's command to/opt/homebrew/bin/bash -l, or add a small re-exec snippet to the top of~/.bash_profile). If a Homebrew Bash is already installed it says so and skips the install step. It never blocks loading. - New config option
CHIEF_CFG_BASH_WARN(defaulttrue;chief.config-set -y BASH_WARN=falseto silence). tools/install.shprints the same guidance when run under Bash older than 4.0 (informational; the install continues).- Docs: new "macOS: install a newer Bash" section in the getting-started guide; the troubleshooting entries now mention the
declareerrors.
Git plugin
chief.git_init <repo_url>: initial commit of current directory to a repo (init, remote, add, commit, branch, pull, push). Refuses if already a repo.chief.git_commit: warns before committing staged files that exceed a size threshold (default 50 MB, configurable viaCHIEF_CFG_GIT_COMMIT_WARN_MB). Interactive prompt offers three options: commit anyway, unstage and add the file(s) to.gitignore, or abort. Previously tracked files are also removed from the index withgit rm --cached. Use-f/--forceto skip the check. In non-interactive shells the commit is aborted when large files are detected.chief.git_commit: the initialgit pullis now best-effort. If the pull fails (for example merge conflicts or unmerged files), a warning is printed and the commit and push still run instead of aborting.
Secrets plugin and Vault plugin
- Secrets plugin (
secrets_chief-plugin.sh): Encrypted bash secrets file (env vars, functions). Backends: Ansible Vault or GPG (symmetric AES256). Commands:chief.secrets_file-edit,chief.secrets_file-load. Backend chosen when creating; auto-detected when loading/editing. Default files:.chief_user-secrets,.chief_shared-secrets. - New GPG backend: Encrypted secrets files were previously Ansible Vault only. You can now use GPG symmetric encryption (AES256, ASCII-armored), so no Ansible install is required.
- Choose the backend when creating a file with
--backend=gpgor--backend=ansible. If you do not specify one, GPG is used whengpgis in PATH, otherwise Ansible Vault. - Existing files are auto-detected as Ansible Vault or GPG. Do not pass
--backendwhen editing or loading. - Non-interactive password: GPG uses
CHIEF_SECRETS_PASSWORD_FILE; Ansible Vault continues to useANSIBLE_VAULT_PASSWORD_FILE. Otherwise you are prompted. - Existing Ansible Vault files keep working unchanged. To switch a file to GPG, decrypt it and recreate it with
--backend=gpg.
- Choose the backend when creating a file with
- Clearer GPG errors:
chief.secrets_file-editandchief.secrets_file-loadno longer report every GPG failure as a wrong password.- If the file is GPG-encrypted and
gpgis not installed, Chief now stops before asking for a password and says so, with an install hint for your platform (for examplebrew install gnupgon macOS). Previously the missing binary was hidden and looked like "GPG decrypt failed (wrong password or file)". - When
gpgruns but fails, Chief shows gpg's own message. It only says "wrong password" when gpg reports a bad passphrase or decryption failure. The same applies to the re-encrypt step at the end ofchief.secrets_file-edit(previously a bare "GPG encrypt failed."). - Ansible Vault files get the same treatment.
chief.secrets_file-loadused to hideansible-vaulterrors and report "password or syntax" for everything. It now decrypts first and reports separately a wrong vault password, a missing vault password (with a hint to setANSIBLE_VAULT_PASSWORD_FILE), any otheransible-vaulterror (with its message), or a syntax error in the decrypted content.chief.secrets_file-editadds a clear failure line afteransible-vault editfails.
- If the file is GPG-encrypted and
- Vault plugin (
vault_chief-plugin.sh): HashiCorp Vault only. Commands:chief.vault_read-secret,chief.vault_write-secret,chief.vault_list-secrets. RequiresvaultCLI,VAULT_ADDR,VAULT_TOKEN(orVAULT_TOKEN_FILE).
SSH: many keys in ssh-agent
ssh offers every key in the agent, one at a time, and servers stop after a few rejected keys (MaxAuthTries), so with many keys loaded the right one may never be tried ("Too many authentication failures").
- New
chief.ssh_host-key <host> <key> [--dry-run] [--yes]: pins one key to a host in~/.ssh/config(IdentityFileplusIdentitiesOnly yes). It updates an existingHostblock or adds a new one above the firstHost/Match, asks before writing, and backs up the file first (config.chief-backup.<timestamp>). The key can be a path or a name inCHIEF_CFG_SSH_KEYS_PATH. It refusesHostlines that list several hosts. - Hint only when it matters: after loading keys, Chief prints a short note only when 3 or more keys are in the agent, once per machine at start-up, and every time you run
chief.ssh_load-keys. The note points tochief.ssh_statusandchief.ssh_host-keyand lists your key names. With fewer keys it stays silent. chief.ssh_statusgains a "Key pinning" section. With 3 or more keys loaded it lists hosts in~/.ssh/configwithoutIdentitiesOnly yesand shows the fix. With fewer keys it reports there is nothing to pin.
SSH: auto-load switch and default keys directory
- New
CHIEF_CFG_SSH_LOAD_KEYS(defaultfalse) turns key auto-loading at start-up and onchief.reloadon or off:chief.config-set ssh_load_keys true. CHIEF_CFG_SSH_KEYS_PATHis now only an optional override. Without it Chief uses~/.ssh, so you no longer have to set the default path just to turn auto-loading on.chief.ssh_load-keysworks with no configuration (it used to stop with "CHIEF_CFG_SSH_KEYS_PATH is not set").
Documentation and message fixes
- Fixed: the README, docs, installer, and Chief's own start-up hints and messages (Bash version warning, branch-tracking line, tips) told you to run
chief.config_set. That command was renamed tochief.config-setin v3.1.1, so copying them failed with "command not found". They all usechief.config-setnow. - Fixed: the editor examples set a nonexistent
EDITORoption. They now usedefault_editor_path(for examplechief.config-set default_editor_path "code --wait"). - New website address: https://chief.randyo.dev (was
chief.reonetlabs.us). The README, docs, installer, uninstaller andCHIEF_WEBSITEuse the new address. - Fixed: the README and docs said Chief is MIT-licensed. Chief is GNU GPL v3.0, as in
LICENSEand every source file header.
Deprecations and breaking changes
-
Deprecated:
chief.vault_file-editandchief.vault_file-load. Usechief.secrets_file-editandchief.secrets_file-load. Old names still work but print a deprecation warning. -
Deprecated: File names
.chief_user-vaultand.chief_shared-vault. Use.chief_user-secretsand.chief_shared-secrets. Legacy names still work; renaming shows a deprecation warning. -
Breaking: The former "vault" plugin (encrypted file) is now the secrets plugin. The vault plugin is now HashiCorp Vault only (read/write/list secrets via Vault CLI). Disable separately:
CHIEF_CFG_PLUGINS_DISABLED_COREcan include"secrets"and/or"vault". -
Breaking: Four commands were renamed to match Chief's naming convention:
chief.<area>_<action>, with hyphens between words in the action (likechief.git_commitandchief.secrets_file-edit). There are no aliases, so the old names no longer work:chief.ssh_load_keys→chief.ssh_load-keyschief.plugins_update→chief.plugins-update(matcheschief.plugins-root)chief.etc_shared-term_create→chief.etc_shared-term-createchief.etc_shared-term_connect→chief.etc_shared-term-connect
-
Removed (maintainers):
__chief.bumpis gone from the core library, with no alias. Usechief.release_status,chief.release_prepareandchief.release_publish(see Release tooling). -
Removed (dev branch only):
CHIEF_CFG_PLUGINS_ENABLED_CORE, which existed only on the v3.2.0 dev branch. If you tested dev and turned onaws,openshiftorvaultthat way, make sure they're not inCHIEF_CFG_PLUGINS_DISABLED_CORE(chief.plugin status). You can delete the old line from your config.
Upgrade notes
aws,openshift,vault: nothing changes for existing setups; your config already has its ownCHIEF_CFG_PLUGINS_DISABLED_CORE, so whatever was loading keeps loading. Fresh installs start with them off; turn one on withchief.plugin enable core.<name>.- SSH auto-load: if your config sets
CHIEF_CFG_SSH_KEYS_PATH, your keys keep auto-loading.chief.config-updateaddsCHIEF_CFG_SSH_LOAD_KEYS=truefor you in that case (andfalseotherwise). If your keys are in~/.ssh, you can then drop the path line. - Use
chief.secrets_file-*for encrypted bash secrets;chief.vault_*for HashiCorp Vault. Migrate fromchief.vault_file-*and rename.chief_*vaultto.chief_*secretswhen convenient. - Renamed commands: update any scripts, aliases or plugins that call
chief.ssh_load_keys,chief.plugins_updateorchief.etc_shared-term_*(new names above). Config files created from older templates may still mention the old names in comments;chief.config-updaterefreshes them. - After
chief.update, runchief.config-updateif prompted. Usechief.plugin statusto see enabled/disabled plugins.
Credits
Written and maintained by Randy E. Oyarzabal. Parts of this release were developed with AI coding assistants (Cursor and Claude by Anthropic), used for refactoring, the version-bump fixes, the chief.plugin symlink fix, the default-off core plugins, the cg contrib plugin, the AWS path fix, the SSH key-limit and auto-load changes, the live progress list, the dev-only release tooling, the website move, test suite work, and documentation. All changes were reviewed and tested by the maintainer. See the README's Acknowledgments section for the project's AI-assistance policy.
Full details: See release-notes directory for complete changelog and version history.