Skip to content

Chief v3.2.0

Latest

Choose a tag to compare

@randyoyarzabal randyoyarzabal released this 18 Nov 22:59
be084f0

Chief v3.2.0 Release Notes

What's New

Core vs user plugins

  • Core plugins: built-in, not editable via chief.plugin. User plugins: from CHIEF_CFG_PLUGINS_PATH, editable and listed by chief.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, openshift and vault are off on new installs, because they need tools or accounts most users don't have (AWS credentials; oc and a cluster; a HashiCorp Vault server). The template now lists them in CHIEF_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.aws removes it from that list; chief.plugin disable core.aws adds 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 with chief.plugin enable contrib.<name> (persisted in the new CHIEF_CFG_PLUGINS_ENABLED_CONTRIB); chief.plugin disable contrib.<name> turns it off. chief.plugin status, chief.status and chief.help plugins list contrib plugins separately.
  • First contrib plugin: cg, a wrapper for the Chainguard customer-success helper functions. Turn it on with chief.plugin enable contrib.cg.
  • Chief ships only the wrapper, not the helper functions. The plugin sources your local copy of .helper_functions.sh from CHIEF_CFG_CG_HELPER_FUNCTIONS. No location is assumed; set it once with chief.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 example cg.setup_customer_org, cg.cli, cg.tag_history), each with -?/--help. The original function names are unchanged and keep working.
  • cg.help lists the commands and shows which helper file is loaded; cg.reload re-sources it after you pull updates.

AWS plugin

  • Fixed: chief.aws_set-role and chief.aws_export-creds looked for their helper script at libs/plugins/python/aws_creds.py, which doesn't exist. They now use libs/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 (TERM set and not dumb). Output piped to a file, grep, or CI logs is plain text.
  • Set NO_COLOR=1 to disable colors everywhere; set CHIEF_FORCE_COLOR=1 to 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.sh scripts.

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 after git clone on 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 / ~/.bash scanning, which skipped *.sh files because of a find operator-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 / --vscode prefer Cursor when cursor is in PATH. Config: CHIEF_CFG_EDITOR_GUI_CMD to override.

chief.update

  • After update, Chief may prompt to run chief.config-update if 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_COLOR is 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.bump and the manual git/gh release 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 from release-notes/vX.Y.Z.md, then merges main back into dev and starts the next -dev version. --next is required, so every release says where development goes next. It asks before each push, merge and publish (--yes skips the questions, --dry-run shows 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_prepare also takes the required --next, so the release commit's Dev Branch badge (the one people see on main) 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 main contains dev's release commit, not just that main's VERSION matches.
  • --admin: if main's branch rules require an approving review (which you can't give your own pull request), chief.release_publish stops at the merge with a plain explanation; re-run with --admin to merge using your admin rights.
  • Changed your mind about the next version mid-cycle (say v3.2.1 should be v3.3.0)? chief.release_status prints 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_BRANCH to main/dev; now that only happens with chief.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 the dev branch and CHIEF_CFG_DEV_TOOLS=true (chief.config-set dev_tools true). On main or any release they never load, and .gitattributes keeps libs/dev out of GitHub release archives. chief.status shows 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 -dev version. Previously a next-dev bump turned all three badges into the dev version.
  • Fixed a false "Already up to date" skip of VERSION during release (the check matched v3.2.0 inside v3.2.0-dev).

Test suite and CI

  • New tests/bump-tests.sh: runs the version bump (release and next-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 stub gh. Covers the dev-tools gate (never loads on main), --next validation, 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. shellcheck is optional locally; the suite skips it with a warning when not installed.
  • Removed duplicate tests: plugin sourcing was tested in both source-tests.sh and plugin-tests.sh; chief.sh --lib-only loading was tested in both source-tests.sh and integration-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_PLUGINS toggles the plugins: line and CHIEF_CFG_BANNER_SHOW_TRACKING toggles the tracking: line. Both default to true and only apply when CHIEF_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 option errors 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 (default true; chief.config-set -y BASH_WARN=false to silence).
  • tools/install.sh prints 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 declare errors.

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 via CHIEF_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 with git rm --cached. Use -f/--force to skip the check. In non-interactive shells the commit is aborted when large files are detected.
  • chief.git_commit: the initial git pull is 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=gpg or --backend=ansible. If you do not specify one, GPG is used when gpg is in PATH, otherwise Ansible Vault.
    • Existing files are auto-detected as Ansible Vault or GPG. Do not pass --backend when editing or loading.
    • Non-interactive password: GPG uses CHIEF_SECRETS_PASSWORD_FILE; Ansible Vault continues to use ANSIBLE_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.
  • Clearer GPG errors: chief.secrets_file-edit and chief.secrets_file-load no longer report every GPG failure as a wrong password.
    • If the file is GPG-encrypted and gpg is not installed, Chief now stops before asking for a password and says so, with an install hint for your platform (for example brew install gnupg on macOS). Previously the missing binary was hidden and looked like "GPG decrypt failed (wrong password or file)".
    • When gpg runs 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 of chief.secrets_file-edit (previously a bare "GPG encrypt failed.").
    • Ansible Vault files get the same treatment. chief.secrets_file-load used to hide ansible-vault errors 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 set ANSIBLE_VAULT_PASSWORD_FILE), any other ansible-vault error (with its message), or a syntax error in the decrypted content. chief.secrets_file-edit adds a clear failure line after ansible-vault edit fails.
  • Vault plugin (vault_chief-plugin.sh): HashiCorp Vault only. Commands: chief.vault_read-secret, chief.vault_write-secret, chief.vault_list-secrets. Requires vault CLI, VAULT_ADDR, VAULT_TOKEN (or VAULT_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 (IdentityFile plus IdentitiesOnly yes). It updates an existing Host block or adds a new one above the first Host/Match, asks before writing, and backs up the file first (config.chief-backup.<timestamp>). The key can be a path or a name in CHIEF_CFG_SSH_KEYS_PATH. It refuses Host lines 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 to chief.ssh_status and chief.ssh_host-key and lists your key names. With fewer keys it stays silent.
  • chief.ssh_status gains a "Key pinning" section. With 3 or more keys loaded it lists hosts in ~/.ssh/config without IdentitiesOnly yes and 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 (default false) turns key auto-loading at start-up and on chief.reload on or off: chief.config-set ssh_load_keys true.
  • CHIEF_CFG_SSH_KEYS_PATH is 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-keys works 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 to chief.config-set in v3.1.1, so copying them failed with "command not found". They all use chief.config-set now.
  • Fixed: the editor examples set a nonexistent EDITOR option. They now use default_editor_path (for example chief.config-set default_editor_path "code --wait").
  • New website address: https://chief.randyo.dev (was chief.reonetlabs.us). The README, docs, installer, uninstaller and CHIEF_WEBSITE use the new address.
  • Fixed: the README and docs said Chief is MIT-licensed. Chief is GNU GPL v3.0, as in LICENSE and every source file header.

Deprecations and breaking changes

  • Deprecated: chief.vault_file-edit and chief.vault_file-load. Use chief.secrets_file-edit and chief.secrets_file-load. Old names still work but print a deprecation warning.

  • Deprecated: File names .chief_user-vault and .chief_shared-vault. Use .chief_user-secrets and .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_CORE can 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 (like chief.git_commit and chief.secrets_file-edit). There are no aliases, so the old names no longer work:

    • chief.ssh_load_keys → chief.ssh_load-keys
    • chief.plugins_update → chief.plugins-update (matches chief.plugins-root)
    • chief.etc_shared-term_create → chief.etc_shared-term-create
    • chief.etc_shared-term_connect → chief.etc_shared-term-connect
  • Removed (maintainers): __chief.bump is gone from the core library, with no alias. Use chief.release_status, chief.release_prepare and chief.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 on aws, openshift or vault that way, make sure they're not in CHIEF_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 own CHIEF_CFG_PLUGINS_DISABLED_CORE, so whatever was loading keeps loading. Fresh installs start with them off; turn one on with chief.plugin enable core.<name>.
  • SSH auto-load: if your config sets CHIEF_CFG_SSH_KEYS_PATH, your keys keep auto-loading. chief.config-update adds CHIEF_CFG_SSH_LOAD_KEYS=true for you in that case (and false otherwise). 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 from chief.vault_file-* and rename .chief_*vault to .chief_*secrets when convenient.
  • Renamed commands: update any scripts, aliases or plugins that call chief.ssh_load_keys, chief.plugins_update or chief.etc_shared-term_* (new names above). Config files created from older templates may still mention the old names in comments; chief.config-update refreshes them.
  • After chief.update, run chief.config-update if prompted. Use chief.plugin status to 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.