ConnectSecure - Printing Press CLI

Prerequisites: Install the CLI

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

macOS / Linux:

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

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/connectsecure/install.ps1 | iex

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

The installer downloads the connectsecure-cli and connectsecure-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.

The CLI mints and refreshes the ConnectSecure JWT from your tenant, client ID and secret, and covers the full V4 API, including create, update and delete endpoints. Sync companies, assets and vulnerability reports into local SQLite, then run exposure, portfolio, blind-spots, suppression-audit and ad-hygiene to rank risk across every client offline; qbr and cve-impact call the live API.

When to Use This CLI

Use this CLI when an agent needs ConnectSecure vulnerability, asset, agent, compliance or Active Directory data, especially questions that span all of an MSP's clients at once. It is the right tool for cross-client triage, QBR prep, scan coverage checks and CVE impact lookups, and for scripted changes to companies, tags, suppressions and schedules.

Anti-triggers

Do not use this CLI for:

Deploying or installing the ConnectSecure agent on endpoints; use your RMM.
Real-time EDR alert response; ConnectSecure is a scanning and assessment platform.
Editing report templates visually; use the ConnectSecure portal report builder.

Unique Capabilities

Cross-client risk

exposure - Reads the synced local store (run sync first): rank open vulnerabilities across all clients at asset level, one row per problem x asset x client, top 50 by default (--limit 0 for all), filtered by EPSS, severity, KEV or first-seen window.

Reach for this when asked which clients have the riskiest vulnerabilities and on which machines; it replaces an N+1 asset lookup loop.
```
connectsecure-cli exposure --min-epss 0.5 --severity Critical,High --agent
```
portfolio - Reads the synced local store (run sync first): one row per client with asset count, critical and high findings, max EPSS, KEV count, risk score, stale assets and active suppressions.

Use it to decide which clients need attention this week before drilling into exposure or qbr.
```
connectsecure-cli portfolio --sort max-epss --agent
```
cve-impact - Live API call: for one CVE, show affected clients with asset counts, affected software, available fixes and CVSS/EPSS, and report any assets the API could not attribute to a client.

Use it when a headline CVE lands and the question is which clients to call.
```
connectsecure-cli cve-impact CVE-2024-3400 --agent
```

Scan coverage

blind-spots - Reads the synced local store (run sync first): list assets whose scan data cannot be trusted (stale discovery, unauthenticated scan, silent agent), sorted by client with reason codes; the unauthenticated check is a keyword heuristic unless you pass --auth-ok.

Use it before trusting a clean vulnerability report; missing scans hide findings.
```
connectsecure-cli blind-spots --stale 14d --agent-stale 48h --agent
```
ad-hygiene - Reads the synced local store (run sync first): per client, risky Active Directory accounts (password never expires, not required, no MFA, stale logon), weak password policies and Azure secure score.

Use it for identity-risk reviews across all clients without paging through each AD report.
```
connectsecure-cli ad-hygiene --stale-logon 90d --min-length 12 --agent
```

Client reporting

qbr - Live API call: one client's QBR numbers in one call, with risk score, latest company stats, open findings by age, top fixes and remediation speed; compliance pass/fail is added only when --compliance-type, --compliance-platform and --compliance-section are all set.

Use it when preparing a client review; pipe the JSON into a writer for prose.
```
connectsecure-cli qbr "Acme Dental" --since 90d --agent
```
suppression-audit - Reads the synced local store (run sync first): flag suppressions that expired but are still active, expire soon, never expire, or were unapproved or self-approved, with the suppressed issue's current EPSS.

Use it for the accountability half of remediation reviews; risky suppressions sort first.
```
connectsecure-cli suppression-audit --within 14d --agent
```

Safety for agents

Read freely: the seven analysis commands, sync, search, and every list / get except the credential reads below.
Ask a human first, every time: credentials list / get, integration-credentials list / get, integration-rules list / get, scheduler list / get, attack-surface-results list / get and agents uninstall-secret return stored scan, integration and job secrets (and credentials create / update, integration-credentials create / update, integration-rules create / update and scheduler create / update send one) (and attack-surface creds and hashes) in plaintext, and custom-domains list / get return TLS certificate details whose contents ConnectSecure does not document (custom-domains create uploads the private key); tail on those resources prints them each poll; export credentials (and export integration_credentials, export integration_rules, export scheduler, export attack_surface_results, export custom_domains) prints them to stdout or writes them to the file named by -o; agent-credentials-mapping create / update changes which stored credentials a scan agent uses, and company-mappings create / update which integration credential a client uses; and --deliver webhook:<url> on any command posts its output off the machine.
Preview, then ask: any create, update or report-builder upload runs immediately - pass --dry-run first and show the user the request. patching patch-now (alias patching create) and scheduler create / update / update-schedule change software on client machines (a schedule can force a reboot, tenant-wide), companies scan / companies external-scan send scan traffic at a client network, agents reset (alias agents create) moves agents between companies, suppress-vulnerability create / update hides a finding from every report, discovery-settings, application-baseline-rules, pii-scan-settings, agent-discoverysettings-mapping and attack-surface-domain create / update change what gets scanned and reported, and assets create / update can switch the scan credentials and discovery settings an asset uses or deprecate it out of reporting; never run these, scheduler remove-schedule, assets bulk-deprecate, import (one API write per line of a file) or any delete without explicit confirmation.
MCP read-only mode: when the server runs with CONNECTSECURE_MCP_READ_ONLY=1 it refuses every non-GET call and hides sync, export, import and tail; credential reads through connectsecure_execute still pass. MCP tools also never take a local file path for the CLI to read (teach / teach-playbook notes and playbook files, import --input, the custom-domains create certificate and key, report-builder uploads); run those from the CLI.
Credential records, integration credentials, integration rules, scheduled jobs, attack-surface results, custom domains (as a precaution: their certificate details are undocumented) and the agent uninstall secret are never written to the local store or response cache, so sync --resources credentials refuses before any request, stores nothing and exits non-zero by design; ask the live API when you need them.
To create or update credentials, integration credentials, integration rules or scheduled jobs, pass the JSON body on stdin with --stdin (wrapped as {"data": {...}}, the shape --dry-run shows for the flag form; --stdin sends it exactly as given) instead of --data-params / --data-integration-params / --data-password, so the secret stays out of process arguments and shell history; --dry-run masks secret fields in its preview.
You never need session: the CLI mints its own token. If a user insists, pipe the encoded token in with --client-auth-token - so the client secret stays out of process arguments.
Refresh the mirror with sync --full, not a bare sync: only a full run prunes findings that were remediated since the last sync, so a bare re-sync leaves them counted as open in exposure and portfolio.
Every other GET is cached on disk for 5 minutes. After a fix or suppression, re-run qbr or cve-impact with --no-cache or you get the earlier answer.

Command Reference

agent_credentials_mapping - Manage agent credentials mapping

connectsecure-cli agent-credentials-mapping create - Create agent credential mapping
connectsecure-cli agent-credentials-mapping delete - Delete agent credential mapping
connectsecure-cli agent-credentials-mapping get - Retrieve agent credential mapping
connectsecure-cli agent-credentials-mapping list - Retrieve agent credentials mapping
connectsecure-cli agent-credentials-mapping update - Update agent credential mapping

agent_discoverysettings_mapping - Manage agent discoverysettings mapping

connectsecure-cli agent-discoverysettings-mapping create - Create agent discoverysetting mapping
connectsecure-cli agent-discoverysettings-mapping delete - Delete agent discoverysetting mapping
connectsecure-cli agent-discoverysettings-mapping get - Retrieve agent discoverysetting mapping
connectsecure-cli agent-discoverysettings-mapping list - Retrieve agent discoverysettings mapping
connectsecure-cli agent-discoverysettings-mapping update - Update agent discoverysetting mapping

agents - Manage agents

connectsecure-cli agents get - Retrieve agent
connectsecure-cli agents list - Retrieve agents
connectsecure-cli agents reset - Migrate Agents
connectsecure-cli agents uninstall-secret - Get uninstall secret token

app_baseline_plan_assets - Manage app baseline plan assets

connectsecure-cli app-baseline-plan-assets get - Retrieve app baseline plan asset
connectsecure-cli app-baseline-plan-assets list - Retrieve app baseline plan assets

app_baseline_plan_company - Manage app baseline plan company

connectsecure-cli app-baseline-plan-company get - Retrieve app baseline plan company
connectsecure-cli app-baseline-plan-company list - Retrieve app baseline plan company

app_baseline_plan_global - Manage app baseline plan global

connectsecure-cli app-baseline-plan-global get - Retrieve app baseline plan global
connectsecure-cli app-baseline-plan-global list - Retrieve app baseline plan global

application_baseline_rules - Manage application baseline rules

connectsecure-cli application-baseline-rules create - Create application baseline rule
connectsecure-cli application-baseline-rules delete - Delete application baseline rule
connectsecure-cli application-baseline-rules get - Retrieve application baseline rule
connectsecure-cli application-baseline-rules list - Retrieve application baseline rules
connectsecure-cli application-baseline-rules update - Update application baseline rule

asset_firewall_policy - Manage asset firewall policy

connectsecure-cli asset-firewall-policy get - Retrieve asset firewall policy
connectsecure-cli asset-firewall-policy list - Retrieve asset firewall policy

asset_installed_drivers - Manage asset installed drivers

connectsecure-cli asset-installed-drivers get - Retrieve asset installed driver
connectsecure-cli asset-installed-drivers list - Retrieve asset installed drivers

asset_interface - Manage asset interface

connectsecure-cli asset-interface get - Retrieve asset interface
connectsecure-cli asset-interface list - Retrieve asset interface

asset_msdt - Manage asset msdt

connectsecure-cli asset-msdt get - Retrieve asset msdt
connectsecure-cli asset-msdt list - Retrieve asset msdt

asset_ports - Manage asset ports

connectsecure-cli asset-ports get - Retrieve asset port
connectsecure-cli asset-ports list - Retrieve asset ports

asset_security_report_data - Manage asset security report data

connectsecure-cli asset-security-report-data get - Retrieve asset security report datum
connectsecure-cli asset-security-report-data list - Retrieve asset security report data

asset_shares - Manage asset shares

connectsecure-cli asset-shares get - Retrieve asset share
connectsecure-cli asset-shares list - Retrieve asset shares

asset_storages - Manage asset storages

connectsecure-cli asset-storages get - Retrieve asset storage
connectsecure-cli asset-storages list - Retrieve asset storages

asset_unqouted_services - Manage asset unqouted services

connectsecure-cli asset-unqouted-services get - Retrieve asset unqouted service
connectsecure-cli asset-unqouted-services list - Retrieve asset unqouted services

asset_user_shares - Manage asset user shares

connectsecure-cli asset-user-shares get - Retrieve asset user share
connectsecure-cli asset-user-shares list - Retrieve asset user shares

asset_video_info - Manage asset video info

connectsecure-cli asset-video-info get - Retrieve asset video info
connectsecure-cli asset-video-info list - Retrieve asset video info

asset_view - Manage asset view

connectsecure-cli asset-view get - Retrieve asset view
connectsecure-cli asset-view list - Retrieve asset view

asset_windows_compatibility - Manage asset windows compatibility

connectsecure-cli asset-windows-compatibility - Retrieve asset windows compatibility

asset_windows_reboot_required - Manage asset windows reboot required

connectsecure-cli asset-windows-reboot-required get - Retrieve asset window reboot required
connectsecure-cli asset-windows-reboot-required list - Retrieve asset windows reboot required

assets - Manage assets

connectsecure-cli assets bulk-deprecate - Bulk deprecate assets
connectsecure-cli assets create - Create asset
connectsecure-cli assets delete - Delete asset
connectsecure-cli assets remediation-plan - Retrieve records
connectsecure-cli assets update - Update asset

attack_surface_domain - Manage attack surface domain

connectsecure-cli attack-surface-domain create - Create attack surface domain
connectsecure-cli attack-surface-domain delete - Delete attack surface domain
connectsecure-cli attack-surface-domain get - Retrieve attack surface domain
connectsecure-cli attack-surface-domain list - Retrieve attack surface domain
connectsecure-cli attack-surface-domain update - Update attack surface domain

attack_surface_results - Manage attack surface results

connectsecure-cli attack-surface-results get - Retrieve attack surface result
connectsecure-cli attack-surface-results list - Retrieve attack surface results

backup_software - Manage backup software

connectsecure-cli backup-software create - Create backup software
connectsecure-cli backup-software delete - Delete backup software
connectsecure-cli backup-software get - Retrieve backup software
connectsecure-cli backup-software list - Retrieve backup software
connectsecure-cli backup-software update - Update backup software

bios_info - Manage bios info

connectsecure-cli bios-info get - Retrieve bio info
connectsecure-cli bios-info list - Retrieve bios info

browser_extensions - Manage browser extensions

connectsecure-cli browser-extensions get - Retrieve browser extension
connectsecure-cli browser-extensions list - Retrieve browser extensions

ciphers_view - Manage ciphers view

connectsecure-cli ciphers-view get - Retrieve cipher view
connectsecure-cli ciphers-view list - Retrieve ciphers view

companies - Manage companies

connectsecure-cli companies create - Create company
connectsecure-cli companies delete - Delete company
connectsecure-cli companies external-scan - Scan external endpoint
connectsecure-cli companies get - Retrieve company
connectsecure-cli companies list - Retrieve companies
connectsecure-cli companies scan - Scan Company
connectsecure-cli companies update - Update company

company_mappings - Manage company mappings

connectsecure-cli company-mappings create - Create company mapping
connectsecure-cli company-mappings delete - Delete company mapping
connectsecure-cli company-mappings get - Retrieve company mapping
connectsecure-cli company-mappings list - Retrieve company mappings
connectsecure-cli company-mappings update - Update company mapping

company_stats - Manage company stats

connectsecure-cli company-stats get - Retrieve company stat
connectsecure-cli company-stats list - Retrieve company stats

compliance - Manage compliance

connectsecure-cli compliance - Retrieve Compliance Types

compliance_assessment - Manage compliance assessment

connectsecure-cli compliance-assessment create - Create compliance assessment
connectsecure-cli compliance-assessment delete - Delete compliance assessment
connectsecure-cli compliance-assessment get - Retrieve compliance assessment
connectsecure-cli compliance-assessment list - Retrieve compliance assessment
connectsecure-cli compliance-assessment update - Update compliance assessment

credentials - Manage credentials

connectsecure-cli credentials create - Create credential
connectsecure-cli credentials delete - Delete credential
connectsecure-cli credentials get - Retrieve credential
connectsecure-cli credentials list - Retrieve credentials
connectsecure-cli credentials update - Update credential

custom_domains - Manage custom domains

connectsecure-cli custom-domains create - Custom Domain
connectsecure-cli custom-domains get - Retrieve custom domain
connectsecure-cli custom-domains list - Retrieve custom domains

custom_profile - Manage custom profile

connectsecure-cli custom-profile create - Create custom profile
connectsecure-cli custom-profile delete - Delete custom profile
connectsecure-cli custom-profile get - Retrieve custom profile
connectsecure-cli custom-profile list - Retrieve custom profile
connectsecure-cli custom-profile update - Update custom profile

custom_ticketing_template - Manage custom ticketing template

connectsecure-cli custom-ticketing-template create - Create custom ticketing template
connectsecure-cli custom-ticketing-template delete - Delete custom ticketing template
connectsecure-cli custom-ticketing-template get - Retrieve custom ticketing template
connectsecure-cli custom-ticketing-template list - Retrieve custom ticketing template
connectsecure-cli custom-ticketing-template update - Update custom ticketing template

cve - Manage cve

connectsecure-cli cve - Retrieve records

discovery_settings - Manage discovery settings

connectsecure-cli discovery-settings create - Create discovery setting
connectsecure-cli discovery-settings delete - Delete discovery setting
connectsecure-cli discovery-settings get - Retrieve discovery setting
connectsecure-cli discovery-settings list - Retrieve discovery settings
connectsecure-cli discovery-settings update - Update discovery setting

edr - Manage edr

connectsecure-cli edr create - Create edr
connectsecure-cli edr delete - Delete edr
connectsecure-cli edr get - Retrieve edr
connectsecure-cli edr list - Retrieve edr
connectsecure-cli edr update - Update edr

event_set - Manage event set

connectsecure-cli event-set create - Create event set
connectsecure-cli event-set delete - Delete event set
connectsecure-cli event-set get - Retrieve event set
connectsecure-cli event-set list - Retrieve event set
connectsecure-cli event-set update - Update event set

firewall_groups - Manage firewall groups

connectsecure-cli firewall-groups get - Retrieve firewall group
connectsecure-cli firewall-groups list - Retrieve firewall groups

firewall_interfaces - Manage firewall interfaces

connectsecure-cli firewall-interfaces get - Retrieve firewall interface
connectsecure-cli firewall-interfaces list - Retrieve firewall interfaces

firewall_license - Manage firewall license

connectsecure-cli firewall-license get - Retrieve firewall license
connectsecure-cli firewall-license list - Retrieve firewall license

firewall_rules - Manage firewall rules

connectsecure-cli firewall-rules get - Retrieve firewall rule
connectsecure-cli firewall-rules list - Retrieve firewall rules

firewall_users - Manage firewall users

connectsecure-cli firewall-users get - Retrieve firewall user
connectsecure-cli firewall-users list - Retrieve firewall users

firewall_zones - Manage firewall zones

connectsecure-cli firewall-zones get - Retrieve firewall zone
connectsecure-cli firewall-zones list - Retrieve firewall zones

integration_credentials - Manage integration credentials

connectsecure-cli integration-credentials create - Create integration credential
connectsecure-cli integration-credentials delete - Delete integration credential
connectsecure-cli integration-credentials get - Retrieve integration credential
connectsecure-cli integration-credentials list - Retrieve integration credentials
connectsecure-cli integration-credentials update - Update integration credential

integration_rules - Manage integration rules

connectsecure-cli integration-rules create - Create integration rule
connectsecure-cli integration-rules delete - Delete integration rule
connectsecure-cli integration-rules get - Retrieve integration rule
connectsecure-cli integration-rules list - Retrieve integration rules
connectsecure-cli integration-rules update - Update integration rule

jobs_view - Manage jobs view

connectsecure-cli jobs-view get - Retrieve job view
connectsecure-cli jobs-view list - Retrieve jobs view

patching - Manage patching

connectsecure-cli patching patch-now - Trigger application/OS patch (now or scheduled)
connectsecure-cli patching settings - Retrieve records

pii_scan_settings - Manage pii scan settings

connectsecure-cli pii-scan-settings create - Create pii scan setting
connectsecure-cli pii-scan-settings delete - Delete pii scan setting
connectsecure-cli pii-scan-settings get - Retrieve pii scan setting
connectsecure-cli pii-scan-settings list - Retrieve pii scan settings
connectsecure-cli pii-scan-settings update - Update pii scan setting

report_builder - Manage report builder

connectsecure-cli report-builder cover-page - Report Settings
connectsecure-cli report-builder create-job - Create Report
connectsecure-cli report-builder download-default-template - Report Settings
connectsecure-cli report-builder report-link - Download report
connectsecure-cli report-builder standard-report-settings - Report Settings
connectsecure-cli report-builder standard-reports - List standard report
connectsecure-cli report-builder update-cover-page - Create Report
connectsecure-cli report-builder update-standard-report-settings - Create Report
connectsecure-cli report-builder upload-template - Report Settings

report_jobs_view - Manage report jobs view

connectsecure-cli report-jobs-view get - Retrieve report job view
connectsecure-cli report-jobs-view list - Retrieve report jobs view

report_queries - Manage report queries

connectsecure-cli report-queries ad-basic-info - Retrieve ad basic info
connectsecure-cli report-queries ad-computers-view - Retrieve ad computers view
connectsecure-cli report-queries ad-domain-details - Retrieve ad domain details
connectsecure-cli report-queries ad-gpos-details - Retrieve ad gpos details
connectsecure-cli report-queries ad-gpos-view - Retrieve ad gpos view
connectsecure-cli report-queries ad-group-computers - Retrieve ad group computers
connectsecure-cli report-queries ad-group-users - Retrieve ad group users
connectsecure-cli report-queries ad-groups-view - Retrieve ad groups view
connectsecure-cli report-queries ad-ous-view - Retrieve ad ous view
connectsecure-cli report-queries ad-password-policies - Retrieve ad password policies
connectsecure-cli report-queries ad-roles - Retrieve ad roles
connectsecure-cli report-queries ad-roles-details - Retrieve ad roles details
connectsecure-cli report-queries ad-roles-member - Retrieve ad roles member
connectsecure-cli report-queries ad-user-licenses - Retrieve ad user licenses
connectsecure-cli report-queries ad-users-view - Retrieve ad users view
connectsecure-cli report-queries adaudit - Retrieve adaudit
connectsecure-cli report-queries application-count - Retrieve records
connectsecure-cli report-queries application-vulnerabilities - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-by-os - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-by-os-software-details - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-by-os-software-details-suppressed - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-by-product - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-by-product-suppressed - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-by-product-suppressed-tag - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-by-product-tag - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-net - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-net-suppressed - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-net-suppressed-tag - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-net-tag - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-os-patch - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-patching-asset-details - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-suppressed - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-suppressed-by-os - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-suppressed-tag - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-suppressed-tag-by-os - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-tag - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-tag-by-os - Retrieve records
connectsecure-cli report-queries application-vulnerabilities-v2 - Retrieve records
connectsecure-cli report-queries asset-compliance-details - Retrieve records
connectsecure-cli report-queries asset-compliance-report-data - Retrieve records
connectsecure-cli report-queries asset-critical-vulnerabilities - Retrieve records
connectsecure-cli report-queries asset-firewall-rules - Retrieve asset firewall rules
connectsecure-cli report-queries asset-iptables-rules - Retrieve asset iptables rules
connectsecure-cli report-queries asset-open-ports - Retrieve asset open ports
connectsecure-cli report-queries asset-patches-info - Retrieve asset patches info
connectsecure-cli report-queries asset-ports-view - Retrieve records
connectsecure-cli report-queries asset-processes-running - Retrieve asset processes running
connectsecure-cli report-queries asset-registry-misconfiguration - Retrieve asset registry misconfiguration
connectsecure-cli report-queries asset-security-report-data - Retrieve records
connectsecure-cli report-queries asset-security-report-data-bulk - Retrieve asset security report data
connectsecure-cli report-queries asset-services - Retrieve asset services
connectsecure-cli report-queries asset-software - Retrieve records
connectsecure-cli report-queries asset-stats - Retrieve asset stats
connectsecure-cli report-queries asset-users - Retrieve asset users
connectsecure-cli report-queries asset-wise-vulnerabilities - Retrieve records
connectsecure-cli report-queries assets - Retrieve assets
connectsecure-cli report-queries assets-by-application - Retrieve records
connectsecure-cli report-queries assets-by-application-suppressed - Retrieve records
connectsecure-cli report-queries azure-ad-logs - Retrieve azure ad logs
connectsecure-cli report-queries azure-licenses - Retrieve azure licenses
connectsecure-cli report-queries azure-secure-score - Retrieve azure secure score
connectsecure-cli report-queries cert-info-view - Retrieve records
connectsecure-cli report-queries companies-by-application - Retrieve records
connectsecure-cli report-queries companies-by-application-suppressed - Retrieve records
connectsecure-cli report-queries companies-by-problem-group - Retrieve records
connectsecure-cli report-queries companies-by-problem-group-suppressed - Retrieve records
connectsecure-cli report-queries compliance-asset-info - Retrieve records
connectsecure-cli report-queries compliance-check-asset-count - Retrieve records
connectsecure-cli report-queries compliance-check-company-count - Retrieve records
connectsecure-cli report-queries compliance-check-count - Retrieve records
connectsecure-cli report-queries compliance-check-count-by-section - Retrieve records
connectsecure-cli report-queries compliance-count - Retrieve records
connectsecure-cli report-queries compliance-internal-checks - Retrieve records
connectsecure-cli report-queries compliance-maturity - Retrieve records
connectsecure-cli report-queries cron-jobs - Retrieve cron jobs
connectsecure-cli report-queries distinct-agents-name - Retrieve records
connectsecure-cli report-queries distinct-asset-ip - Retrieve records
connectsecure-cli report-queries distinct-asset-name - Retrieve records
connectsecure-cli report-queries distinct-discovered-protocols - Retrieve records
connectsecure-cli report-queries distinct-os - Retrieve records
connectsecure-cli report-queries distinct-platform - Retrieve records
connectsecure-cli report-queries distinct-software - Retrieve records
connectsecure-cli report-queries distinct-tags - Retrieve records
connectsecure-cli report-queries event-stats - Retrieve event stats
connectsecure-cli report-queries event-tickets - Retrieve event tickets
connectsecure-cli report-queries external-asset-externalscan - Retrieve records
connectsecure-cli report-queries external-asset-ports-data - Retrieve records
connectsecure-cli report-queries external-asset-ssl-attack - Retrieve records
connectsecure-cli report-queries external-asset-ssl-ciphers - Retrieve records
connectsecure-cli report-queries external-asset-vulnerabilities - Retrieve records
connectsecure-cli report-queries get-assets-by-problem - Retrieve records
connectsecure-cli report-queries get-assets-problem - Retrieve records
connectsecure-cli report-queries get-computer-details - Retrieve get computer details
connectsecure-cli report-queries get-groups-details - Retrieve get groups details
connectsecure-cli report-queries get-ous-details - Retrieve get ous details
connectsecure-cli report-queries get-remediate-records - Retrieve records
connectsecure-cli report-queries get-remediation - Retrieve records
connectsecure-cli report-queries get-user-details - Retrieve get user details
connectsecure-cli report-queries job-details - Retrieve job details
connectsecure-cli report-queries job-details-view - Retrieve job details view
connectsecure-cli report-queries kernel-modules - Retrieve kernel modules
connectsecure-cli report-queries lightweight-assets - Retrieve records
connectsecure-cli report-queries notification-tickets-view - Retrieve records
connectsecure-cli report-queries notification-tickets-view-legacy - Retrieve notification tickets view
connectsecure-cli report-queries os-pending-patches - Retrieve records
connectsecure-cli report-queries os-pending-patches-companies - Retrieve records
connectsecure-cli report-queries ports-assets-details - Retrieve records
connectsecure-cli report-queries ports-count - Retrieve records
connectsecure-cli report-queries ports-view - Retrieve records
connectsecure-cli report-queries problem-group-summary - Retrieve records
connectsecure-cli report-queries problem-group-summary-asset-company-count - Retrieve records
connectsecure-cli report-queries problems-info - Retrieve records
connectsecure-cli report-queries problems-remediations-summary - Retrieve records
connectsecure-cli report-queries problems-ssl-for-asset - Retrieve records
connectsecure-cli report-queries problems-summary - Retrieve records
connectsecure-cli report-queries problems-summary-asset-details - Retrieve records
connectsecure-cli report-queries problems-summary-global - Retrieve records
connectsecure-cli report-queries problems-summary-group-by-companies - Retrieve records
connectsecure-cli report-queries problems-summary-tag - Retrieve records
connectsecure-cli report-queries registry-problems-company - Retrieve records
connectsecure-cli report-queries registry-problems-remediation - Retrieve records
connectsecure-cli report-queries registry-problems-remediation-asset-details - Retrieve records
connectsecure-cli report-queries registry-problems-summary - Retrieve records
connectsecure-cli report-queries remediate-records - Retrieve records
connectsecure-cli report-queries remediate-records-assets - Retrieve records
connectsecure-cli report-queries remediate-records-companies - Retrieve records
connectsecure-cli report-queries remediate-records-days - Retrieve records
connectsecure-cli report-queries remediated-registry-solution-plan - Retrieve records
connectsecure-cli report-queries remediation-companies - Retrieve records
connectsecure-cli report-queries remediation-plan-asset-details - Retrieve records
connectsecure-cli report-queries remediation-plan-asset-details-by-epss - Retrieve records
connectsecure-cli report-queries remediation-plan-asset-epss-details - Retrieve records
connectsecure-cli report-queries remediation-plan-by-company - Retrieve records
connectsecure-cli report-queries remediation-plan-include-company - Retrieve records
connectsecure-cli report-queries remediation-plan-include-company-days - Retrieve records
connectsecure-cli report-queries remediation-velocity-application - Retrieve records
connectsecure-cli report-queries remediation-velocity-application-asset-details - Retrieve records
connectsecure-cli report-queries remediation-velocity-company - Retrieve records
connectsecure-cli report-queries resolved-remediation - Retrieve records
connectsecure-cli report-queries risk-score - Retrieve records
connectsecure-cli report-queries selinux-settings - Retrieve selinux settings
connectsecure-cli report-queries suid-permissions - Retrieve suid permissions
connectsecure-cli report-queries suppress-vulnerability-problems - Retrieve records
connectsecure-cli report-queries suppress-vulnerability-problems-sid - Retrieve records
connectsecure-cli report-queries suppress-vulnerability-solution - Retrieve records
connectsecure-cli report-queries suppressed-problems - Retrieve records
connectsecure-cli report-queries sw-problems-remediations-view - Retrieve records
connectsecure-cli report-queries sw-problems-remediations-view-assetwise - Retrieve records
connectsecure-cli report-queries sw-problems-remediations-view-vul - Retrieve records
connectsecure-cli report-queries system-events-view - Retrieve system events view
connectsecure-cli report-queries system-events-view-ticketid - Retrieve system events view
connectsecure-cli report-queries tags-view - Retrieve records
connectsecure-cli report-queries total-asset-count - Retrieve records
connectsecure-cli report-queries ufw-firewall-rules - Retrieve ufw firewall rules
connectsecure-cli report-queries unconfirmed-key-check - Retrieve records
connectsecure-cli report-queries unconfirmed-open-ports-key-check - Retrieve records
connectsecure-cli report-queries user-enabled-stats - Retrieve user enabled stats
connectsecure-cli report-queries user-event-stats - Retrieve user event stats
connectsecure-cli report-queries user-locked-stats - Retrieve user locked stats
connectsecure-cli report-queries vulnerabilities-count - Retrieve records
connectsecure-cli report-queries vulnerabilities-details - Retrieve records
connectsecure-cli report-queries vulnerabilities-details-suppressed - Retrieve records

scheduler - Manage scheduler

connectsecure-cli scheduler create - Create scheduler
connectsecure-cli scheduler delete - Delete scheduler
connectsecure-cli scheduler get - Retrieve scheduler
connectsecure-cli scheduler list - Retrieve scheduler
connectsecure-cli scheduler remove-schedule - Update schedule
connectsecure-cli scheduler update - Update scheduler
connectsecure-cli scheduler update-schedule - Update schedule

session - Manage session

connectsecure-cli session - Authorize

suppress_vulnerability - Manage suppress vulnerability

connectsecure-cli suppress-vulnerability create - Create suppres vulnerability
connectsecure-cli suppress-vulnerability delete - Delete suppres vulnerability
connectsecure-cli suppress-vulnerability get - Retrieve suppres vulnerability
connectsecure-cli suppress-vulnerability list - Retrieve suppress vulnerability
connectsecure-cli suppress-vulnerability update - Update suppres vulnerability

tag_rules - Manage tag rules

connectsecure-cli tag-rules create - Create tag rule
connectsecure-cli tag-rules delete - Delete tag rule
connectsecure-cli tag-rules get - Retrieve tag rule
connectsecure-cli tag-rules list - Retrieve tag rules
connectsecure-cli tag-rules update - Update tag rule

tags - Manage tags

connectsecure-cli tags create - Create tag
connectsecure-cli tags delete - Delete tag
connectsecure-cli tags get - Retrieve tag
connectsecure-cli tags list - Retrieve tags
connectsecure-cli tags update - Update tag

users - Manage users

connectsecure-cli users - Retrieve Users

windows_protection_status - Manage windows protection status

connectsecure-cli windows-protection-status get - Retrieve window protection status
connectsecure-cli windows-protection-status list - Retrieve windows protection status

ad-hygiene

connectsecure-cli ad-hygiene - Reads the synced local store (run sync first): per client, risky Active Directory accounts (password never expires, not required, no MFA, stale logon), weak password policies and Azure secure score.

blind-spots

connectsecure-cli blind-spots - Reads the synced local store (run sync first): list assets whose scan data cannot be trusted (stale discovery, unauthenticated scan, silent agent), sorted by client with reason codes; the unauthenticated check is a keyword heuristic unless you pass --auth-ok.

cve-impact

connectsecure-cli cve-impact - Live API call: for one CVE, show affected clients with asset counts, affected software, available fixes and CVSS/EPSS, and report any assets the API could not attribute to a client.

exposure

connectsecure-cli exposure - Reads the synced local store (run sync first): rank open vulnerabilities across all clients at asset level, one row per problem x asset x client, top 50 by default (--limit 0 for all), filtered by EPSS, severity, KEV or first-seen window.

portfolio

connectsecure-cli portfolio - Reads the synced local store (run sync first): one row per client with asset count, critical and high findings, max EPSS, KEV count, risk score, stale assets and active suppressions.

qbr

connectsecure-cli qbr - Live API call: one client's QBR numbers in one call, with risk score, latest company stats, open findings by age, top fixes and remediation speed; compliance pass/fail is added only when --compliance-type, --compliance-platform and --compliance-section are all set.

suppression-audit

connectsecure-cli suppression-audit - Reads the synced local store (run sync first): flag suppressions that expired but are still active, expire soon, never expire, or were unapproved or self-approved, with the suppressed issue's current EPSS.

Freshness Contract

This printed CLI owns bounded freshness only for registered store-backed read command paths. In --data-source auto mode, those paths check sync_state and may run a bounded refresh before reading local data. --data-source local never refreshes. --data-source live reads the API (through the 5-minute on-disk response cache; add --no-cache to force a fresh call) and does not mutate the local store. Set CONNECTSECURE_NO_AUTO_REFRESH=1 to skip the freshness hook without changing source selection.

Covered paths: Pre-read refresh applies to the generated list and get commands of synced resources, for example companies list, agents list, tags list and edr list. Credential resources (credentials, integration-credentials, integration-rules), scheduled jobs (scheduler, whose rows carry a password field), attack-surface results (attack-surface-results, whose rows carry creds and hashes fields), custom domains (custom-domains, a precaution: their certificate details are undocumented) and the agent uninstall secret are never cached or synced locally. The local novel commands (exposure, portfolio, blind-spots, suppression-audit, ad-hygiene) read the store directly and print a hint: line naming any resource that was never synced.

When JSON output uses the generated provenance envelope, freshness metadata appears at meta.freshness. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment.

Finding the right command

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

connectsecure-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

Critical vulns, narrowed for an agent

connectsecure-cli report-queries vulnerabilities-details --condition "severity='Critical'" --limit 50 --agent --select problem_name,epss_score,base_score,affected_assets

Pull only the fields that matter from a large report query.

Which clients does this CVE hit

connectsecure-cli cve-impact CVE-2024-3400 --agent

Per-client affected asset counts plus available fixes for one CVE (live API).

Assets you cannot trust

connectsecure-cli blind-spots --stale 14d --agent-stale 48h

Stale, unauthenticated, or agent-silent assets sorted by client, with reason codes (local store).

One client's QBR numbers

connectsecure-cli qbr "Acme Dental" --since 90d --agent

Risk score, latest stats, open findings by age, top fixes and remediation speed in one JSON pack (live API).

Auth Setup

ConnectSecure uses a token exchange, not OAuth. Set CONNECTSECURE_BASE_URL to your pod URL (Profile > API Documentation, for example https://pod106.myconnectsecure.com, not the portal login URL), plus CONNECTSECURE_TENANT (your portal login tenant), CONNECTSECURE_CLIENT_ID and CONNECTSECURE_CLIENT_SECRET (Settings > Users > user > API Key). The CLI calls POST /w/authorize with Client-Auth-Token set to base64 of tenant, a literal plus sign, client_id, a colon and client_secret, caches the returned JWT and user ID, and sends Authorization: Bearer plus X-USER-ID on every call. If you already have a token, set CONNECTSECURE_ACCESS_TOKEN and CONNECTSECURE_USER_ID instead.

Run connectsecure-cli doctor to verify setup.

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)
--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:
```
connectsecure-cli companies list --agent --select id,name,domain
```
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
Writes are not confirmation-gated - API writes (create, update, delete, scans) run immediately and are not --yes-gated; preview them with --dry-run first. --yes only answers this CLI's own local prompts, such as profile delete.
Explicit retries - use --idempotent only when an already-existing create should count as success, and use --ignore-missing only when a missing delete target 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 (qbr and cve-impact print their report object at the top level unless --agent wraps it in the same envelope; export and tail stream with no envelope: export prints raw records as JSONL, or one JSON array with --format json, and tail prints one {"event", "timestamp", "data"} object per line) (live also covers a response served from the 5-minute on-disk cache). 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 CONNECTSECURE_HOME=<dir> to relocate all four path kinds under one root.
Use per-kind env vars only when a specific kind must diverge: CONNECTSECURE_CONFIG_DIR, CONNECTSECURE_DATA_DIR, CONNECTSECURE_STATE_DIR, CONNECTSECURE_CACHE_DIR.
Resolution order is per-kind env var, --home, CONNECTSECURE_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, the store data-<hash>.db (its path is db_path in doctor --agent), 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 connectsecure-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:

{
  "mcpServers": {
    "connectsecure": {
      "command": "connectsecure-mcp",
      "env": {
        "CONNECTSECURE_HOME": "/srv/connectsecure"
      }
    }
  }
}

Fleet precedence: an inherited per-kind env var overrides an explicit --home for that kind. Use CONNECTSECURE_HOME or per-kind vars as durable fleet levers, and use --home only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing CONNECTSECURE_HOME, or doctor will not find credentials left under the former root.

Automatic learning

This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a flag_alias candidate, and a teach on a query family without a playbook auto-synthesizes a playbook_candidate from the session's journal. Your job is judgment only: recall first, act on surfaced candidates, teach the final answer, playbook amend when you observe a correction. You never record failures by hand.

Step 1: `recall` before any discovery

Before list/search/drill commands on a new user question, pass the question as an argv or MCP tool argument to recall --agent. Do not interpolate user-controlled text into a shell command line.

Quoted recall "<question>" breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data:

# Write the question verbatim with your file-writing tool (no shell involved).
# Command substitution on a file only ever yields data  -  the shell never
# parses the file's bytes as syntax.
QUERY=$(cat /path/to/question.txt)
connectsecure-cli recall "$QUERY" --agent

Prefer MCP: pass the question as the tool's query argument. "$QUERY" after a file read is argv-safe; putting the question itself in the command text is not.

The response envelope:

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "connectsecure-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and learnings list and learnings candidates are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught.

Step 2: decision tree

Read candidates, playbook, notes, results[0], and warnings in that order:

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `connectsecure-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a Results[] hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping mismatches; pass --debug-mismatches only when investigating cold-start surprises.

Candidate judgment details: learnings confirm <id> prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. learnings reject <id> tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; connectsecure-cli learnings candidates lists the full open set.

Graceful degradation: if learnings confirm is an unknown command, you are driving an older binary - ignore the candidates guidance and follow the rest of the protocol.

Step 3: always read `warnings`

low_confidence: row exists at confidence<2. Treat as a hint, not a skip-discovery hit.
resource_not_in_store: the local store doesn't have the resource the learning points at. The match validator couldn't classify entities - direct-fetch and re-evaluate.
cross_alias_match (per-result): the row was taught under a different alias and matched the live query's canonical via entity_lookups (e.g., a "USA" teach satisfying a "United States" recall). Trust the resource_id.
similar_shape_different_entity:<canonical> (top-level): a structurally matching row exists but its canonical entity differs from the live query's. Treated as cold start; the warning carries the conflicting canonical as a hint, but the row is NOT promoted into Results.
ambiguous_alias (top-level): a single query entity resolved to multiple canonicals (e.g., "Cards" → Arizona Cardinals + St. Louis Cardinals). Surface the ambiguity from context before committing to a resource.
candidates_present (top-level): the envelope carries a candidates section. Handle it via the candidates branch in Step 2 before anything else.
lookup_refresh_available (top-level): an entity in the query has no lookup row yet, but synced data could provide one. Run connectsecure-cli sync --full to refresh entity lookups.
Top-level no_learnings_for_query_family: the table had no rows above the Jaccard floor. Pure cold start.

Step 4: `teach &` after finalizing your response - always

Teaching is unconditional. After resolving a query the store could not answer, background-teach the final resource mapping - no call-count threshold, no judging whether it was "worth" learning. The teach is the anchor of the loop: it triggers playbook synthesis for a family without a playbook, and same-referent phrasings fold into one family so near-duplicate teaches do not fragment the store. Fire it after assembling your user-facing response but BEFORE emitting it, with a shell & so the call returns immediately. Pass the query the same way as recall - argv/MCP, or file-then-$QUERY. Do not splice the question into the command text:

QUERY=$(cat /path/to/question.txt)
connectsecure-cli teach --query "$QUERY" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

Silent on success. Errors only land in teach.log under the resolved state dir. Teach the most specific resource - if the user asked a broad question and you walked through parent records to find the specific answer, teach the leaf id, not the parent. The CLI uses seeded entity_lookups for cross-alias resolution at recall time, so a teach under one alias (e.g., "Niners") satisfies future queries under another alias (e.g., "49ers", "San Francisco") automatically.

PII rule: teach the structural question with identifiers stripped - never include names, emails, phone numbers, account ids, or other personal identifiers in taught queries or notes. The CLI scans teach queries for obvious email/phone shapes and warns, but does not block; strip before teaching rather than relying on the warning.

Step 5: playbooks - optional flags, automatic synthesis

You do not need to decide whether a session "deserves" a playbook: a teach on a family without one auto-synthesizes a playbook_candidate from the session's journal, and the next session judges it via confirm/reject. Attach explicit playbook flags only when you already hold choreography worth recording verbatim - workarounds the CLI didn't surface (silently-dropped flags, undocumented params, pagination tricks, payload gotchas). Prefer the integrated one-call form - record the resource learning and the playbook in the same teach invocation:

# Common case: record both the resource learning AND the playbook in one call.
QUERY=$(cat /path/to/question.txt)
connectsecure-cli teach \
  --query "$QUERY" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
QUERY=$(cat /path/to/question.txt)
connectsecure-cli teach-playbook \
  --query "$QUERY" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

Playbook files are JSON with steps, entity_slots, expected_tool_calls. Notes files are markdown carrying the gotchas verbatim. File-free callers (MCP-only agents) pass the same content inline: --playbook-json and --playbook-notes on the integrated teach form, --playbook-json and --notes on teach-playbook. On the integrated teach form, the playbook flags are optional - omit them entirely for a resource-only teach. On the standalone teach-playbook form, at least one of the playbook and notes flags must be set; both empty is rejected. Playbooks are keyed on the structural query family (entities stripped) so a recipe taught from one entity-shaped query applies to every other query of the same shape, with slots_resolved binding the live query's canonical at recall time.

When you DO find a playbook on a future recall, treat it as ground truth: replay the steps with slots_resolved substitutions, skip the discovery that the choreography already documents, and read notes before any step.

Step 6: `playbook amend &` when your debug response identifies a correction

If your debug-protocol response identifies a concrete correction the notes or playbook should know - a workaround, an undocumented endpoint shape, a stale field name, observed schema drift, an empty-payload fallback - fire playbook amend BEFORE emitting your user-facing response. Same fire-and-forget posture as teach. Pass the query and note as argv/MCP arguments, or write each with a non-shell file tool and read them back (QUERY=$(cat ...), NOTE=$(cat ...)). Do not interpolate either string into the command text:

QUERY=$(cat /path/to/question.txt)
NOTE=$(cat /path/to/note.txt)
connectsecure-cli playbook amend \
  --query "$QUERY" \
  --add-note "$NOTE"
# (append shell `&` to background it)

What counts as worth amending: a behavior you OBSERVED this session that future-you would benefit from knowing. Examples worth amending:

A workaround for a CLI surface that silently drops or misorders a flag.
An undocumented endpoint shape (response wrapped in {meta, results}, payload nested two levels deeper than the docs claim).
Observed schema drift (a field renamed, an index that shifted between seasons, a category label that the API now returns lower-cased).

What does NOT belong in notes:

The year-specific or entity-specific answer to the user's question. That's the response, not a learning.
Per-team / per-athlete / per-row data the playbook already retrieves at runtime.
Statements that paraphrase what the existing notes already say.

The amend command appends to the family's existing notes with a timestamped marker ([amend YYYY-MM-DDTHH:MMZ]: <text>). Multiple amends accumulate; the audit trail is visible. If no playbook exists yet for the family, amend creates a notes-only one (so cold-start corrections still land).

PII discipline for amend notes

playbook amend notes are designed to potentially flow upstream as shared knowledge in future versions of the Printing Press. Keep them clean of user-identifying content so the upstream-contribution path stays open without retroactive scrubbing:

Do NOT embed paths to user filesystems, personal API keys or tokens, user email addresses, user GitHub handles, or specific query histories tied to a single user.
Acceptable: endpoint shapes, undocumented field names, API gotchas, observed schema drift, workarounds for CLI surfaces, generalizable pagination or retry tactics.

If a correction is only meaningful with user-specific context, it belongs in a personal note, not in the playbook amend.

Measuring the loop

connectsecure-cli learnings stats reports recall hit rate, teach-to-reuse, playbook resolution rate, and candidate confirm/reject counts from the local learn_events table. Rates are null until they have a denominator; everything stays on this machine. Use it to check whether the loop is earning its keep for this CLI.

Disabling learning

--no-learn on a single command short-circuits both recall and the teach write path. Use for deterministic agent flows or tests that must not be affected by accumulated learnings.
CONNECTSECURE_NO_LEARN=true in the environment globally disables the pipeline.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

connectsecure-cli feedback "the --since flag is inclusive but docs say exclusive"
connectsecure-cli feedback --stdin < notes.txt
connectsecure-cli feedback list --json --limit 10

Entries are stored locally as feedback.jsonl under the resolved data dir. They are never POSTed unless CONNECTSECURE_FEEDBACK_ENDPOINT is set AND either --send is passed or CONNECTSECURE_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename). Binary-response commands write decoded payload bytes (not the base64 JSON envelope) and print a small JSON receipt on stdout; `--json`/`--csv` do not refuse when this sink is set.
`webhook:<url>`	POST the output body to the URL (`application/json`)

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled or recurring agent reuses the same saved flags while providing different input each run.

connectsecure-cli profile save briefing --json
connectsecure-cli --profile briefing companies list
connectsecure-cli profile list --json
connectsecure-cli profile show briefing
connectsecure-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Async Jobs

Four read-only views poll for a job to finish: jobs-view list, report-jobs-view list, report-queries job-details and report-queries job-details-view. They accept --wait (block until the job reaches a terminal status), --wait-timeout (default 10m, 0 means no timeout) and --wait-interval (default 2s, backing off to 30s). When --wait times out the command exits 8 and prints a recovery command; run it instead of re-running the job.

Exit Codes

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
6	Partial failure
7	Rate limited (wait and retry)
8	Async job submitted but not finished (run the printed recovery command; do not resubmit)
10	Config error

Argument Parsing

Parse $ARGUMENTS:

Empty, help, or --help → show connectsecure-cli --help output
Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

Install the MCP binary (run the install script from the Prerequisites section, or see mcp-install.md for per-agent wire-up).

claude mcp add connectsecure-mcp \
  --env CONNECTSECURE_BASE_URL=https://pod106.myconnectsecure.com \
  --env CONNECTSECURE_TENANT=<portal-login-tenant> \
  --env CONNECTSECURE_CLIENT_ID=<api-client-id> \
  --env CONNECTSECURE_CLIENT_SECRET=<api-client-secret> \
  -- connectsecure-mcp

Verify: claude mcp list

Direct Use

Check if installed: which connectsecure-cli If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the --agent flag:

connectsecure-cli exposure --min-epss 0.5 --severity Critical,High --agent

If ambiguous, drill into subcommand help, for example connectsecure-cli report-queries --help.