ITAM / Endpoint Agent
workverge-agentctl Reference
Command-line reference for managing the WorkVerge agent service, updates, profiles, and uninstall on macOS and Linux.
Real-world scenario
Carlos Reyes · IT Admin at Bluewave Labs
Carlos SSHes into a Linux endpoint and uses workverge-agentctl instead of remembering systemctl vs launchctl syntax.
Before you begin
- Agent installed
- workverge-agentctl on PATH (~/.local/bin or /usr/local/bin)
Overview
workverge-agentctl is the supported way to manage the agent on macOS (launchd) and Linux (systemd user or system units). It detects the correct service scope automatically.
Service commands
| Command | Description |
|---|---|
| status | Show service state, plist/unit path, PID hints |
| start | Start the agent |
| stop | Stop the agent |
| restart | Stop then start |
| logs | Follow logs (tail on Mac, journalctl on Linux) |
| enable | Start on login / boot |
| disable | Unload service but keep install files |
Typical debugging session
workverge-agentctl status workverge-agentctl logs # Ctrl+C to exit logs workverge-agentctl restart
Lifecycle
| Command | Description |
|---|---|
| update | Download latest bundle from active profile server, reinstall deps, restart |
| version | Print installed version from package.json |
| uninstall | Stop service, remove install dir and ~/.workverge-agent |
| uninstall --keep-profiles | Remove agent binaries but keep profiles.json for re-install |
Profile commands
| Command | Description |
|---|---|
| profile list | List profiles; * marks active |
| profile show | Same as config show |
| profile add NAME --server-url URL --enroll-token TOKEN | Enroll and save profile; add --set-active to switch immediately |
| profile use NAME | Switch active profile, sync service env, restart |
| profile remove NAME | Delete saved profile credentials |
More detail
Config
workverge-agentctl config show prints the active profile as JSON with the JWT redacted. Use this to confirm which server and deviceAgentId the agent is using.
Windows
Use workverge-agentctl.ps1 from C:\Program Files\WorkvergeAgent with similar subcommands: status, start, stop, restart, update, profile list, profile use.
PowerShell
& "C:\Program Files\WorkvergeAgent\workverge-agentctl.ps1" status
Related articles