-
-
Notifications
You must be signed in to change notification settings - Fork 81
Servy CLI
Akram El Assas edited this page Feb 13, 2026
·
126 revisions
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.
Once you install Servy, the CLI executable will be available at:
%ProgramFiles%\Servy\servy-cli.exe
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.
Important
If you face any issues with the CLI in automated or non-interactive environments (e.g., CI/CD, Ansible, WinRM), use --quiet or -q options to suppress interactive output such as spinners or loading animations.
Starting with Servy v6.4+, the CLI automatically detects when no console is attached. You no longer need to pass --quiet manually. The CLI automatically suppresses spinners and console animations in non-interactive sessions (like SYSTEM tasks).
To get started, open a command prompt or PowerShell window (admin), and run:
PS> servy-cli help
Servy.CLI 4.3.0+aa6728bb5456d9ac0b1dced4d756d211fe0fcc14
Copyright © 2025 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 4.3.0+aa6728bb5456d9ac0b1dced4d756d211fe0fcc14
Copyright © 2025 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. Here is its detailed usage:
PS> servy-cli install --help
Servy.CLI 6.0.0+a94501300356b60f770276a15cb5a7c3adeaafa1
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.
--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.
--maxRotations Maximum rotated log files to keep. Set to 0 or
leave empty for unlimited.
--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.
--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.
--env 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, NT
AUTHORITY\NetworkService, or NT
AUTHORITY\LocalService, make sure to grant
write access to %ProgramData%\Servy for the
account running the service.
--password The service account password.
--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 Windows Event Log. 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.
Below is an example usage of the install command:
servy-cli install `
--quiet `
--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" `
--enableRotation `
--rotationSize=10 `
--enableHealth `
--heartbeatInterval=10 `
--maxFailedChecks=3 `
--recoveryAction="RestartService" `
--maxRestartAttempts=5 `
--env="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 `
--quiet `
--name="MyLegacyService" `
--description="Runs legacy app with dynamic config" `
--path="C:\Apps\LegacyApp\LegacyApp.exe" `
--startupDir="C:\Apps\LegacyApp" `
--params="--mode=production" `
--preLaunchPath="C:\Scripts\GenerateConfig.ps1" `
--preLaunchStartupDir="C:\Scripts" `
--preLaunchParams="-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" `
--enableRotation `
--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