---
title: Installing and Managing Agents with ConfigWizardCmd
description: Command-line installation, configuration, and management of QMonitor Agents on Windows and Linux

url: https://help.qmonitor.app/docs/tasks/agents/installation_cmd/index.md
lastmod: 2026-09-16T22:53:51+02:00
---


ConfigWizardCmd is the **command-line tool used to install and manage QMonitor agents**.  
On **Linux**, it is the *only* available configuration method.  
On **Windows**, it is an alternative to the graphical ConfigWizard tool and is suitable for automation, scripting, and DevOps pipelines.

This page documents all commands supported by ConfigWizardCmd, their parameters, and typical usage patterns.

---

## Overview

ConfigWizardCmd is shipped together with the QMonitor agent kit and exposes several commands (verbs):

| Command             | Description                                                    |
|---------------------|----------------------------------------------------------------|
| `set-key`           | Registers or updates the organization key.                     |
| `install`           | Installs and starts an agent service.                          |
| `uninstall`         | Removes an agent service.                                      |
| `start`             | Starts an installed agent.                                     |
| `stop`              | Stops a running agent.                                         |
| `set-serviceaccount`| Updates the service account used by the agent service.         |
| `network-check`     | Tests DNS, TCP, and TLS connectivity to QMonitor endpoints.    |
| `help`              | Prints built-in help text.                                     |

General syntax:

```sh
ConfigWizardCmd <command> [options]
```

---

## 1. Setting the organization key

Before installing agents, register the organization’s key:

```sh
ConfigWizardCmd set-key --org MyOrg --key your_organization_key
```

This command will validate the key and update any installed agents.

If the key is invalid, the command exits with an error.

---

## 2. Installing an agent

To install an agent named `Default`:

```sh
ConfigWizardCmd install --org MyOrg --agent Default --key your_organization_key
```

During installation, ConfigWizardCmd performs:

1. Loading or initializing the organization configuration.
2. License validation via QMonitor APIs.
3. Credential selection:
   - If `--user` and `--password` are provided (Windows only), that account is used.
   - Otherwise the agent runs as **NT AUTHORITY\NetworkService** on Windows.
4. Registering and starting the agent’s operating system service.

### Optional parameters

| Option              | Description                                      |
|---------------------|--------------------------------------------------|
| `--user <name>`     | Windows service account username                 |
| `--password <pwd>`  | Password for the service account (hidden in CLI) |

Example with a custom account:

```sh
ConfigWizardCmd install --org MyOrg --agent Default --key your_key --user DOMAIN\User --password P@ss123
```

---

## 3. Starting and stopping agents

Start a service:

```sh
ConfigWizardCmd start --org MyOrg --agent Default
```

Stop a service:

```sh
ConfigWizardCmd stop --org MyOrg --agent Default
```

These commands interact directly with the OS service manager and do not require a key.

---

## 4. Uninstalling an agent

Remove an agent completely:

```sh
ConfigWizardCmd uninstall --org MyOrg --agent Default
```

This will:

- Stop the service  
- Remove the service definition  
- Update local configuration  

---

## 5. Updating the service account

You can change the credential under which an agent runs:

```sh
ConfigWizardCmd set-serviceaccount --org MyOrg --agent Default --key your_organization_key
```

### Windows behavior

A secure credential prompt appears:

- Leave username/password empty → service runs as **Network Service**  
- Provide domain or local credentials → service runs under that identity  

### Linux behavior

The CLI prompts for:

```
Username:
Password:
```

After updating credentials, the service is automatically restarted.

---

## 6. Network connectivity check

Validate that the agent can connect to QMonitor servers:

```sh
ConfigWizardCmd network-check
```

This tool performs:

1. DNS resolution  
2. TCP connection to port 443  
3. TLS handshake (TLS 1.2/1.3)

Example output:

```
[INFO] api.qmonitor.app -> 2606:4700:...
[ OK ] api.qmonitor.app:443 - TLS established (Tls13)
```

Useful for troubleshooting firewalls, proxies, and outbound restrictions.

---