CLI Entry Point and Routing
Relevant source files
The following files were used as context for generating this wiki page:
The CLI Entry Point and Routing system manages the execution flow of the spike utility. It initializes the application environment for macOS, parses command-line arguments, and dispatches execution to specific command handlers based on user input.
This system ensures that the CLI process is correctly registered with the WindowServer to allow for screen capture and provides a structured way to handle various tasks such as environment diagnostics, device enumeration, and media recording.
Application Initialization
The entry point initializes the process as a macOS "accessory" application. This initialization is required because standard CLI processes lack a GUI context, which causes ScreenCaptureKit (SCK) window recording to fail during initialization.
let nsApp = NSApplication.shared
nsApp.setActivationPolicy(.accessory)
Sources: Sources/Spike/main.swift:5-7
Command Routing Logic
The routing logic uses a switch statement to evaluate the first argument provided by the user. If no argument is provided, it defaults to a "help" command which prints usage instructions.
The diagram shows the dispatch flow from the entry point to specific command handlers.
Sources: Sources/Spike/main.swift:9-22
Supported Commands
| Command | Description | Source File |
|---|---|---|
doctor | Diagnoses permissions and environment settings. | Sources/Spike/Doctor.swift |
devices | Lists available displays, windows, and audio devices. | Sources/Spike/DevicesCmd.swift |
inspect | Displays track configuration and audio levels of a file. | Sources/Spike/InspectCmd.swift |
rec-system | Records display and system audio. | Sources/Spike/RecSystemCmd.swift |
rec-audio-only | Captures system audio without video. | Sources/Spike/RecAudioOnlyCmd.swift |
rec-device | Records from a specific audio input device (e.g., BlackHole). | Sources/Spike/RecDeviceCmd.swift |
rec-window | Records a specific window and its audio scope. | Sources/Spike/RecWindowCmd.swift |
monitor | Manages multi-output aggregate devices for loopback. | Sources/Spike/MonitorCmd.swift |
Argument Parsing
The Args structure handles the extraction of flags and options from the command-line array. It identifies flags (e.g., --mic) and paired options (e.g., --output <path>).
- Flag detection: Checks if a specific string exists in the arguments.
- Option extraction: Finds the index of a key and retrieves the subsequent element.
- Bare arguments: Filters out all strings starting with
-to identify positional parameters like file paths.
Sources: Sources/Spike/Util.swift:34-42
Common Command Options
Most recording commands share a set of standardized options processed during routing:
| Option | Type | Description |
|---|---|---|
--duration | String | Duration of recording (e.g., "10s", "1m"). Defaults to 6s. |
--output | Path | The destination file path for the recording. |
--match | String | A text string to match window titles or bundle IDs. |
--mic | Flag | Enables simultaneous microphone recording. |
Sources: Sources/Spike/main.swift:25-41, Sources/Spike/Util.swift:44-50
Execution Environment
The router delegates execution to command objects, often passing the Args instance for local parameter handling. Commands like RecSystemCmd and MonitorCmd use these arguments to configure SCStreamConfiguration or AudioHAL operations.
The sequence diagram illustrates how command handlers interact with the argument parser and underlying system frameworks.
Sources: Sources/Spike/main.swift:12-20, Sources/Spike/RecSystemCmd.swift:76-85
Error Handling and Termination
The CLI uses a global fail() function to write error messages to stderr and terminate the process with exit code 2. During recording commands, the system installs signal handlers (SIGINT, SIGTERM) to ensure that AVAssetWriter sessions are finalized before the process exits, preventing file corruption.
Sources: Sources/Spike/Util.swift:13-16, Sources/Spike/Util.swift:63-73