-
-
Notifications
You must be signed in to change notification settings - Fork 87
Servy CLI
aelassas edited this page Aug 21, 2026
·
140 revisions
Important
Console UI Compatibility
If your app tries to visually update the command prompt (like clearing the screen or moving the cursor), it will crash when running as a background service since services don't have visible windows. To fix this without changing your code, enable the --enableConsoleUI option in the service configuration while installing your service.
Servy includes a command-line interface (CLI) designed for full scripting, automated deployments, and seamless integration into CI/CD pipelines.
The CLI offers a lightweight, script-friendly alternative to the desktop app, focusing on automation and headless use cases while leveraging the same core service management logic as the desktop application.
After installation, the Servy directory is automatically added to the system PATH environment variable. This allows you to run servy-cli directly from any elevated Command Prompt or PowerShell session.
Note
In servy-cli, the equals sign (=) is not supported when using single-character shortcuts (like -n or -p).
To get started, open an elevated Command Prompt or PowerShell window and run:
PS> servy-cli help
Servy.CLI <version>+<commit>
Copyright © 2026 Akram El Assas. All rights reserved.
install Install a Windows service.
uninstall Uninstall a Windows service.
start Start a Windows service.
stop Stop a Windows service.
status Get the current status of a Windows service. Possible results:
NotInstalled, Stopped, StartPending, StopPending, Running,
ContinuePending, PausePending, Paused.
restart Restart a Windows service.
export Export a Servy Windows service configuration to a configuration
file.
import Import a Windows service configuration into the Servy database and
optionally install the service.
help Display more information on a specific command.
version Display version information.
For detailed help on any command, append --help after the command name. For example, to get help for the start command:
PS> servy-cli start --help
Servy.CLI <version>+<commit>
Copyright © 2026 Akram El Assas. All rights reserved.
-n, --name Required. Name of the service to start.
-q, --quiet Suppress spinner and run in non-interactive mode.
--help Display this help screen.
--version Display version information.
The main command for installing or updating a Windows service is install.
Quick Example
The following command installs MyApp.exe as a Windows service named MyService:
servy-cli install --name="MyService" --path="C:\path\to\MyApp.exe"Detailed Usage
Here is its detailed usage:
PS> servy-cli install --help
Servy.CLI <version>+<commit>
Copyright © 2026 Akram El Assas. All rights reserved.
-n, --name Required. Unique service name to install.
--displayName The human-readable name shown in the Windows Services console
(services.msc). If left empty, the service name will be used
instead.
-d, --description Description of the service.
-p, --path Required. Path to the executable process. Supports
environment variable expansion, example:
%JAVA_HOME%\bin\java.exe
--startupDir Startup directory for the process. Supports environment
variable expansion, example: %PROGRAMDATA%\MyApp
--params Additional parameters for the process. Supports environment
variable expansion, example: --params="--data
%ProgramData%\MyApp --bin %MY_VAR%\bin". SECURITY WARNING:
Use the SERVY_PROCESS_PARAMETERS environment variable instead
to avoid exposing sensitive parameters in OS process
listings.
--startupType Service startup type. Options: Automatic,
AutomaticDelayedStart, Manual, Disabled.
--priority Process priority level. Options: Idle, BelowNormal, Normal,
AboveNormal, High, RealTime.
-a, --cpuAffinity Logical CPUs the process may run on (e.g., '0-3,8' or
'0xFF00').
--startTimeout Timeout in seconds to wait for the process to start
successfully before considering the startup as failed. Must
be between 1 and 86400 seconds. Defaults to 10 seconds.
--stopTimeout Timeout in seconds to wait for the process to exit. Must be
between 1 and 86400 seconds. Defaults to 5 seconds.
--enableConsoleUI Enable console user interface for the service. When enabled,
stdout/stderr redirection is disabled.
--stdout Path to stdout log file.
--stderr Path to stderr log file.
--enableRotation Deprecated. Enable size-based log rotation. This option is
kept only for backward compatibility. Use
--enableSizeRotation instead.
--enableSizeRotation Enable size-based log rotation.
--rotationSize Log rotation size in Megabytes (MB). Must be between 1 and
10240 MB.
--enableDateRotation Enable date-based log rotation based on the date interval
specified by --dateRotationType. When both size-based and
date-based rotation are enabled, size rotation takes
precedence.
--dateRotationType Date rotation type. Options: Daily, Weekly, Monthly, None
(None disables date-based rotation; use when only size
rotation is desired).
--maxRotations Maximum rotated log files to keep. Must be between 0 and
10000. Set to 0 or leave empty for unlimited.
--useLocalTimeForRotation Use local server time for log rotation instead of UTC.
Default is false.
--debug Whether debug logs are enabled. When enabled, environment
variables and process parameters are recorded in the
Servy.Service.log file. Not recommended for production
environments, as these logs may contain sensitive
information.
--enableHealth Enable health monitoring.
--heartbeatInterval Heartbeat interval in seconds. Must be between 5 and 86400
seconds.
--maxFailedChecks Maximum allowed failed health checks. Must be between 1 and
100000.
--recoveryAction Recovery action on failure. Options: None, RestartService,
RestartProcess, RestartComputer. Restart service and restart
computer actions are not available if the service runs under
NT AUTHORITY\NetworkService, NT AUTHORITY\LocalService, or a
user account without the required privileges. Only the
restart process action will be available for these accounts.
--recoveryOnCleanExit Enable running recovery action even if the process exits
successfully. Default is false.
--maxRestartAttempts Maximum restart attempts on failure. Must be between 0 and
100000. Set to 0 for unlimited restart attempts.
--heartbeatUrl Absolute URL for out-of-band diagnostic heartbeat pings. Only
used when health monitoring is enabled.
--heartbeatUrlTimeoutSeconds Timeout in seconds for external heartbeat URL requests. Must
be between 2 and 30 seconds.
--enableHeartbeatUrlFlags Append /start and /fail to the heartbeat URL on service start
and failure.
--failureProgramPath The failure program path. Configure a script or executable to
run when the wrapped process exits with a non-zero exit code
(recovery disabled) or after all recovery action retries have
failed (recovery enabled). It is not run when the process
fails to start; that path stops the service. Supports
environment variable expansion, example:
%JAVA_HOME%\bin\java.exe
--failureProgramStartupDir Specifies the directory in which the failure program will
start. If not set, defaults to the service working directory.
Supports environment variable expansion, example:
%PROGRAMDATA%\MyApp
--failureProgramParams Additional parameters for the failure program. SECURITY
WARNING: Use the SERVY_FAILURE_PROGRAM_PARAMETERS environment
variable instead to avoid exposing sensitive parameters in OS
process listings.
--envVars Environment variables for the process. Enter variables in the
format varName=varValue separated by semicolons (;). Use \=
to escape '=', \" to escape '"', \; to escape ';', \\ to
escape '\', and %% to escape '%' (collapses to a single '%').
Supports environment variable expansion, example:
VAR1=%ProgramData%\MyApp; VAR2=%VAR1%\bin. SECURITY WARNING:
Use the SERVY_ENVIRONMENT_VARIABLES environment variable
instead to avoid exposing sensitive parameters in OS process
listings.
--deps Specify one or more Windows service names (not display names)
that this service depends on separated with semicolons (;).
Service names may contain letters, digits, hyphens,
underscores, periods, spaces, and dollar signs ($). Windows
starts stopped dependencies automatically when this service
starts; if a dependency is disabled or fails to start, this
service will not start.
--user The service account username (e.g., .\username,
DOMAIN\username, or DOMAIN\gMSA$). If this option is not set,
the service runs under Local System. If the service runs
under an account other than Local System, you must grant
Modify access to %ProgramData%\Servy for the account running
the service and execute the mandatory hardening script:
Set-ServyExePermissions.ps1 -TargetAccount "domain\user" to
prevent unprivileged binary tampering and local privilege
escalation. Learn script location and execution usage at:
https://github.com/aelassas/servy/wiki/Security#executable-pe
rmission-hardening-mandatory
--password The service account password. SECURITY WARNING: Use the
SERVY_PASSWORD environment variable instead to avoid exposing
credentials in OS process listings.
--preLaunchPath The pre-launch executable path. Configure an optional script
or executable to run before the main service starts. This is
useful for preparing configurations, fetching secrets, or
other setup tasks. If the pre-launch script fails, the
service will not start unless you enable
--preLaunchIgnoreFailure. Supports environment variable
expansion, example: %JAVA_HOME%\bin\java.exe
--preLaunchStartupDir Specifies the directory in which the pre-launch executable
will start. If not set, defaults to the service working
directory. Supports environment variable expansion, example:
%PROGRAMDATA%\MyApp
--preLaunchParams Additional parameters for the pre-launch executable. SECURITY
WARNING: Use the SERVY_PRE_LAUNCH_PARAMETERS environment
variable instead to avoid exposing sensitive parameters in OS
process listings.
--preLaunchEnv Environment variables for the pre-launch executable. Enter
variables in the format varName=varValue separated by
semicolons (;). Use \= to escape '=', \" to escape '"', \; to
escape ';', \\ to escape '\', and %% to escape '%' (collapses
to a single '%'). Supports environment variable expansion,
example: VAR1=%ProgramData%\MyApp; VAR2=%VAR1%\bin. SECURITY
WARNING: Use the SERVY_PRE_LAUNCH_ENVIRONMENT_VARIABLES
environment variable instead to avoid exposing sensitive
parameters in OS process listings.
--preLaunchStdout Path to stdout log file of the pre-launch executable.
--preLaunchStderr Path to stderr log file of the pre-launch executable.
--preLaunchTimeout Timeout for the pre-launch executable. Must be between 0 and
86400 seconds. Set the timeout to 0 to run the pre-launch
hook in fire-and-forget mode. When set to 0, the hook is
started and the service is launched immediately without
waiting for completion. Use this only for tasks that do not
affect the service's ability to start or run correctly.
Stdout/Stderr redirection and retries are not available in
fire-and-forget mode.
--preLaunchRetryAttempts Number of retry attempts for the pre-launch executable if it
fails. Must be between 0 and 100000.
--preLaunchIgnoreFailure Ignore failure and start service even if pre-launch
executable fails.
--postLaunchPath The post-launch executable path. Configure an optional script
or executable to run after the process starts successfully.
Supports environment variable expansion, example:
%JAVA_HOME%\bin\java.exe
--postLaunchStartupDir Specifies the directory in which the post-launch executable
will start. If not set, defaults to the service working
directory. Supports environment variable expansion, example:
%PROGRAMDATA%\MyApp
--postLaunchParams Additional parameters for the post-launch executable.
SECURITY WARNING: Use the SERVY_POST_LAUNCH_PARAMETERS
environment variable instead to avoid exposing sensitive
parameters in OS process listings.
--preStopPath The pre-stop executable path. Configure an optional script or
executable to run before the main service stops. This can be
used for graceful shutdown tasks such as notifying external
systems or draining resources. The pre-stop process runs
synchronously and extends the service stop timeout while it
is running. Set the timeout to 0 to run the pre-stop process
in fire-and-forget mode. Supports environment variable
expansion, example: %JAVA_HOME%\bin\java.exe
--preStopStartupDir Specifies the directory in which the pre-stop executable will
start. If not set, defaults to the service working directory.
Supports environment variable expansion, example:
%PROGRAMDATA%\MyApp
--preStopParams Additional parameters for the pre-stop executable. SECURITY
WARNING: Use the SERVY_PRE_STOP_PARAMETERS environment
variable instead to avoid exposing sensitive parameters in OS
process listings.
--preStopTimeout Timeout for the pre-stop executable. Set the timeout to 0 to
run the pre-stop process in fire-and-forget mode. Must be
between 0 and 86400 seconds.
--preStopLogAsError Log pre-stop failure as error.
--postStopPath The post-stop executable path. Configure an optional script
or executable to run after the wrapped process and all of its
child processes have exited. The post-stop process is started
in fire-and-forget mode and does not block service shutdown.
Supports environment variable expansion, example:
%JAVA_HOME%\bin\java.exe
--postStopStartupDir Specifies the directory in which the post-stop executable
will start. If not set, defaults to the service working
directory. Supports environment variable expansion, example:
%PROGRAMDATA%\MyApp
--postStopParams Additional parameters for the post-stop executable. SECURITY
WARNING: Use the SERVY_POST_STOP_PARAMETERS environment
variable instead to avoid exposing sensitive parameters in OS
process listings.
-q, --quiet Suppress spinner and run in non-interactive mode.
--help Display this help screen.
--version Display version information.
Note
If the value of --params in install command includes arguments that start with --, use an equals sign (=) to prevent parsing issues. Example: --params="--mode=production --port=7008" Without the equals sign, the CLI might interpret --mode or --port as its own options instead of part of the service parameters.
Important
If the service runs under an account other than Local System, you must grant Modify access to %ProgramData%\Servy for the service account and run the mandatory hardening script (Set-ServyExePermissions.ps1 -TargetAccount "domain\user") to lock down binary executables to Read & Execute, preventing unprivileged binary tampering and local privilege escalation. For script location and execution instructions, see the Executable Permission Hardening Guide.
Important
Security Best Practice: Avoid using sensitive flags (e.g., --password, --params, --envVars, --preLaunchEnv) in production or scripts. Passing these values as command-line arguments makes them visible to any user or process with access to the Windows Process List or shell history files. Instead, set the corresponding environment variables (e.g., SERVY_PASSWORD, SERVY_PROCESS_PARAMETERS, SERVY_ENVIRONMENT_VARIABLES) before running the install command. See Security page for more information.
Below is the recommended way to install a service using the secure environment variable fallback pattern:
# 1. Set sensitive values in the current process environment
$env:SERVY_PASSWORD = "your_secret_password"
$env:SERVY_PROCESS_PARAMETERS = "C:\Apps\App\index.js"
$env:SERVY_ENVIRONMENT_VARIABLES = "ENV_VAR1=VAL1; ENV_VAR2=VAL2;"
# 2. Run the install command without sensitive CLI flags
servy-cli install `
--name="My NodeJS Service" `
--description="My NodeJS Server" `
--path="C:\Program Files\nodejs\node.exe" `
--startupDir="C:\Apps\App" `
--startupType="Automatic" `
--priority="Normal" `
--stdout="C:\Apps\App\stdout.log" `
--stderr="C:\Apps\App\stderr.log" `
--enableSizeRotation `
--rotationSize=10 `
--enableHealth `
--heartbeatInterval=10 `
--maxFailedChecks=3 `
--recoveryAction="RestartService" `
--maxRestartAttempts=5 `
--deps="MongoDB; MySQL80" `
--user=".\serviceuser"
# 3. Clear sensitive variables from memory immediately after use
Remove-Item Env:SERVY_PASSWORD
Remove-Item Env:SERVY_PROCESS_PARAMETERS
Remove-Item Env:SERVY_ENVIRONMENT_VARIABLESBelow is an example usage of the install command:
servy-cli install `
--name="My NodeJS Service" `
--description="My NodeJS Server" `
--path="C:\Program Files\nodejs\node.exe" `
--startupDir="C:\Apps\App" `
--params="C:\Apps\App\index.js" `
--startupType="Automatic" `
--priority="Normal" `
--stdout="C:\Apps\App\stdout.log" `
--stderr="C:\Apps\App\stderr.log" `
--enableSizeRotation `
--rotationSize=10 `
--enableHealth `
--heartbeatInterval=10 `
--maxFailedChecks=3 `
--recoveryAction="RestartService" `
--maxRestartAttempts=5 `
--envVars="ENV_VAR1=VAL1; ENV_VAR2=VAL2;" `
--deps="MongoDB; MySQL80"Below is an example usage of the install command with a pre-launch script:
servy-cli install `
--name="MyLegacyService" `
--description="Runs legacy app with dynamic config" `
--path="C:\Apps\LegacyApp\LegacyApp.exe" `
--startupDir="C:\Apps\LegacyApp" `
--params="--mode=production" `
--preLaunchPath="C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" `
--preLaunchStartupDir="C:\Scripts" `
--preLaunchParams="-File C:\Scripts\GenerateConfig.ps1 -VaultUrl https://vault.example.com -SecretName AppSecrets" `
--preLaunchEnv="ENV=production;API_KEY=abcdef123" `
--preLaunchStdout="C:\Logs\prelaunch_stdout.log" `
--preLaunchStderr="C:\Logs\prelaunch_stderr.log" `
--preLaunchTimeout="60" `
--preLaunchRetryAttempts="2" `
--preLaunchIgnoreFailure `
--enableHealth `
--heartbeatInterval="30" `
--maxFailedChecks="3" `
--recoveryAction="RestartService" `
--maxRestartAttempts="5" `
--stdout="C:\Logs\service_stdout.log" `
--stderr="C:\Logs\service_stderr.log" `
--enableSizeRotation `
--rotationSize="10"For more details on CPU affinity, see the FAQ.
-
uninstall: Uninstall an existing service by name. -
start: Start a Windows service by name. -
stop: Stop a Windows service by name. -
restart: Restart a Windows service by name. -
status: Get a Windows service status by name. -
export: Export a Servy Windows service configuration to a configuration file. -
import: Import a Windows service configuration into Servy's database and optionally install it. -
--version: Show CLI version (it's a global flag).
- Always run the CLI with Administrator privileges when executing commands that modify Windows services.
- Use the
--helpflag with any command to display detailed usage information and available options. - When automating with scripts or CI/CD pipelines, rely on the CLI's exit codes:
0indicates success, any other value indicates failure. - Ensure that log file paths are writable by the user account under which the service runs to avoid permission issues.
Copyright © Akram El Assas. All rights reserved.
- Home
- Overview
- Installation Guide
- Advanced Configuration
- Usage
- Servy Desktop App
- Servy Manager
- Servy CLI
- PowerShell Module
- Examples & Recipes
- Logging & Log Rotation
- Health Monitoring & Recovery
- Environment Variables
- Service Dependencies
- Pre-Launch & Post-Launch Actions
- Pre-Stop & Post-Stop Actions
- Shutdown & Teardown
- Export/Import Services
- Automation & CI/CD
- Integration with Monitoring Tools
- Service Event Notifications
- Comparison with Alternatives
- Security
- Architecture
- Building from Source
- Troubleshooting
- FAQ