[edit on GitHub]

Use the macos_userdefaults resource to manage the macOS user defaults system. The properties of the resource are passed to the defaults command, and the parameters follow the conventions of that command. See the defaults man page for additional information.

New in Chef Client 14.0.


This resource has the following Syntax:

macos_userdefaults 'name' do
  domain                String # required
  global                True, False # default value: 'false'
  key                   String
  sudo                  True, False # default value: 'false'
  type                  String # default value: ""
  user                  String
  value                 # required - see description
  action                Symbol # default to :write if not specified


  • macos_userdefaults is the name of the resource
  • 'name' is the name of the resource block
  • action identifies the steps the chef-client will take to bring the node to the desired state
  • domain, global, key, sudo, type, user, and value are the properties available to this resource


This resource has the following actions:

Default. Writes the setting to the specified domain.
Define this resource block to do nothing until notified by another resource to take action. When this resource is notified, the resource block is either run immediately or it is queued up to be run at the end of the Chef Client run.


This resource has the following properties:


Ruby Type: String

Required. The domain that the user defaults belong to.


Ruby Types: True, False | Default Value: false

Determines whether or not the domain is global.


Ruby Type: String

The preference key.


Ruby Types: True, False | Default Value: false

Set to true if the setting you wish to modify requires privileged access.


Ruby Type: String | Default Value: ""

The value type of the preference key.


Ruby Type: String

The system user that the default will be applied to.


Ruby Types: Integer, Float, String, TrueClass, FalseClass, Hash, Array

Required. The value of the key.


Specify a global domain

macos_userdefaults 'full keyboard access to all controls' do
  domain 'AppleKeyboardUIMode'
  global true
  value '2'

Use an integer value

macos_userdefaults 'enable macOS firewall' do
  domain '/Library/Preferences/'
  key 'globalstate'
  value '1'
  type 'int'

Use a boolean value

macos_userdefaults 'finder expanded save dialogs' do
  domain 'NSNavPanelExpandedStateForSaveMode'
  global true
  value 'TRUE'
  type 'bool'