RFC: add a signed local CLI and capability API over canonical actions

[xcv58]

Summary

Introduce an official mactools command-line tool backed by a versioned, authenticated local IPC contract

The CLI should discover and invoke the same canonical actions used by Unified Search, global shortcuts, Automation, Action Grid, gestures, Run Links, and App Intents.

Canonical actions remain the domain model. Run Links remain the lightweight deep-link interface. The CLI becomes an additional programmatic surface with structured input, output, completion, and error behavior.

Decision Requested

This RFC asks the project to decide:

• Whether MacTools should ship an official CLI
• Which local IPC architecture should connect the CLI to the running host
• How CLI action eligibility relates to existing external-invocation policy
• How the CLI locates or starts the MacTools host
• How the binary is distributed and placed on the user's shell path
• Which commands and guarantees belong in the first version

This RFC does not authorize a network server or remote-control API.

Motivation

Run Links are appropriate for:

• Clickable integrations
• Apple Shortcuts
• Launchers
• Documentation
• Fire-and-forget shell commands
• Stored parameter presets

They are not sufficient for:

• Listing installed actions
• Describing action parameters
• Querying availability
• Passing typed parameters directly
• Receiving structured results
• Returning reliable shell exit codes
• Waiting for completion
• Cancelling cancellable work
• Machine-readable scripting
• Future local agent integrations

A CLI would make MacTools useful from:

• Terminal scripts
• Shell aliases
• Developer tooling
• Alfred, Raycast, Hammerspoon, and similar tools
• Test automation
• Local agents
• A future MCP adapter
• Support and diagnostic workflows

Architectural Invariants

• Plugins continue to publish canonical actions through the existing action registry.
• The CLI does not load plugin bundles.
• The CLI does not implement plugin behavior.
• The CLI does not bypass availability, permission, confirmation, concurrency, or timeout policies.
• The host process remains authoritative for installed plugins and runtime state.
• The CLI communicates only through a local authenticated channel.
• No TCP port or local HTTP server is introduced.
• Run Links remain supported.
• Existing action references remain stable.
• Sensitive action values are never placed in URLs or ordinary command-line arguments.

Proposed Command Surface

The initial command groups should be:

General

• mactools version
• mactools doctor
• mactools help

Actions

• mactools actions list
• mactools actions describe <provider/action>
• mactools actions availability <provider/action>
• mactools actions run <provider/action>
• mactools actions run <provider/action> --parameter name=value
• mactools actions run <provider/action> --input-json <path>
• mactools actions run <provider/action> --json

Workflows

Workflows remain canonical actions, but convenience commands improve usability:

• mactools workflows list
• mactools workflows describe <name-or-id>
• mactools workflows run <name-or-id>
• mactools workflows history <name-or-id>

Plugins

Read-only plugin status may be useful:

• mactools plugins list
• mactools plugins describe <plugin-id>
• mactools plugins doctor <plugin-id>

Installing, updating, and uninstalling plugins should remain outside the first CLI version.

Output Behavior

Human-Readable Mode

Default output should be concise and suitable for interactive terminal use.

Examples of result categories:

• Completed
• Started
• Cancelled
• Unavailable
• Confirmation denied
• Timed out
• Invalid parameters
• Host unavailable
• Provider changed

JSON Mode

--json should produce a versioned object containing:

• Protocol version
• Request ID
• Action reference
• Invocation source
• Start and finish timestamps
• Outcome category
• User-facing message
• Structured rejection category

The output must not contain sensitive parameter values.

Exit Codes

Define stable exit-code categories for:

• Success
• Invalid command or input
• Unknown action
• Action unavailable
• Confirmation denied or unavailable
• Action failure
• Timeout
• Cancellation
• Host or transport failure
• Protocol incompatibility

Exact numeric values should be selected during implementation and documented as part of the CLI contract.

Execution Semantics

Add a distinct .cli action-execution source.

The first version should:

• Wait for validation and confirmation
• Wait for ordinary action completion by default
• Return after durable background work is accepted when the action owns its own progress UI
• Allow --no-wait only when semantics are unambiguous
• Send cancellation when the CLI receives an interrupt and the action is cancellable
• Preserve the action's configured timeout
• Display host-owned confirmation UI for confirmation-required actions
• Fail rather than silently approve when confirmation UI cannot be presented

Fine-grained progress streaming is not required for the first version. The initial protocol may report accepted, started, and final states. A future protocol version can add progress events.

Initial Action Eligibility

Use a conservative policy for the first version.

An action may be run from the CLI only when:

• It is published in the action catalog
• It is currently registered
• Its parameters validate
• It is currently available
• Its execution mode is supported
• It is eligible for external invocation under the current policy
• It contains no unsupported sensitive parameter transport
• The provider has not excluded the CLI surface

Add ActionExposureSurface.cli so providers can explicitly exclude a CLI invocation.

The RFC should decide whether a future dedicated CLI policy is needed for actions that should be available to a signed local CLI but not to URL-based Run Links.

Sensitive Parameters

Do not encourage secrets on the command line because shell histories and process listings may expose them.

Sensitive values should use one of:

• Standard input
• A permission-restricted input file
• A future host-owned secure prompt
• A Keychain-backed saved preset

The host must continue validating parameter privacy metadata.

Sensitive parameter values must never appear in:

• Process arguments
• Logs
• Diagnostics
• JSON output
• Action history
• Error messages

Local Transport Spike

Before implementing the full CLI, compare these architectures.

Option A: User-Scoped Bundled LaunchAgent Using XPC

Potential benefits:

• Discoverable local service
• Launch-on-demand behavior
• Explicit bidirectional interface
• Strong code-signing validation
• Clear service lifecycle

Costs:

• Additional process
• Service Management registration
• Upgrade and removal behavior
• Coordination with the GUI host and plugin runtime

Option B: GUI-Owned Authenticated IPC Endpoint

Potential benefits:

• Fewer long-running processes
• The action registry stays directly inside the existing host
• Simpler ownership after the app is running

Costs:

• Endpoint discovery
• Secure app-launch handoff
• Stale endpoint cleanup
• Peer validation
• More complicated behavior when the app is not running

Option C: User-Owned Unix-Domain Socket

Potential benefits:

• Simple request and response protocol
• Natural streaming and cancellation
• Easy use from multiple languages

Costs:

• Custom authentication
• Socket lifecycle and permissions
• Peer-identity verification
• More custom security code than XPC

The spike should select an option based on:

• Same-user and same-team validation
• Launch behavior
• Upgrade behavior
• Cancellation
• Streaming
• Testability
• Failure recovery
• App Sandbox and signing constraints
• Removal behavior

Do not select a transport only because it is quickest to prototype.

Security Requirements

• Accept connections only from the current user.
• Validate the CLI's code-signing identity where supported.
• Fail closed when identity cannot be established.
• Use a versioned, explicit IPC interface.
• Bound request and response sizes.
• Reject unknown fields or unsupported protocol versions safely.
• Validate every action reference through the registry.
• Revalidate provider generation and availability before execution.
• Preserve confirmation policy.
• Never expose arbitrary Swift invocation, selectors, shell execution, or plugin internals.
• Do not add a general "run arbitrary command" endpoint.
• Keep an optional redacted audit entry for CLI-originated actions.
• Prevent recursive CLI-to-action-to-CLI invocation loops where detectable.

Host Lifecycle

When MacTools is not running, the CLI should:

1. Locate the installed MacTools application.
2. Launch or activate the host without opening unnecessary windows.
3. Wait for action-registry readiness with a bounded timeout.
4. Negotiate the local protocol version.
5. Execute or return a clear startup error.

The CLI must not independently inspect or load installed plugin bundles.

If no graphical user session is available, actions requiring UI or confirmation should fail clearly.

Distribution

Ship a signed CLI binary with the MacTools application.

Evaluate these installation paths:

• Homebrew exposes the bundled binary automatically.
• The app provides an "Install Command Line Tool" or "Show Setup Command" action.
• Users can add a symlink under ~/.local/bin.
• Advanced users can invoke the binary directly from the app bundle.

Avoid introducing a privileged helper solely to create a symlink.

The CLI and application should report compatible protocol and build versions through mactools version and mactools doctor.

Implementation Phases

Phase 0: Transport and Security Spike

• Compare the candidate IPC architectures.
• Implement version handshake.
• Validate same-user and same-team behavior.
• Test app launch and registry readiness.
• Test stale or incompatible clients.
• Document the selected architecture.

Phase 1: Read-Only Discovery

• version
• doctor
• actions list
• actions describe
• actions availability
• workflows list
• Human-readable and JSON output

Phase 2: Conservative Execution

• Run parameterless externally eligible actions.
• Wait for completion.
• Return structured result and exit code.
• Preserve confirmation behavior.
• Add cancellation for cancellable actions.

Phase 3: Typed Parameters

• Validate typed parameter input.
• Support JSON input.
• Support secure sensitive-value input.
• Add saved-preset references where appropriate.

Phase 4: Richer Integrations

• Optional progress events
• Action and workflow history
• MCP adapter
• Better launcher integrations
• Additional authenticated local clients

Test Coverage

Include tests for:

• Protocol-version mismatch
• Unsigned or wrong-team client
• Wrong user
• Host not installed
• Host not running
• Host launch timeout
• Registry startup delay
• Unknown action
• Invalid parameters
• Unavailable action
• Permission failure
• Confirmation approval and denial
• Confirmation unavailable
• External invocation excluded
• Provider changing during execution
• Concurrent invocation policy
• Timeout
• Cancellation
• Sensitive-value redaction
• JSON schema stability
• Exit codes
• App and CLI upgrade ordering

Acceptance Criteria for the RFC

• The product role of the CLI is approved.
• Canonical actions remain the sole execution domain model.
• Run Links remain supported.
• One local transport architecture is selected.
• Client-identity and user-identity requirements are documented.
• Host-startup behavior is decided.
• Initial action-eligibility policy is decided.
• Sensitive-parameter transport is decided.
• Initial command and JSON contracts are approved.
• Distribution and shell-path behavior are decided.
• Phase 0 can proceed without committing to a public remote API.

Non-Goals

• Remote access over the network
• A REST server
• A public cloud API
• Replacing the GUI
• Replacing Run Links
• Loading plugins inside the CLI
• Allowing arbitrary code execution
• Root or system-wide control
• Plugin installation or update in the first version
• Guaranteeing headless execution for actions that require a graphical session
• Declaring the first IPC protocol permanently stable for third parties

Open Questions

• Should CLI eligibility initially reuse Run Link external policy, or should a separate opt-in be required?
• Should the host, a LaunchAgent, or a broker own the IPC listener?
• Should the CLI launch MacTools automatically by default?
• Which actions should be visible but not runnable?
• Should workflow conveniences be aliases over actions or separate IPC operations?
• How should fine-grained progress evolve without changing the current action ABI prematurely?
• What is the preferred Homebrew and non-Homebrew installation path?

[ggbond268]

Thanks for proposing this. I think an official CLI would be a valuable extension to MacTools, especially for automation and scripting. Based on the feedback available today, however, we have not yet seen direct user requests for it, so I would view it as a useful future capability rather than an urgent requirement.

I would prefer the CLI to be delivered as a separate, optional installation package instead of being embedded in the MacTools App bundle. This would keep the main application lightweight for the majority of users who do not need command-line integration.

The CLI could still use the same release version and release cadence as the corresponding MacTools App. Separate packaging would mainly keep installation optional and avoid increasing the size of the main application; it would not require a separate product-versioning scheme.

IPC Architecture

Of the proposed approaches, Option A seems like the strongest fit: a user-scoped, on-demand LaunchAgent provided by the MacTools App and used as an XPC broker.

In this model, the independently installed mactools CLI and the MacTools Host would connect to the broker separately. The broker would have a deliberately narrow role: peer authentication, Host startup, protocol negotiation, request forwarding, and cancellation. It would not load plugins, maintain the Action Catalog, validate Actions, or execute Actions.

The Action Registry, availability checks, confirmation, concurrency control, timeouts, and execution would remain entirely within the MacTools Host. This preserves the Host as the single source of truth and avoids duplicating application behavior in the CLI or broker.

It also seems preferable for the broker to be provided and registered by the MacTools App rather than included in the CLI package. With that separation, not installing the CLI, having a broken CLI installation, or encountering a broker startup failure would not interfere with the normal operation of the main MacTools application.

Independent Packaging

The CLI could be distributed as a separate mactools-cli installation package, with the installed command named mactools. It could be produced by the same release workflow and use the same release version as the MacTools App while remaining a separate, optional download and installation.

For Homebrew distribution, I would prefer installing the binary officially signed by the project while preserving its Developer ID signature. This would avoid relying on Homebrew to rebuild a binary that is unsigned or signed with a different identity.

The CLI and the App could be installed and upgraded separately even when they share the same release version. Runtime compatibility would still be more robust if negotiated through minimum and maximum protocol versions and a capability handshake, rather than assuming that matching product versions always imply protocol compatibility.

To keep the boundary clear, the CLI would not link against PluginKit, inspect plugin directories, or directly read MacTools configuration. The App and CLI would share only a small, independently versioned local protocol specification or protocol package.

Security

For this architecture to remain safe, XPC connections would need mutual authentication. A reasonable verification policy would include the current user's EUID, the Apple Generic Anchor, the expected Team ID, and the exact designated identifiers of the CLI, broker, and Host. Checking only for a shared Team ID would provide a weaker boundary than intended.

The release broker would accept only officially signed builds of the mactools CLI. Development builds could use a separate development service name and separate signing requirements, allowing local development without weakening the verification policy of the production service.

Host Lifecycle

MacTools settings could provide an Enable Command-Line Integration option. When enabled, the App would register the on-demand LaunchAgent through SMAppService.

If the CLI sends a request while the Host is not running, the broker could launch MacTools in the background through LaunchServices without opening unrelated windows. It would then wait for the Host to explicitly report that the Action Registry is ready. Both startup and readiness waiting should have bounded timeouts so that CLI requests cannot wait indefinitely.

Because the first version would permit only safe Actions, it should not normally need to display confirmation UI. If execution-time revalidation determines that an Action requires confirmation, the Host would reject the request rather than silently approve it.

If CLI eligibility is broadened in the future, confirmation UI could remain the responsibility of the Host. When confirmation cannot be displayed, failing closed would be the safer and more predictable behavior.

Action Policy

I suggest keeping CLI exposure separate from Run Link exposure by introducing:

ActionExecutionSource.cli
ActionExposureSurface.cli

CLI exposure could follow the same default polarity as the existing App Intents integration. Providers would use .automatic by default and apply .excluded only to individual Actions that should not be available through the CLI because of security, interaction, or recursion concerns.

In this context, .automatic would only mean that an Action has not been excluded at the exposure layer; it would not grant unconditional permission to execute it.

The Host could reuse the existing App Intents eligibility requirements. An Action would be eligible for CLI access only when all of the following conditions are satisfied:

• The Action is published in the Action Catalog and currently registered.
• risk == .safe.
• The Action supports .background.
• The Action includes the .automatic capability.
• Its ActionReference is portable.
• Its .cli exposure has not been excluded.
• Its parameters conform to the declared schema.
• Its current availability is available.

I would keep the CLI independent from the Run Link externalInvocationPolicy, since Run Links and an authenticated, officially signed local CLI represent different invocation surfaces.

The existing Executor would continue to handle parameter validation, availability checks, execution-mode checks, permissions, confirmation, concurrency control, timeouts, and Provider-generation validation. A Workflow could be exposed through the CLI only when every Action in its complete dependency graph satisfies the CLI eligibility requirements.

First-Version Scope

A practical first version could include:

• mactools version
• mactools doctor
• mactools actions list
• mactools actions describe
• mactools actions availability
• Parameterless mactools actions run
• Human-readable and JSON output
• Waiting for completion, timeouts, and SIGINT cancellation

For the initial scope, I would limit execution to safe Actions and leave confirmation-required and foreground-interactive Actions for a later iteration. If execution-time revalidation determines that confirmation is required, the Host would reject the request.

I would also leave typed parameters, sensitive parameters, progress streaming, history, plugin management, and a separate Workflow IPC interface outside the first version.

The current Canonical Action result does not include typed business output. Because of that, the first-version JSON contract could reasonably cover structured request information, timestamps, execution status, rejection reasons, and messages.

If Action-specific business data needs to be returned in the future, it would be better to extend the Canonical Action result model first rather than introduce a second result model used only by the CLI.

Run Links could continue to serve as the lightweight URL-based invocation interface. The XPC protocol would remain limited to officially signed local MacTools components rather than becoming a public remote-control API.

Overall, this approach would keep the CLI optional and lightweight from the user's perspective, preserve the MacTools Host as the authoritative execution environment, and leave room to expand the CLI later if real user demand emerges.

[xcv58]

Thanks for the detailed feedback. I agree with the big-picture direction and with the framing that an official CLI would be valuable, but is not necessarily an urgent product requirement until we see stronger user demand.

I agree in particular that the CLI should be a separate, optional mactools-cli download rather than embedded in MacTools.app. It can use the same version and release cadence as the app while keeping the main application lightweight. The installed command remains mactools, and the release workflow can publish the officially signed universal binary alongside the app release.

I also agree with Option A: an app-provided, user-scoped XPC LaunchAgent with a deliberately narrow broker. Authentication, host startup, protocol negotiation, forwarding, and cancellation belong in the broker; action discovery, validation, availability, confirmation, concurrency, timeouts, and execution should remain in the MacTools host. That preserves canonical actions and the host as the single source of truth.

I opened draft PR #338 as a working prototype: #338

The prototype currently exercises a somewhat broader surface—including typed parameters, workflow conveniences, and read-only plugin diagnostics—so we can test separate packaging, cold start, upgrade ordering, authentication, cancellation, failure recovery, JSON contracts, and command ergonomics end to end. This is for evaluation and discussion; it does not mean every prototype feature needs to ship in CLI v1.

I also agree that CLI exposure should be represented as its own execution source and exposure surface. The exact relationship between CLI eligibility and Run Link externalInvocationPolicy is still worth validating through the prototype, since an authenticated signed CLI and a URL invocation have different trust and interaction characteristics.

My proposed next step is to treat the draft PR as the Phase 0/prototype implementation, test it locally as a separately installed CLI, and use those results to decide the final v1 scope. We can then narrow the public surface where appropriate without changing the overall architecture.

Overall, I think the proposed separation of packaging, broker responsibility, host authority, and security boundaries is the right foundation.