github.com/howielauvehansen94/chefctl
1.0.0 / published Oct 24, 2026 / repository
chefctl
A small Crystal CLI for the Chef Infra Server REST API.
Installation
Prebuilt binaries for Linux and Windows are attached to each GitHub release.
From source:
shards install
crystal build src/chefctl.cr -o bin/chefctl
On Windows this produces bin\chefctl.exe. Note that Crystal's Windows
support is currently a preview.
Usage
export CHEF_SERVER_URL=https://chef.example.com/organizations/myorg
export CHEF_USER=myuser
export CHEF_KEY="$HOME/.chef/myuser.pem"
chefctl get nodes
chefctl get node web01.example.com
chefctl create node web01.example.com
chefctl get "search/node?q=platform:ubuntu"
Run chefctl --help for all commands and flags. The get command also hits
any org-relative endpoint (a PATH containing / or ?), so search, data bags
(get data), etc. work without dedicated commands.
Objects are created and updated from JSON passed with --file FILE (-
reads stdin) or piped on stdin; create node generates a minimal empty node
when no body is given:
chefctl get node web01.example.com > web01.json
$EDITOR web01.json
chefctl update node web01.example.com --file web01.json
chefctl delete node web01.example.com
Pass -F json or -F yaml for machine-readable output: name lists render as
collections and everything else renders as documents, e.g.
chefctl -F yaml get node web01.example.com
--key and CHEF_KEY accept ~, which chefctl expands itself, so
--key ~/.chef/myuser.pem works the same in PowerShell and cmd as in POSIX
shells.
Development
crystal spec
Integration tests boot cinc-server-ng
(an in-memory Chef Infra Server implementation) in a container and run the CLI
against it. Requires docker or podman (docker is the default) plus just:
just integration
The suite tears the server down afterwards; eval "$(just create-env)" starts
the server (if needed) and exports CHEF_SERVER_URL, CHEF_USER and
CHEF_KEY into your shell for manual chefctl runs — just server-down
cleans up. just server-up, just seed and just server-down are available
for lower-level control, and CONTAINER_RUNTIME=podman just integration
forces podman.