Skip to content

[Prototype] Add signed local mactools CLI and capability API - #338

Draft
xcv58 wants to merge 20 commits into
ggbond268:mainfrom
xcv58:codex/issue-309-cli-rfc
Draft

[Prototype] Add signed local mactools CLI and capability API#338
xcv58 wants to merge 20 commits into
ggbond268:mainfrom
xcv58:codex/issue-309-cli-rfc

Conversation

@xcv58

@xcv58 xcv58 commented Aug 23, 2026

Copy link
Copy Markdown
Contributor

Prototype status

This draft PR is a working prototype for RFC #309. It is intended to make the packaging, security, IPC, lifecycle, and command-surface decisions testable; it does not propose freezing every implemented command into CLI v1.

What this prototype includes

  • A separately downloadable, signed universal mactools-cli release archive whose installed command is mactools; the CLI executable is not embedded in MacTools.app.
  • An opt-in, user-scoped LaunchAgent/XPC broker provided and registered by the app.
  • A narrow broker responsible for peer authentication, protocol negotiation, host startup, forwarding, admission bounds, and cancellation.
  • Host-owned action discovery and execution through the existing Action Registry and Action Executor.
  • Exact role identity, Team ID, Apple anchor, and effective-user trust checks, with separate development service identities.
  • Versioned request/response contracts, bounded cold start, structured JSON output, stable exit codes, cancellation, and upgrade/failure recovery.
  • A broad prototype command surface covering action discovery/execution, typed and sensitive input transport, workflow conveniences, and read-only plugin diagnostics.
  • Separate release packaging, notarization, checksums, artifact validation, and Homebrew-ready distribution support.

Decisions reflected from the RFC discussion

  • The CLI is optional and distributed separately while sharing the app release cadence.
  • The app provides the broker; the CLI package contains only the command-line executable.
  • The broker does not load plugins or execute actions.
  • MacTools remains the authoritative source for installed plugins, availability, permissions, confirmation, concurrency, timeouts, and execution.
  • Run Links remain supported and no network or public remote-control API is introduced.

Areas to validate before defining v1

  • Which of the broader prototype commands should remain in the first public release.
  • Whether CLI eligibility should be fully independent from Run Link externalInvocationPolicy or retain it as an additional conservative gate.
  • Installation, upgrade-ordering, background-item approval, and removal ergonomics.
  • The appropriate initial policy for safe, interactive, confirmation-required, and parameterized actions.

Verification

The branch includes unit, executable, protocol, packaging, release-layout, and end-to-end coverage. The latest response-contract changes were verified with:

xcodebuild -project MacTools.xcodeproj -scheme MacTools -configuration Debug \
  -derivedDataPath build/DerivedData test -quiet \
  -only-testing:MacToolsTests/CLIParameterInputTests \
  -only-testing:MacToolsTests/CLIExecutableTests

Related to #309.

# Conflicts:
#	scripts/tests/test_plugin_minimum_host_compatibility.py
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant