-
-
Notifications
You must be signed in to change notification settings - Fork 81
Servy CLI
Akram El Assas edited this page Apr 27, 2026
·
126 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, simply turn on --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.exe 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 -c 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 new service.
uninstall Uninstall a service.
start Start a Windows service.
stop Stop a Windows service.
status Get the current status of a Windows service. Possible results: 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 Servy's database.
help Display more information on a specific command.
version Display version information.
For detailed help on any command, append the command name after --help. 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 a Windows service is install.
Quick Example
The following command installs MyApp.exe as a Windows service named MyService:
PS> 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:
--param="%ProgramData%\MyApp"
--param="%MY_VAR%\bin"
--startupType Service startup type. Options:
Automatic, AutomaticDelayedStart,
Manual, Disabled.
--priority Process priority level. Options: Idle,
BelowNormal, Normal, AboveNormal, High,
RealTime.
--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 greater than or equal to 1 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. Set
to 0 or leave empty for unlimited.
--useLocalTimeForRotation Use local server time for log rotation
instead of UTC. Default is false.
--enableHealth Enable health monitoring.
--heartbeatInterval Heartbeat interval in seconds.
--maxFailedChecks Maximum allowed failed health checks.
--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.
--maxRestartAttempts Maximum restart attempts on failure.
Set to 0 for unlimited restart
attempts.
--failureProgramPath The failure program path. Configure a
script or executable to run when the
process fails to start. If health
monitoring is disabled, the program
will run when the process fails to
start. If health monitoring is enabled,
the program will only run after all
configured recovery action retries have
failed. Supports environment variable
expansion, example:
%JAVA_HOME%\bin\java.exe
--failureProgramStartupDir Specifies the directory in which the
failure program will start. Defaults to
the failure program directory. Supports
environment variable expansion,
example: %PROGRAMDATA%\MyApp
--failureProgramParams Additional parameters for the failure
program.
--envVars Environment variables for the process.
Enter variables in the format
varName=varValue separated by
semicolons (;). Use \= to escape '=',
\" to escape '"', \; to escape ';' and
\\ to escape '\'. Supports environment
variable expansion, example:
VAR1=%ProgramData%\MyApp;
VAR2=%VAR1%\bin
--deps Specify one or more Windows service
names (not display names) that this
service depends on separated with
semicolons (;). Use service key names
without spaces or special characters.
Each dependency service must be
installed and running before this
service can start. If a dependency's
start type is Automatic, Windows will
try to start it automatically before
this service. If a dependency fails to
start or is disabled, 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 write access to
%ProgramData%\Servy for the account
that runs the service.
--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.
Defaults to the service working
directory. Supports environment
variable expansion, example:
%PROGRAMDATA%\MyApp
--preLaunchParams Additional parameters for the
pre-launch executable.
--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 ';' and \\ to escape '\'.
Supports environment variable
expansion, example:
VAR1=%ProgramData%\MyApp;
VAR2=%VAR1%\bin
--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.
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 greater or equal to 0.
--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.
Defaults to the directory of the
post-launch program. Supports
environment variable expansion,
example: %PROGRAMDATA%\MyApp
--postLaunchParams Additional parameters for the
post-launch executable.
--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.
--startTimeout Timeout in seconds to wait for the
process to start successfully before
considering the startup as failed. Must
be greater than or equal to 1 second.
Defaults to 10 seconds.
--stopTimeout Timeout in seconds to wait for the
process to exit. Must be greater than
or equal to 1 second. Defaults to 5
seconds.
--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.
Defaults to the directory of the
pre-stop program. Supports environment
variable expansion, example:
%PROGRAMDATA%\MyApp
--preStopParams Additional parameters for the pre-stop
executable.
--preStopTimeout Timeout for the pre-stop executable.
Set the timeout to 0 to run the
pre-stop process in fire-and-forget
mode.
--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.
Defaults to the directory of the
post-stop program. Supports environment
variable expansion, example:
%PROGRAMDATA%\MyApp
--postStopParams Additional parameters for the post-stop
executable.
-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
Security Best Practice: Avoid using the --password flag in production or scripts. Passing passwords as CLI arguments makes them visible in the Windows Process List and shell history. Instead, set the SERVY_PASSWORD environment variable before running the install command.
Below is the recommended way to install a service with credentials:
# 1. Set the password in the current process environment
$env:SERVY_PASSWORD = "your_secret_password"
# 2. Run the install command without the --password flag
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" `
--user=".\serviceuser"
# 3. Clear the variable from memory immediately after use
Remove-Item Env:SERVY_PASSWORDBelow 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" `
--user=".\username" `
--password="secret"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 `
--user=".\serviceuser" `
--password="P@ssw0rd!" `
--enableHealth `
--heartbeatInterval="30" `
--maxFailedChecks="3" `
--recoveryAction="RestartService" `
--maxRestartAttempts="5" `
--stdout="C:\Logs\service_stdout.log" `
--stderr="C:\Logs\service_stderr.log" `
--enableSizeRotation `
--rotationSize="10"-
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.
- 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