W3cubDocs

/Ansible

community.general.osx_defaults – Manage macOS user defaults

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.osx_defaults.

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
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

# TODO: Describe what happens in each example

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

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

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

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

- community.general.osx_defaults:
    key: AppleMeasurementUnits
    type: string
    value: Centimeters

- community.general.osx_defaults:
    key: AppleLanguages
    type: array
    value:
      - en
      - nl

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

Authors

  • Franck Nijhof (!UNKNOWN)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/osx_defaults_module.html