Erich Blume
c601514e3d
- Add TestArgumentSeparator class with 8 tests verifying that script arguments must come after '--' separator - Update create and edit command docstrings with examples showing correct usage of '--' separator - Update argument help text to indicate "(must come after '--')" - Add "Passing Arguments to Your Script" section to README Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
84 lines
2.1 KiB
Markdown
84 lines
2.1 KiB
Markdown
# mcquack
|
|
|
|
A simple macOS LaunchAgent manager for executable scripts.
|
|
|
|
Named after Launchpad McQuack, the fearless (if accident-prone) pilot from DuckTales.
|
|
|
|
## Requirements
|
|
|
|
- macOS (uses launchctl and ~/Library/LaunchAgents)
|
|
- [uv](https://github.com/astral-sh/uv)
|
|
|
|
## Installation
|
|
|
|
No installation required! Run directly with:
|
|
|
|
```bash
|
|
uvx git+https://github.com/eblume/mcquack
|
|
```
|
|
|
|
Or clone and run the script directly (it's already executable).
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# List all mcquack-managed LaunchAgents
|
|
mcquack list
|
|
|
|
# Create and load an executable as a LaunchAgent
|
|
mcquack create /path/to/your/script
|
|
|
|
# Create with additional arguments for the script (note the -- separator)
|
|
mcquack create /path/to/your/script -- --arg1 value1 --arg2
|
|
|
|
# Kickstart (immediately run) the LaunchAgent
|
|
mcquack launch /path/to/your/script
|
|
|
|
# Show the current arguments configured in the plist
|
|
mcquack show /path/to/your/script
|
|
|
|
# Edit the arguments in the plist (note the -- separator)
|
|
mcquack edit /path/to/your/script -- --new-arg1 --new-arg2
|
|
|
|
# Unload (stop) the LaunchAgent
|
|
mcquack unload /path/to/your/script
|
|
|
|
# Delete the LaunchAgent plist file
|
|
mcquack delete /path/to/your/script
|
|
```
|
|
|
|
### Passing Arguments to Your Script
|
|
|
|
When passing arguments to your script with `create` or `edit`, you **must** use `--` to
|
|
separate mcquack's options from arguments intended for your script:
|
|
|
|
```bash
|
|
# Correct: passes --config and --debug to your script
|
|
mcquack create my_script.sh -- --config /path/to/config --debug
|
|
|
|
# Wrong: --help is interpreted as mcquack's --help flag, shows help instead
|
|
mcquack create my_script.sh --help
|
|
|
|
# Correct: passes --help as an argument to your script
|
|
mcquack create my_script.sh -- --help
|
|
```
|
|
|
|
The `--` separator ensures that flags like `--help`, `--verbose`, etc. are passed to your
|
|
script rather than being interpreted by mcquack itself.
|
|
|
|
## How it works
|
|
|
|
mcquack creates plist files in `~/Library/LaunchAgents/` with the naming convention:
|
|
|
|
```
|
|
mcquack.eblume.<scriptname>.plist
|
|
```
|
|
|
|
The generated plist configures the script to:
|
|
- Run at load
|
|
- Keep alive (restart if it exits)
|
|
- Log stdout/stderr to `~/Library/Logs/mcquack.<scriptname>.{out,err}.log`
|
|
|
|
## License
|
|
|
|
MIT
|