launchd-simple-api

Simple API to manage services via macosx launchd

Install

npm i @mh-cbon/launchd-simple-api --save

Usage

var LaunchSimpleApi = require('@mh-cbon/launchd-simple-api')

var lsa = new LaunchSimpleApi()

// launchctl list
lsa.list(function (err, items) {
  console.log(items)
})

// find the service file definition,
// then convert it to a json object with plutil
lsa.describe("serviceId", function (err, info) {
  console.log(info)
})

// convert given service file to a json object with plutil
lsa.describeFile("/SystemLibrary/Myservice.plist", function (err, info) {
  console.log(info)
})

// find the service file definition,
// then, launchctl load /the/service/file.plist
lsa.load('fake', {disabled: false, force: false, domain: null, session:null}, function (err) {
  err && console.error(err);
})

// launchctl load /the/service/file.plist
var opts = {disabled: false, force: false, domain: null, session:null}
lsa.loadServiceFile('/SystemLibrary/Myservice.plist', opts, function (err) {
  err && console.error(err);
})

// find the service file definition,
// then, launchctl unload /the/service/file.plist
lsa.unload('fake', {disabled: false, domain: null, session:null}, function (err) {
  err && console.error(err);
})

// launchctl unload /the/service/file.plist
var opts = {disabled: false, domain: null, session:null}
lsa.unloadServiceFile('/SystemLibrary/Myservice.plist', opts, function (err) {
  err && console.error(err);
})

// Look up through each defaults macosx service definition directories
// and try to find for a file named such [service name].plist
lsa.findUnitFile('fake', function (err, list) {
  console.log(list)
})

// Test validity of the given plist service definition file
// plutil /SystemLibrary/Myservice.plist
lsa.testUnitFile('/SystemLibrary/Myservice.plist', function (err) {
  err && console.error(err);
})

// Convert given plist service file into a JSON object
// plutil -convert json -o - /SystemLibrary/Myservice.plist
lsa.convertUnitFile('/SystemLibrary/Myservice.plist', 'json', function (err, info) {
  err && console.error(err);
  console.log(info)
})

// Convert given JSON object into a valid plist content
// plutil -convert json -o - - (< JSON object into stdin)
lsa.convertJsonToPlist({some: 'object'}, function (err, info) {
  err && console.error(err);
  console.log(info)
})

// launhctl start serviceId
lsa.start('serviceId', function (err) {
  err && console.error(err);
})

// launhctl stop serviceId
lsa.stop('serviceId', function (err) {
  err && console.error(err);
})

// launhctl start serviceId
// launhctl stop serviceId
lsa.restart('serviceId', function (err) {
  err && console.error(err);
})

// Find all service file definition for given options
/*
domain === user         => ~/Library/LaunchAgents
domain === global
   jobType === agent    => /Library/LaunchAgents
   jobType === daemon   => /Library/LaunchDaemons
domain === system
   jobType === agent    => /System/Library/LaunchAgents
   jobType === daemon   => /System/Library/LaunchDaemons
*/
lsa.listUnitFiles({domain: 'global', jobType: 'agents'}, function (err, list) {
  console.log(list)
})

Install a service

var service = {
  domain: 'user',
  plist: {
    Label: 'fake',
    ProgramArguments: [
      '/Users/vagrant/node/node-v5.9.1-darwin-x64/bin/node',
      '/Users/vagrant/wd/utils/fake-service.js'
    ]
  }
}
lsa.install(service, function (err, results) {
  err && console.error(err);
  var serviceFile = '/Users/vagrant/Library/LaunchAgents/fake.plist';
  fs.readFile(serviceFile, function (err2, content){
    err2 && console.error(err2);
    console.log(content.toString())
  })
})

// find the corresponding service file, then deletes it
lsa.uninstall('fake', function (err, results) {
  err && console.error(err);
})

// deletes given service file definition
lsa.uninstallUnitFile('/Users/vagrant/Library/LaunchAgents/fake.plist', function (err, results) {
  err && console.error(err);
})

Read more

• http://launchd.info/
• https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html
• https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/launchctl.1.html
• http://alvinalexander.com/mac-os-x/launchd-examples-launchd-plist-file-examples-mac