https://github.com/milly/runtray-ps
Run any console program in the notification area.
https://github.com/milly/runtray-ps
cli gui windows
Last synced: about 1 year ago
JSON representation
Run any console program in the notification area.
- Host: GitHub
- URL: https://github.com/milly/runtray-ps
- Owner: Milly
- License: mit
- Created: 2022-10-14T20:13:39.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-07-19T14:39:24.000Z (almost 3 years ago)
- Last Synced: 2025-03-19T22:15:53.139Z (about 1 year ago)
- Topics: cli, gui, windows
- Language: PowerShell
- Homepage:
- Size: 91.8 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# runtray-ps
A long-running console program can be run in the notification area.
Configure detailed settings in the [JSON configuration file](#json-configuration-file).
## Supported platforms
`runtray.ps1` can run on Windows platforms with PowerShell 3.0 and .NET Framework 4.5 or later versions installed.
[Windows PowerShell system requirements](https://learn.microsoft.com/powershell/scripting/windows-powershell/install/windows-powershell-system-requirements)
Preinstalled since Windows 8.
## Installation
### Unblock downloaded file
Users should unblock files downloaded from the Internet so that Windows does not block access to the files.
#### With GUI
1. Download `runtray.ps1`.
2. Right-click the file and select **Properties** from the context menu.
3. On the **General** tab of the file properties dialog, check the **Unblock** option.
#### With CLI
Use PowerShell's [`Unblock-File`][] cmdlet.
powershell -NoProfile -Command Unblock-File "path\to\runtray.ps1"
[`Unblock-File`]: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/unblock-file
### Use `runtray.ps1` as bundle
1. Download `runtray.ps1` and [Unblock](#unblock-downloaded-file).
2. Copy the ps1 file and write a [JSON configuration file](#json-configuration-file) with the same name to the same folder.
C:\my\app\my-application.ps1
C:\my\app\my-application.json
3. Run install command.
powershell -NoProfile -ExecutionPolicy RemoteSigned C:\my\app\my-application.ps1 install
### Use `runtray.ps1` as global
1. Download `runtray.ps1` to any folder and [Unblock](#unblock-downloaded-file).
C:\my\program\runtray.ps1
2. Write a [JSON configuration file](#json-configuration-file) and put it in any folder.
C:\my\app\my-application.json
3. Run install command.
powershell -NoProfile -ExecutionPolicy RemoteSigned C:\my\program\runtray.ps1 install -ConfigPath C:\my\app\my-application.json
## Start application
The shortcut is installed to the Startup folder, so it will automatically start when you log on to Windows.
Alternatively, you can launch it with the script `start` command.
## Usage
### Command line
```powershell
powershell -NoProfile -ExecutionPolicy RemoteSigned .\runtray.ps1 [Option ...]
```
| Command | Description
| ------- | -----------
| start | Start the executable from shortcut.
| stop | Stop the service.
| restart | Stop and start the service.
| install | Install shortcut to the startup folder.
| uninstall | Remove shortcut from the startup folder.
| run | Start the executable in current terminal. For internal or debug.
| Option | Description
| ------ | -----------
| -ConfigPath `file` | JSON configuration file path.
| -GUI | Enable GUI mode.
| -PassThru | Returns an object in some command.
### JSON configuration file
Note that backslashes must be escaped within the JSON string.
Example::
```json
{
"name": "ping-local",
"description": "Pinging localhost continuously.",
"executable": "%WinDir%\\System32\\ping.exe",
"arguments": ["-t", "127.0.0.1"],
"workingdirectory": "%USERPROFILE%",
"shutdownwait": 2000,
"autorestart": true
}
```
| Element | Required | Type | Default | Description
| ------- | -------- | ---- | ------- | -----------
| $.name | No | string | [^1] | Used for the shortcut filename and the program title.
| $.description | No | string | `""` | Written in the description field of the shortcut.
| $.executable | Yes | string | | Path to the executable. [^2]
| $.arguments | No | string[] | `[]` | Arguments of the executable. [^2]
| $.workingdirectory | No | string | `"."` | Path to the working directory. [^2]
| $.shutdownwait | No | int | `2000` | Wait time in milliseconds after sending Ctrl-C.
| $.autorestart | No | bool | `false` | Auto-restart when service is terminated.
[^1]: The base name of the configuration file without the extension is used.
[^2]: Replace `%name%` in the string with the value of the environment variable with the specified name.