Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/phuctm97/jxax

💻 JavaScript for Automation (JXA) Extensions Kit & CLI automate macOS setup, configuring preferences, personalization, etc.
https://github.com/phuctm97/jxax

cli javascript javascript-for-automation jxa macos macos-setup osascript osx osx-setup

Last synced: 4 days ago
JSON representation

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

Awesome Lists containing this project

README 

        




  


  Logo

  




  JXA Extensions Kit & CLI

  






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

  personalization, etc.

  



  build

  latest release

  license

  code-style-airbnb

  code-style-prettier




---



![Demo][demo-gif]



---



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



```bash

$ /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:



```yaml

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:



```js

// 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" });

```



```bash

# 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][commands-file] 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][contributing-file] 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][contributing-file].



## License



This project is licensed under the [MIT License][license-file].



Copyright © 2020 - present, Phuc (Minh) Tran. All rights reserved.



[version-badge]: https://img.shields.io/github/package-json/v/deskp/jxax

[build-badge]: https://img.shields.io/github/workflow/status/deskp/jxax/ci

[license-badge]: https://img.shields.io/github/license/deskp/jxax



[demo-gif]: /docs/assets/demo.gif



[features]: #features

[commands-file]: /docs/COMMANDS.md

[license-file]: /LICENSE

[contributing-file]: /CONTRIBUTING.md