swiftDialog turns a command line into a native macOS dialog

A modal dialog aimed at administrators

The README's first substantive sentence defines the project. swiftDialog is an open source admin utility for macOS 15 or later, written in Swift and SwiftUI, that presents custom dialogs, displays informative messages, or can be used as a form to request user input.

The framing word is admin utility, and it decides everything else about the design. This is not a general purpose notification tool, and it is not a UI framework. It is a way for a script running on a managed Mac to put a window in front of the person sitting at it and get something back.

That use case is specific and it is worth being concrete about it. A shell script that needs a user to choose an option, an administrator running a policy that needs a one-off acknowledgement, a script that has to gather a serial number or a reason, or a tool that wants to show a message with an icon and a couple of buttons. In each of those cases the alternatives are a message box bolted onto a script, a web page the user has to open, or nothing at all.

The platform floor is macOS 15, and the README is explicit about what to do below it. For macOS 14 or earlier, it points to version 2.5.6, so the project is currently split across a modern line and a maintained older line, which is a decision administrators have to make once per fleet.

The licence is MIT, with the text in `LICENSE.md`, and the primary language is Swift. The repository is not archived, and the last push was on 2026-10-19.

Appearance is configured piece by piece

The README's appearance section is short, but it reveals how the tool is meant to be used, because the workflow is described as a progression from the simplest case to the decorated one.

At the most simple level, you give swiftDialog a title and a message and it displays them. Everything else is optional, and the README then lists what else you can change.

You can pass in an image resource to display as the icon, or point at an app path or a system preference bundle path, and swiftDialog extracts the icon for display. That last detail matters more than it looks, because an icon taken from the app in question is what makes a dialog look like it belongs to the product rather than to the script that raised it.

You can add extra buttons, change their text to say what you want, wait for user input, or set an automatic timeout so the dialog does not sit on screen forever. The README says every aspect of the appearance can be modified, and points to the documentation site for the details of each of these.

For the message itself, you can use markdown, so bold, italics and URL links are available without escaping anything. You can also add images, and the README gestures at more with an ellipsis rather than enumerating it.

This is a tool for a person who is looking at a screen, so the default assumption is that somebody is there to read it. A script that wants to log something to a file should not be reaching for a dialog.

The input form is the part that makes it more than a message box

The first sentence of the README lists three jobs, and the third is the one that changes what the tool is for. It can be used as a form to request user input.

A dialog that only displays is a nicer `echo`. A dialog that collects input is a small application, and it is the reason a Mac administrator would adopt this rather than a notification.

The pieces the README describes for the display case are the same pieces the input case needs, plus the ability to wait for the user and the ability to time out. The button model is the interesting part, because extra buttons with text you choose are what let a script ask a question with a bounded set of answers rather than a free-text field.

The documentation site is where the details of the input behaviour live, and the README itself does not document the returned values, the input types or the exit codes. That is the gap to be aware of, because the README is a signpost to the documentation rather than a reference, and the documentation at swiftdialog.app is the place to check the behaviour before you build a script on top of it.

For the project structure, the repository gives a hint about how much is bundled in one binary. There is a `dialog.xcodeproj/` at the root, a `dialog/` directory for the app itself, a `dialogcli/` directory, a `DialogNotifier/` directory, and separate `dialogTests/` and `dialogUITests/` targets. The `examples/` directory holds an `inspect/` example, and `docs/` sits alongside `assets/` and a `swiftDialog.icon/` folder.

A project that moved houses but kept its history

The links in the README reveal something about the project's lineage that is worth knowing before you file an issue or a pull request.

The licence link, the release link, the issue link and the contributing guide all point at `bartreardon/Dialog` and `bartreardon/swiftDialog`, while the repository itself now lives under the `swiftDialog` organisation. The author is named in a comment at the bottom of the README as Bart Reardon, with the keywords swift, swiftui, swiftDialog, Dialog, utility, macadmins, apple and macos.

So the project began as a personal repository and now sits in an organisation, and the older URLs still work. For a user that hardly matters. For a contributor it matters a lot, because the pull request template and the contributing guide in the tree are the same ones the old links point at, and the issue link in the README still sends you to the old issue tracker.

The project is also visible in a community rather than only on GitHub. The README invites people to the `#swiftDialog` channel in the MacAdmins Slack, and the badges at the top of the file reference SwiftUI, a Markdown UI project, SwiftyJSON and WebViewKit, which are the libraries the tool sits on.

The repository itself is small in structure. There is a `.swiftlint.yml`, a `CODE_OF_CONDUCT.md`, a `CONTRIBUTING.md`, two Info.plist files with copy in their names, and the usual GitHub and Git directories. The `docs/` directory is where the site content lives, and the `examples/inspect/` folder is the one example named in the tree.

Release cadence, and the beta tags in between

The release history tells you how the project ships, and it shows a pattern that is worth understanding before you pin a version.

The three most recent tags are v3.1.1b2 on 2026-09-25, described as a beta, v3.1.1b3 on 2026-09-29, and v3.1.1 on 2026-10-19, which is the stable release and the same day as the last push.

So the numbering carries a beta suffix, and the betas are separate tags leading up to a stable tag. For a tool that runs on managed Macs, that matters. The betas give you a way to test a change on a small group of machines before it reaches the fleet, and the stable tag is what you would pin in a management system.

The other pattern is the platform split. The current line requires macOS 15, and the v2.5.6 release is what the README points you at for macOS 14 and earlier. Both are maintained, and the choice is a fleet decision rather than a per-machine one.

The documentation is hosted at swiftdialog.app, with the getting started introduction at the path the README links, and the releases page is linked from the README for the latest builds. Nothing in the repository suggests a package manager route such as Homebrew, so the documented distribution is the release artifacts and the documentation site.

What a dialog cannot do for you

There are limits that come from the medium rather than from the implementation, and they are worth naming before you build a workflow on top of this.

A modal dialog needs a human. If your script runs on a Mac that nobody is sitting at, the dialog either waits until somebody arrives or times out, and a timeout means your script continues with whatever the default answer was. The README's mention of an automatic timeout is a reminder that this is an interactive tool and not a reporting channel. A log file, a notification centre banner or a mail message covers the unattended case, and choosing swiftDialog for it is the wrong choice.

The second limit is that the tool runs as a process on the user's machine, so it inherits the permissions and the session of whatever launched it. An administrator running it from a management agent gets a dialog on the console of the logged in user, which is the intent, but it also means the process needs to be able to present a window in that session at all.

The third is the macOS 15 floor. The README tells you plainly that macOS 14 or earlier needs the v2.5.6 line, so a fleet with a mix of operating systems means running two versions of the tool, or pinning the old one until the fleet is upgraded.

What the project gives you in exchange is the thing scripts cannot easily produce: a window that looks like it belongs to the application, on the user's screen, with a question that has a bounded set of answers.

Editorial conclusion

swiftDialog fits a Mac administrator who needs a user to notice something, choose an option or type a value, from a shell script, a Jamf policy or a launch agent. Skip it if you are on macOS 14 or earlier, where the README points you at the older v2.5.6 line, or if a notification centre banner would serve the purpose without a modal window. Verify first that your target machines are on macOS 15 or later, read the input handling behaviour in the documentation site, and confirm that the dialog style you pick does not interrupt a workflow your users run unattended.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. swiftDialog/swiftDialog on GitHub