W3cubDocs

osx_defaults – Manage macOS user defaults

Synopsis
Parameters
Notes
Examples
Status

Synopsis

osx_defaults allows users to read, write, and delete macOS user defaults from Ansible scripts.
macOS applications and other programs use the defaults system to record user preferences and other information that must be maintained when the applications are not running (such as default font for new documents, or the position of an Info panel).

Parameters

Parameter	Choices/Defaults	Comments
array_add boolean	Choices: no ← yes	Add new elements to the array for a key which has an array as its value.
domain string	Default: "NSGlobalDomain"	The domain is a domain name of the form `com.companyname.appname`.
host string		The host on which the preference should apply. The special value `currentHost` corresponds to the `-currentHost` switch of the defaults commandline tool.
key string / required		The key of the user preference.
path string	Default: "/usr/bin:/usr/local/bin"	The path in which to search for `defaults`.
state string	Choices: absent list present ←	The state of the user defaults. If set to `list` will query the given parameter specified by `key`. Returns 'null' is nothing found or mis-spelled. `list` added in version 2.8.
type string	Choices: array bool boolean date float int integer string ←	The type of value to write.
value raw		The value to write. Only required when `state=present`.

Notes

Note

Apple Mac caches defaults. You may need to logout and login to apply the changes.

Examples

- osx_defaults:
    domain: com.apple.Safari
    key: IncludeInternalDebugMenu
    type: bool
    value: true
    state: present

- osx_defaults:
    domain: NSGlobalDomain
    key: AppleMeasurementUnits
    type: string
    value: Centimeters
    state: present

- osx_defaults:
    domain: /Library/Preferences/com.apple.SoftwareUpdate
    key: AutomaticCheckEnabled
    type: int
    value: 1
  become: yes

- osx_defaults:
    domain: com.apple.screensaver
    host: currentHost
    key: showClock
    type: int
    value: 1

- osx_defaults:
    key: AppleMeasurementUnits
    type: string
    value: Centimeters

- osx_defaults:
    key: AppleLanguages
    type: array
    value:
      - en
      - nl

- osx_defaults:
    domain: com.geekchimp.macable
    key: ExampleKeyToRemove
    state: absent

Status

This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]
This module is maintained by the Ansible Community. [community]

Authors

Franck Nijhof (@frenck)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/osx_defaults_module.html