The Xolo admin tool xadm has many options and sub-commands. For detailed help output, use xadm help or xadm help [command].

All of that help output is also available here in the wiki.

The general format of xadm commands is:

xadm [global options] command [target] [command-options]

The global options affect the overall behavior of xadm. The command options are specific to each xadm command

• Walkthru
• Descriptions
• App Bundles abd Version Scripts
  • App Bundles - preferred
  • Version Scripts - if needed
  • Best Practices if no App Bundle is installed normally.
    • Using a Dummy App to hold the version number
    • Using a two-line version script that reads a file
    • Using an executable deployed by your title
• Self Service
• Limiting visibility
• Re-uploading .pkg files

The --walkthru/-w global option will run xadm in interactive mode. Rather than giving the command options as CLI flags, you will be presented with a menu-driven interface where you can enter the values as needed.

Here's an example using xadm --walkthru edit-version xolotest 1.0.0

------------------------------------------------
Editing Version '1.0.0' of Xolo Title 'xolotest'
------------------------------------------------
Current Settings => New Settings

1. Publish Date: 2025-09-28 00:00:00 -0700
2. Minimum OS: 13
3. Maximum OS: 
4. Reboot: false
5. Standalone: true
6. KillApps: 
7. Pilot Computer Groups: xolotest-smartgroup
8. Upload Package: xolotest-100.pkg
9. Cancel
10. Done

Your Choice: 

When you select a value to enter, a description of the value is shown, followed by a prompt for you to enter the new value.

If the item takes multiple values (e.g. KillApps, or Excluded Groups) you'll just see another prompt after you type enter/return. Just keep entering desired values, and enter an 'x' when you're done. To remove all values from such an item, use 'none'.

Values you enter are validated as you enter them. If not valid, you'll see an error message and a new prompt. Use 'x' to get out of ongoing error prompts.

Top

When creating a title, you are required to provide a description that is at least 25 characters long.

This may seem arbitrary, but without leveraging some kind of AI to enforce 'good' descriptions, it is a decent workaround.

Why enforce good descriptions?

Because many times over the years we've been frustrated by unfamiliar d3 packages with no description, or even worse, a description that only says "Installs [title]" (llke, really, I wouldn't have known that 🤦 )

What is a 'good' description? Here are some pointers:

• Tells you what the title is, what it does, what it's for.
• Includes, if available, links or pointers to more detailed info about the title
• Anything else that might help the reader know why the title exists in Xolo

Xolo also requires contact email addresses for all titles - usually the team that maintains the title in xolo. Team or group addresses are preferred, since individuals occasionally leave. Xolo also records who adds, edits, releases, or deletes any versions or titles

Top

Jamf Pro's Patch Management System needs a way to learn not only IF a title is installed on a Mac, but which version is installed. It does this in one of two ways:

• The name and id of an 'App Bundle'
• The output of an 'Extension Attribute' script, which Xolo cals a 'version-script'

Top

Double-clickable apps in macOS are directories with names ending in .app, containing a standard group of files and executables. One file they contain is called Info.plist an xml file which defines many things about the app, including a unique identifier, and the current version.

As part of its normal management process, Jamf Pro gathers data from the Info.plist of all apps installed in known directories. Jamf can then use an app's name, e.g. 'Google Chrome.app' and its "bundle id", e.g. 'com.google.chrome' to know which version of that title is installed.

If a title installs an app bundle into a normal location (e.g. /Applications) and the CFBundleShortVersionString in the Info.plist is the version of the title as a whole, then using the app bundle is the best way for Jamf and Xolo to know what version is installed.

To do so, you provide --app-name and --app-bundle-id when running xadm add-title. To find those values:

• The app name is what you see in the Finder, including the '.app', e.g. 'Google Chrome.app'
• To find the bundle id, you need to look at the app's Info.plist:
  • Right-click on the app icon and choose 'Show Package Contents'
  • In there will be a 'Contents' folder, and in there will be 'Info.plist'
  • Open Info.plist in a text editor, or view its contents in a terminal - its a normal XML plist look for the key CFBundleIdentifier its value is the bundle id you want. Its usually something like 'com.google.chrome'

IMPORTANT: Use the correct version
When creating versions with xadm add-version [title] [version] the [version] string you use MUST match the value in the Info.plist CFBundleShortVersionString key. You can also see this in the Finder by using 'Get Info...' on the .app icon. Even if the publisher shows something different on their website or in their documentation, the value in the Info.plist is what Jamf & Xolo look at.

Top

If a title doesn't install an app bundle, Jamf Patch Management requires a custom script that it can run on every managed mac to determine which, if any, version of a title is installed. It stores this script in an 'Extension Attribute'. Xolo calls these scripts 'version scripts'.

The script can do whatever it needs to learn the currently installed version. It must send that version to standard output, wrapped in a 'result' xml tag, like so: <result>1.23.4</result> (if the title isn't installed, the tag should be empty: <result></result>

This script is run on every managed mac, every time it gathers inventory data to send to Jamf (called 'running a recon'). This can happen several times per day.

Unfortunately, the Extension Attribute data that is part of the Patch Management system is not accessible to other parts of Jamf Pro. But Xolo needs to use that data to maintain a 'smart group' separate from the Patch Management system. This means that Xolo maintains two exact copies of the script in Jamf - the Patch Management Extension Attribute and the 'normal' Extension Attribute - and both of them get run at every recon. So if there are 50 titles that use version scripts, that's 100 scripts that get run on every Mac, at every recon.

As you can see, its wise to limit the number of titles that use version scripts.

Also, as with the important note above, the xolo version string must match the value in the result tag.

Top

If a title doesn't normally install a real app bundle, here's how to get the right info into Jamf.

Using a 'fake' app bundle is the preferred way to do this, since it doesn't add extra overhead to running a recon on all managed Macs.

You can use Script Editor build a simple tiny Applescript .app that does nothing. It will have an Info.plist which you can edit with an appropriate CFBundleIdentifier and CFBundleShortVersionString

1. Launch Script Editor, creating a new document
2. The script contents should be nothing but the word return
3. Save the script as an Application, giving it an appropriate name, e.g. MyTitleXoloVersion.app
4. Edit the Info.plist inside the .app
5. Set the CFBundleName key to your chosen name, without the .app, e.g. 'MyTitleXoloVersion'
6. Set the CFBundleIdentifier key to your chosen id: 'org.myorg.mytitle'
7. When creating your title in Xolo with xadm, use --app-name 'MyTitleXoloVersion.app' --app-bundle-id 'org.myorg.mytitle'
8. Add the app to your project source, deploying it to a folder where it will be seen by Jamf Pro
9. Then every time you package up a new version of your project, update the CFBundleShortVersionString key in the Info.plist to the new version string

The last step can be automated in a CI/CD pipeline, XCode build script, or other means.

It is unlikely (TBD) that you need to sign this app - it literally does nothing so there's no reason to run it, and no need to sign it. It exists merely as an efficient way for Jamf Pro to know what version of your title is installed.

Top

If you absolutely need a script, here's a simple, standardized way to do it

• Create a file in your project that contains only the current version.
• Deploy that file via the installer .pkg

Any out-of-the-way directory works as a location for the file.

When packaging a new version of your title, this file can be created/updated by an automated process such as a CI/CD pipeline, XCode build script, or other means.

Then the version-script for your xolo title can be just 2 lines of code:

#!/bin/zsh
[[ -f '/Library/Application Support/xolo-versions/mytitle' ]] && res=$(< '/Library/Application Support/xolo-versions/mytitle' )
echo "<result>$res</result>"

If your title installs an executable command-line tool, e.g. /usr/local/bin/my-cli-tool and you can make it spit out the version, e.g. with a --version option, then your version script can just use that instead of a special file.

#!/bin/zsh
[[ -x /usr/local/bin/my-cli-tool ]] && res=$( /usr/local/bin/my-cli-tool --version )
echo "<result>$res</result>"

Top

Xolo titles can be set to appear in Self Service, in a given category and with a specified icon.

When this is set, only the released version appears, and it is available to all managed Macs that are not members of an excluded group.

Pilot, skipped, and deprecated versions never appear in Self Service.

• If a version has any defined --pilot-groups, they will get the version automatically
• To install a pilot, deprecated, or skipped version on any other managed Macs, use xadm deploy or ssh to the machine and use sudo xolo install

Top

Versions in Xolo are installable on all computers that are not excluded via an excluded-group. This means they can be installed on any non-excluded mac using xadm deploy or sudo xolo install or Self Service, if configured for it.

If you want to limit which machines it can be installed on, you must use a Jamf Computer Group (Smart or Static) to define the computers that should NOT be able to install it, and use that as an excluded group.

Static groups are just manually maintained lists of computers. Smart groups are dynamic lists based on defined criteria - members are computers that meet the criteria.

Its good practice to use standardized names when creating groups in Jamf, just so all Jamf administrators will know why the group exists. When creating Jamf computer groups for xolo exclusions, please name them along the lines of: xolo-[title]-exclusions.

Top

Sometimes the .pkg installer you provide for a version has problems, even if the software it installs doesn't.

Once you have a new, functional .pkg, you don't need to delete the version from xolo and recreate it - just tell it to use your new .pkg:

xadm edit-version [title] [version] --pkg-to-upload /path/to/new/.pkg

This will upload the new .pkg file, replacing the existing one. Any normal delay for the new pkg to propagate to all distribution points still applies.

After uploading to the primary dist. point, xoloserver will wait some time for the pkg to propagate to all dist. points (currently 15 min).

Then it will enable (if needed), and flush the logs for the 'xolo-[title]-[version]-auto-reinstall' policy, causing the new pkg to be installed wherever that version is already installed. This policy is needed because the version string didn't change, so the patch policy won't do anything to re-deploy the new pkg.

Top