Octo-Notifier

Description

The Octo-Notifier is a command line tool included in Octory's packages. It allows you to trigger actions, update application monitors and display messages whenever you want it. It is a powerfull addition to Octory and can be used directly in your scripts to have full control over Octory's behaviour.

When deployed, Octo-Notifier is installed in /usr/local/bin/octo-notifier.

Name

octo-notifier - Send a notification to Octory's public interface

Synopsis

octo-notifier [--version] [--help | -h]
octo-notifier command [options] [--help | -h]

Commands

The following commands are available:

• monitor - Change the status of a monitor.
• trigger - Trigger an action.
• message - Display a message to the end user.
• help - Display information on other commands.

Monitor

Send an update to a monitor's installation state.

Synopsis

• octo-notifier monitor name [--state | -s] state

Argument	Possible values	Description
name	-	The name of your application must be matching the Name key from Octory's configuration.
state	notInstalled, installing, installed, failed	Installation state displayed in the MonitorsDisplay component.

Trigger

Send a custom trigger event to execute one or more ActionSets.

Synopsis

• octo-notifier trigger name

Argument	Possible values	Description
name	-	The custom trigger name in Octory's configuration.

Message

Display a message to the end user, at any moment, without changing the current configuration.

Availability: Octo-Notifier 1.1.0+

A message is either a banner posted to Notification Center, or a floating window drawn by Octory over the other applications. If no Octory instance is running, Octo-Notifier launches the application just to display the message: no slide, no monitoring and no termination script is executed, and the application quits once the banner is delivered or the window dismissed.

Synopsis

• octo-notifier message title [--body | -b body] [--style style] [--icon icon] [--icon-animation animation] [--button label[:command]] [--sound sound] [--width width] [--height height] [--position position] [--app-path path] [--no-launch]

Argument	Possible values	Style	Description
title	-	both	The message title. This is the only required argument.
--body, -b	-	both	The message body. Supports basic markdown (bold, italic, code, lists, links) and \n for line breaks in the window style.
--style	banner, window	-	How the message is displayed. Default is banner.
--icon	-	window	Icon displayed above the title: an SF Symbol name, an image file path or an image URL. The kind is detected automatically.
--icon-animation	bounce, pulse, wiggle, rotate, breathe, variableColor	window	Animates the icon. Only applies to SF Symbol icons and is ignored for images. Requires --icon.
--button	label[:command]	both	Adds a button. Can be repeated up to 3 times.
--sound	a sound name, or default	banner	Plays a notification sound.
--width	-	window	Window width in points.
--height	-	window	Window height in points.
--position	center, top-left, top-right, bottom-left, bottom-right	window	Where the window appears on the main screen. Default is top-right.
--app-path	-	both	Path to the Octory application, used when no instance is running. Default is /Library/Application Support/Octory/Octory.app.
--no-launch	-	both	Only post the message to a running instance, and fail instead of launching Octory.

warning

The options above are validated before anything is displayed, and a mismatch makes the command fail:

• --icon, --icon-animation, --width, --height and --position are rejected with --style banner.
• --sound is rejected with --style window.
• --icon-animation requires --icon.
• A message accepts at most 3 buttons.

Buttons

A button is declared as "Label" or "Label:command". The value is split on the first colon, so a label cannot contain one.

The command is a shell command, executed as the logged-in user when the end user clicks the button. It is not an Octory trigger, and nothing runs unless the button is clicked.

info

Window buttons dismiss the message, and run their command if they have one. Banner buttons must have a command: the system already provides a way to dismiss a notification.

Examples

A simple banner:

octo-notifier message "Installation complete" --body "Your Mac is ready to use."

A banner with a sound and a button running a command:

octo-notifier message "Update available" \
    --body "A new version of the company toolkit is ready." \
    --sound default \
    --button "Install now:/usr/local/bin/install-toolkit"

A floating window with an animated symbol, placed in the centre of the screen:

octo-notifier message "Restart required" \
    --style window \
    --body "Your Mac needs to restart to **finish** the installation." \
    --icon arrow.clockwise.circle.fill \
    --icon-animation rotate \
    --position center \
    --button "Restart:/sbin/shutdown -r now" \
    --button "Later"

note

A banner is only delivered if the end user allowed notifications for Octory. You can pre-approve them by deploying an MDM Notifications payload for com.amaris.octory.

Help

Show command's help information.

Synopsis

• octo-notifier help command

Argument	Possible values	Description
command	monitor, trigger, message	The command for which you need help with.