ControlPlane for macOS: Context Profiles and CLI Setup

ControlPlane's Context-Sensitive Automation Model

ControlPlane addresses repetitive Mac configuration changes. Its documented examples include mounting a network share and changing the default printer after joining a home Wi-Fi network, then reverting the configuration when that context disappears. Connecting a work monitor can activate a different profile. The intended users are macOS users who want local automation driven by their environment rather than by manually switching settings throughout the day.

The rewrite is written in Swift and packaged as a macOS menu-bar application. It supports both Apple Silicon and Intel Macs running macOS 13 Ventura or later. A related audience is developers who prefer managing automation through a command-line interface, since the current implementation has no configuration GUI beyond the menu-bar icon. That distinction matters: ControlPlane is not presented as a general-purpose macOS administration console. It is a local context engine for profile activation and associated actions.

The README labels the rewrite alpha software and explicitly says it is not yet suitable for daily use. It warns of bugs, incomplete features, and breaking changes between releases. Its purpose is still concrete, but the project describes the implementation as an early operational layer rather than a finished desktop utility.

Sensors, Rules, and Weighted Profile Activation

ControlPlane separates observation, decision, and response. Sensors read the Mac's environment, rules compare those readings with configured expectations, and profiles accumulate confidence until they cross a threshold. A matching rule adds a confidence weight to its associated profile. The documentation states that a one-rule profile using the default threshold activates as soon as that rule matches. Multiple rules can express narrower conditions by requiring more confidence.

The sensor set covers Wi-Fi SSID, BSSID, signal strength, Bluetooth connections, USB devices, power and charging state, active network interfaces, IP addresses, DNS configuration, displays, mounted volumes, active and running applications, screen lock state, laptop lid state, audio output, host reachability, time, and file presence. The README presents these as built-in categories, but it does not document the exact configuration syntax for every sensor in the visible instructions.

Actions run when a profile activates or deactivates. Available actions include executing a macOS Shortcut by UUID, running a shell script with arguments, opening files, applications, folders, or URLs, quitting applications, mounting SMB or AFP shares, unmounting volumes, changing desktop backgrounds, controlling Wi-Fi, changing power behavior, starting Time Machine, selecting a backup destination, switching network locations, and setting the default printer. This architecture is more flexible than a fixed Wi-Fi trigger, although it also gives scripts broad access to the Mac and makes action selection an important review point.

Building ControlPlane and Running cpctl

Source builds require Xcode 15 or later, Swift 5.9 or later, and a supported Mac. The Makefile compiles `ControlPlane` and `cpctl` for both `arm64` and `x86_64`, then combines each architecture pair into universal binaries. The `build` target is sufficient for compilation:

make build

The Makefile reports universal output under `.build/universal/debug/`. This creates both architecture variants rather than installing the CLI.

To build, install `cpctl` under `~/.local/bin`, and ad hoc sign that binary, use the documented install command:

make install

The default `make` target runs `build` and `install`, while `make run` also assembles the app bundle, registers it with LaunchServices, and launches it. The Makefile does not show the complete implementation of the truncated `run` recipe, so the visible project instructions should be treated as authoritative rather than assuming extra behavior:

make run

The README also says that first launch installs `cpctl` at `~/.local/bin/cpctl`. Since configuration is currently performed through this CLI, verify that the installation directory is present in `PATH` before invoking it by name. If it is not, the documented absolute installation target is `~/.local/bin/cpctl`.

Start by checking the command interface and current local state:

cpctl status
cpctl profiles list
cpctl rules list
cpctl sensors readings
cpctl evaluators list
cpctl --help

The README does not provide commands for creating the first sensor rule, assigning confidence, or attaching an action to a profile. It documents inspection commands but leaves the exact mutation syntax to `cpctl --help` or unshown repository documentation. Inventing a configuration command would be misleading, so the first real use begins with confirming that the engine is running and exposes the expected readings, followed by using the CLI's own help for profile, rule, and action creation.

Action Scope and macOS Failure Modes

The breadth of available actions is also the main operational risk. A shell script action can perform arbitrary work supported by the user's permissions, while application and volume actions touch active user sessions. Profiles may trigger actions on activation and deactivation, so an incorrect sensor rule can repeatedly apply and reverse system state. The README does not document rate limiting, transaction grouping, failure retries, rollback, or an ordered action log. Those omissions make the exact evaluator and action behavior important to inspect before depending on it.

Wi-Fi is an imperfect identity signal when multiple nearby networks share an SSID. The project also exposes BSSID, which can distinguish a specific access point, but the README does not explain how BSSID values behave when a network uses randomized or changing identifiers. Monitor presence alone can also describe desk geometry rather than user intent unless combined with additional rules.

ControlPlane is the wrong tool for a mandatory, centrally managed Mac policy. Its sensor, profile, and action model is aimed at local context switching, not declarative compliance reporting or remote fleet policy. Users who need auditable deployment, rollback, or a stable configuration database should not assume those capabilities from the alpha application. The absence of a schema migration path makes upgrades especially cautious: the project explicitly warns that the database schema may change between versions.

Alpha Packaging, Updates, and GPL-2.0

The repository is not archived, and its last push was on 2026-07-25. That supports treating the branch as receiving recent development activity, but the README's own readiness warning remains controlling for adoption. The visible release history lists version 1.6.7 from 2019-08-21, while the README describes a modern Swift rewrite from the ground up. The release entry therefore does not by itself establish that a signed, current distribution exists for this rewrite.

Distribution is source oriented. The README states that there is no auto-update mechanism and no code signing or notarization for distribution builds. The Makefile ad hoc signs `cpctl` with `codesign --force --sign -` during installation, but that local signing operation is not documented as release notarization. Build, installation, permissions, and local launch therefore belong to the adopter's environment.

ControlPlane is licensed under GNU General Public License v2.0. Anyone redistributing modified binaries or incorporating the project into another distributed work should review the repository's `LICENSE` and determine how GPL-2.0 applies to that specific distribution. This article does not provide legal advice. For an internal build, the more immediate upgrade cost is preserving compatible profile data and reviewing changed rules and actions before replacing an installed schema.

ControlPlane Compared with Script-Only Automation

A script-only alternative addresses the same automation goal with a simpler model. A launch agent or login script can inspect one condition and execute one command, which avoids ControlPlane's database, confidence scoring, profile thresholds, and sensor abstraction. That approach may be easier to understand when the requirement is narrow, such as running one command when a specific volume appears.

ControlPlane adds value when several independent signals must contribute to a decision and when activation and deactivation require different actions. Its sensor catalog provides a common interface over Wi-Fi, USB, displays, power, applications, time, files, and other conditions. Weighted profiles also allow multiple rules to influence one outcome instead of hard-coding all context detection inside one script.

The trade-off is meaningful. Direct scripts are easier to inspect as code and can be versioned independently of an application database. ControlPlane centralizes sensors and actions, but currently adds alpha packaging risks, a schema without a migration path, and a large action surface. The better choice depends on whether shared context and reversible profiles justify adopting an unfinished local automation application, rather than on either approach being universally preferable.

Editorial conclusion

ControlPlane fits macOS users who want to automate configuration changes from explicit sensor and rule inputs, especially developers comfortable building from source and managing the project through `cpctl`. It does not fit users seeking a polished configuration GUI, signed distribution builds, automatic updates, or stable schema migrations. Verify the complete sensor-to-profile workflow on your required macOS version, confirm that every needed action exists, and review the GPL-2.0 obligations before adopting it.

Frequently asked questions

Official sources

1. dustinrue/ControlPlane on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases