JXA Extensions Kit & CLI

JavaScript for Automation (JXA) Extensions Kit & CLI automate macOS setup, configuring preferences, personalization, etc.

Installation

The easiest way to use JXAX is to install it using our install.sh. Running the following command downloads the jxax CLI and JXAX scripting library into your usr/local/bin and ~/Library/Script Libraries respectively:

$ /bin/zsh -c "$(curl -fsSL https://raw.githubusercontent.com/deskp/jxax/master/scripts/install.sh)"

Usage

Option 1: Configure in YAML and run with `jxax` CLI

jxax CLI allows you to write, store and run your workflows as YAML files, enables writing workflows once and running them many times at many places, which automation is all about.

JXAX's workflows are relatively similar to but simpler than CI/CD workflows.

Configure your workflow in YAML

Here is the configuration used in the GIF demo you see above:

jobs:
  - uses: sysprefs.configureGeneral
    args:
      appearance: dark
      accentColor: blue
      highlightColor: blue
      sidebarIconSize: small
      autoHideMenuBar: false
      showScrollBars: auto
      clickScrollBar: jumpToNextPage
      defaultWebBrowser: Google Chrome.app
      askWhenClosingDocuments: true
      closeWindowsWhenQuittingApp: true
      recentItems: 0
      allowHandoff: true
      useFontSmoothing: true
  - uses: sysprefs.configureDock
    args:
      size: 0.25
      magnification: false
      magnificationSize: 0
      location: left
      minimizeEffect: genie
      preferTabsWhenOpeningDocuments: inFullScreenOnly
      doubleClickTitleBar: zoom
      minimizeToAppIcon: false
      animate: true
      autohide: true
      showOpenIndicators: true
      showRecentApps: false
  - uses: sysprefs.configureMissionControl
    args:
      autoRearrangeSpaces: false
      switchSpaceWhenSwithToApp: true
      groupWindowsByApp: false
      displaysHaveSeparateSpaces: true
      missionControlKeyShortcut: "[control][up]"
      appWindowsKeyShortcut: "[control][down]"
      showDesktopKeyShortcut: F12
  - uses: sysprefs.configureSpotlight
    args:
      searchResults:
        - Applications
        - System Preferences
        - Calculator
        - Conversion
        - Definition
        - Contacts
        - Movies
        - Music
        - PDF Documents
        - Presentations
        - Spreadsheets
        - Spotlight Suggestions
      allowSpotlightInLookup: true
  - uses: desktops.changePicture
    args:
      picture: ~/Pictures/Wallpaper.jpg
  - uses: desktops.configureScreenSaver
    args:
      screenSaver: Brooklyn
      delayInterval: 5
      mainScreenOnly: false
      showClock: true

A workflow has jobs, each job uses a command with a set of args to construct an automation. Check out Features to see full list of supported commands.

Run your workflow

Simply run the jxax CLI with your configured workflow YAML file, either absolute or relative or home (~) paths are applicable:

$ jxax your-workflow.yml

Option 2: Use `JXAX` scripting library in your own script

Installing JXAX using install.sh also installs JXAX.scpt scripting library, which enables easy integration your existing applications or scripts:

// Use in JXA script then run with Script Editor.app or Automator.app or osascript.
var jxax = Library("JXAX");
jxax.runCommand("desktops.changePicture", { picture: "Catalina Rock" });

# Run inline command in shell script.
osascript -l JavaScript -e '''
Library("JXAX").runCommand("desktops.changePicture", {picture: "Catalina Rock"});
'''

Features

Currently, JXAX supports following commands:

Command	Description
`desktops.changePicture`	Change current Desktop picture
`desktops.configureScreenSaver`	Configure screen saver preferences
`sysprefs.configureGeneral`	Configure System Preferences/General
`sysprefs.configureDock`	Configure System Preferences/Dock
`sysprefs.configureMissionControl`	Configure System Preferences/Mission Control
`sysprefs.configureSpotlight`	Configure System Preferences/Spotlight

See Commands for the commands' details (arguments and types).

😬We're adding more features constantly. However, the features to be added are dependent on our maintainers' interests. If you'd love to add a feature, feel free to create an issue and submit a PR! Check out Contributing to see how to.

Contributing

JXAX is designed to be extended by its users and community. Adding an automation to JXAX is easy. So if you've ever used it and wanted to add or added an automation, why don't you create an issue or submit a PR, there may be many people out there share interests with you, your contribution is very likely to be highly appreciated! 💚

See Contributing.

License

This project is licensed under the MIT License.

billyromano/jxax