servosity/msp-skills/connectwise-control

ConnectWise Control Claude Code Skill

Prerequisites: Install the CLI

This skill drives the connectwise-control-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. macOS / Linux:

``bash bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/connectwise-control/install.sh) ``

1. Windows (PowerShell):

``powershell iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/connectwise-control/install.ps1 | iex ``

1. Verify: connectwise-control-cli --version
2. Ensure ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows) is on $PATH.

The installer downloads the connectwise-control-cli and connectwise-control-mcp binaries into ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows). It does not register the skill with your agent and writes no MCP client config - see mcp-install.md for that wire-up.

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

connectwise-control-cli drives a ConnectWise Control (ScreenConnect) instance from the terminal or an AI agent: list and inspect remote-support and access sessions, read session detail and the audit log, rename and tag sessions, manage instance users, and run an approved command on a guest machine. sessions stale finds access agents that went dark and security access-review checks every instance user in one call.

When to Use This CLI

Use this CLI when an agent or operator needs to read or manage a ConnectWise Control (ScreenConnect) instance from the terminal: sessions, session groups, users, the audit log, or a reviewed command on a guest machine.

Unique Capabilities

Instance hygiene

• `sessions stale` - List sessions whose guest has not connected for at least --days (default 30), oldest first, plus sessions with no recorded connection.

_Use it to find dead access agents before a license true-up or a client offboarding._

``bash connectwise-control-cli sessions stale --session-type Access --days 30 --agent ``

• `security access-review` - Flag instance users that are disabled, have an expired password, or belong to no security group, with each user's groups listed.

_Use it for a quarterly access review of who can open remote sessions on customer machines._

``bash connectwise-control-cli security access-review --agent ``

Command Reference

audit - Audit metadata and audit-log queries (AuditService).

• connectwise-control-cli audit get-info - Returns metadata about the audit subsystem (available event types and retention).
• connectwise-control-cli audit query-log - Queries audit-log records by session, time window, and event type.

security - Users, roles, and security configuration (SecurityService).

• connectwise-control-cli security delete-user - Deletes an instance user. Requires the x-anti-forgery-token header. Wire format: positional array ['<userName>'].
• connectwise-control-cli security get-configuration - Returns the instance security configuration, including users and roles. Wire format: empty positional array [].
• connectwise-control-cli security save-user - Creates a new instance user or updates an existing one. Requires the x-anti-forgery-token header.

session_groups - Session groups that organize sessions (SessionGroupService).

• connectwise-control-cli session-groups - Returns all session groups configured on the instance.

sessions - Remote support, access, and meeting sessions (PageService).

• connectwise-control-cli sessions add-event-to - Queues a session event (such as Wake-on-LAN) against one or more sessions.
• connectwise-control-cli sessions get-access-token - Issues a one-time access token/URL to join a session. Wire format: positional array ['<group>', '<sessionID>'].
• connectwise-control-cli sessions get-detail - Returns full detail (connections and recent events) for one session.
• connectwise-control-cli sessions list - Returns the live session list for a session type and group.
• connectwise-control-cli sessions run-command - Queues a command or control event on a session.
• connectwise-control-cli sessions update-custom-property - Sets one custom property value on a session.
• connectwise-control-cli sessions update-name - Renames a session. Wire format: positional array ['<group>', '<sessionID>', '<newName>'].

security

• connectwise-control-cli security access-review - Flag instance users that are disabled, have an expired password, or belong to no security group, with each user's groups listed.

sessions

• connectwise-control-cli sessions stale - List sessions whose guest has not connected for at least --days (default 30), oldest first, plus sessions with no recorded connection.

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

connectwise-control-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match - fall back to --help or use a narrower query. --json (and other machine formats) keep that exit-2 contract and write {"matches":[]} on stdout so agents can inspect the envelope without treating a miss as success.

Recipes

Find dark access agents

connectwise-control-cli sessions stale --session-type Access --days 60 --agent

Lists access sessions whose guest has not connected in 60 days, oldest first.

Quarterly user access review

connectwise-control-cli security access-review --agent

Flags disabled users, expired passwords and users in no security group.

Auth Setup

Auth is HTTP Basic with an instance user name and password against your instance base URL. Set CONNECTWISE_CONTROL_BASE_URL, CONNECTWISE_CONTROL_USERNAME and CONNECTWISE_CONTROL_PASSWORD, then run connectwise-control-cli doctor to confirm the login works.

Credential safety

• The HTTP Basic credentials (CONNECTWISE_CONTROL_USERNAME, CONNECTWISE_CONTROL_PASSWORD) and every API request go only to the scheme, host and port of CONNECTWISE_CONTROL_BASE_URL, your instance (for example https://company.screenconnect.com). A redirect to any other host is refused, so the credentials never reach it.
• Any output, file, local-store write or MCP result that would repeat a credential this program holds (the user name, the password, the Basic header, the MCP HTTP token, a session accessToken or the join url that repeats it) is withheld whole: a "[credkit: withheld from ...]" notice stands in its place, in any encoding the shared credential kit reads. Responses are never cached on disk.
• sessions get-access-token issues a one-time token that grants remote control of a guest machine. The token, and the join URL that carries it, are withheld from every output, so the command cannot hand a join link to a script or an agent: join the session from the instance web app.
• Only credentials.toml (mode 0600) holds a credential. auth set-credentials takes the user name and password as arguments, which your shell may keep in its history; the environment variables avoid that.
• --dry-run sends nothing and writes no local file. Over MCP, a tool that changes something (runs a command on a guest, queues a session event, renames or tags a session, issues an access token, saves or deletes an instance user) returns a preview and acts only with confirm: true, and a tool argument can never name a file to read or write.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color.

Global format flags share one contract on promoted, novel, sync, and --deliver paths:

• --json - one JSON document on stdout (sync progress events go to stderr)
• --compact - keep identity/status/timestamp fields; does not change the document vs stream shape
• --csv / --plain - tabular rows (collection envelopes unwrap to the row array). --csv prefixes ' on a cell or header key that starts with =, +, -, @, tab, CR, or LF (fullwidth ＝＋－＠ too) so a spreadsheet does not run it as a formula; a plain signed number such as -5 or +2.5e3 is unchanged.
• --quiet - one identity value per row, no envelope

• Pipeable - JSON on stdout, errors on stderr
• Filterable - --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

``bash connectwise-control-cli session-groups --agent --select name,sessionCount,sessionType ``

• Previewable - --dry-run shows the request without sending
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Non-interactive - never prompts, every input is a flag
• Explicit confirmation - --agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear
• Explicit retries - use --idempotent only when an already-existing create should count as success

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set - piped/agent consumers and explicit-format runs get pure JSON on stdout.

Paths and state

Agents should treat the CLI's path resolver as part of the runtime contract:

• Use --home <dir> for one invocation, or set CONNECTWISE_CONTROL_HOME=<dir> to relocate all four path kinds under one root.
• Use per-kind env vars only when a specific kind must diverge: CONNECTWISE_CONTROL_CONFIG_DIR, CONNECTWISE_CONTROL_DATA_DIR, CONNECTWISE_CONTROL_STATE_DIR, CONNECTWISE_CONTROL_CACHE_DIR.
• Resolution order is per-kind env var, --home, CONNECTWISE_CONTROL_HOME, XDG (XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME), then platform defaults.
• config contains settings like config.toml and profiles. data contains credentials.toml, data.db, cookies, and auth sidecars. state contains persisted queries, jobs, and teach.log. cache contains regenerable HTTP/cache files.
• Stored secrets live in credentials.toml under the data dir. Existing legacy config.toml secrets are read for compatibility and leave config.toml on the first auth write.
• Run connectwise-control-cli doctor --fail-on warn to surface path and credential-location warnings. agent-context exposes a schema v4 paths block for agents that need the resolved dirs.
• For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags:

``json { "mcpServers": { "connectwise-control": { "command": "connectwise-control-mcp", "env": { "CONNECTWISE_CONTROL_HOME": "/srv/connectwise-control" } } } } ``