chef-client -z: From Zero To Chef In 8.5 Seconds

In Chef 11.8, we’re excited to introduce local mode with `chef-client -z`. Designed to get people up and running with Chef as quickly as possible, local mode harnesses the power of chef-zero to let you run recipes and work with the full power of Chef locally without the need to set up a server, register and grab keys, configure the client, or switch to root. It is designed to handle many scenarios, including:

1. Beginners: Local mode lets a new user run their first recipe as fast as possible: install Chef, write recipe, `chef-client -z -o cookbookname`, done!
2. Rapid Recipe Development: with local mode, you can `chef-client`, change your recipe/data bags/roles/whatever, and `chef-client` again with no steps in between.
3. Solo Use: Makes it easy to configure a local workstation of server with Chef, while allowing an easy transition to a real Chef server to handle multiple remote servers.

Getting started with local mode

Here’s the most basic scenario for getting started with local mode:

1. Install Chef
2. Create `cookbooks/helloworld/recipes/default.rb`:

file "#{ENV[‘HOME’]}/x.txt" do
content ‘HELLO WORLD’

3. Run chef-client:

$ chef-client -z -o helloworld
[2013-10-30T16:39:59-07:00] WARN: No config file found or specified on command line, using command line options.
Starting Chef Client, version 11.8.0.rc.1
[2013-10-30T16:40:01-07:00] WARN: Run List override has been provided.
[2013-10-30T16:40:01-07:00] WARN: Original Run List: 
] [2013-10-30T16:40:01-07:00] WARN: Overridden Run List:
] resolving cookbooks for run list: ["helloworld"] Synchronizing Cookbooks: - helloworld Compiling Cookbooks... Converging 1 resources Recipe: helloworld::default * file[/Users/jkeiser/x.txt] action create - update content in file /Users/jkeiser/x.txt from 9b96a1 to 787ec7 --- /Users/jkeiser/x.txt 2013-10-15 10:52:19.000000000 -0700 +++ /var/folders/87/lgq7l8yj6yg5j6323hc0jn7h0000gn/T/.x.txt20131030-5422-6h1dud 2013-10-30 16:40:01.000000000 -0700 @@ -1,2 +1,2 @@ -hi there +HELLO WORLD Chef Client finished, 1 resources updated

No muss, no fuss, you have just run your first recipe!

Data bags, roles, and search, oh my!

`chef-client -z` supports the full range of Chef concepts including data bags, roles, environments and even search. To add other types of thing, just make files for them:


A gentle ramp to production

When you’ve developed your recipes for a while and outgrow local mode, you’ll naturally want to move to Hosted Chef or to a Chef Server of your own. This is where `chef-client -z` gives you a clear path. When it’s time to move, just make a `.chef/knife.rb` in the current directory and use `knife upload`:

knife upload /

All your cookbooks, data bags, roles, nodes, and everything are on the server. To the cloud!

knife local mode

knife works in local mode too! For example, if you want to set your node’s run list, you can use `knife node list -z` to find your node’s name and then run:

knife node run_list add -z  recipe[helloworld]

After this,

chef-client -z

with no other parameters will always run “helloworld”.


Local mode has a special feature embedded: when your recipes save data back to the Chef server, the data goes back into your repository! So if your recipe creates or updates a data bag, or changes a node attribute, or tags a node, the data will go straight back into your local filesystem and the next time `chef-client -z` or `knife -z` run, they will be aware of it.

Try it out! One thing this means is that after your first chef-client run, you will see a `nodes/MYHOST.json` file containing your node data.

A note about chef-solo

chef-solo still exists, and this obviously has some overlap there. In *most* cases where you are using chef-solo, you will be able to use chef-client -z in its place, since chef-client has all of chef-solo’s features and more. Only if your recipes specifically test for :solo mode will things be different, since chef-client does not set this variable.

As always, issues and feature requests can be filed at []( Check out the [mailing lists]( or [IRC]( if you want to discuss or contribute. Please direct angry mobs at [@jkeiser2](

Author John Keiser

John is a Principal Mad Scientist at Chef, has contributed code that will be worked around for years to nearly every piece of software Chef ships. Specific credits include chef-zero, chef-provisioning, and the ChefFS tools (knife diff, upload, and download).

  • caleb_land

    Is Chef local supposed to replace chef solo eventually? I’m new to chef and have just been using chef solo on a few servers, but I don’t see why I would want to use chef solo instead of chef local mode at this point.

    Am I missing something?

    • Local mode wasn’t written to replace chef-solo. We’ve considered the overlaps but have no plans to change chef-solo at this time.

      As cookbook testing has matured, use of chef-solo for testing grew because of it’s inherent isolation. However, chef-solo has always been used by folks whose use case excluded a server. This left a gap on testing the common and powerful features that require a server to be useful, like search. Some workarounds have been added here and there, but chef-solo really wasnt designed for these kinds of use cases. Thus, chef-zero was born.

      Local mode is a logical fusion between chef-client and chef-zero, providing seamless support for full-feature chef runs when you don’t want to hit a server.

  • rcmorano

    killing feature :]

  • irr

    Looks like it can also be used like a workaround for “override run_list” not to save node object in the main chef-server (

    • irr

      nm me, it’s not a good workaround since chef-zero won’t have all the other nodes so search won’t work properly