This page documents the current ms-teams-agent CLI.
ms-teams-agent <command> [options]
Option Description --versionPrint the agent version and exit.
Command Description runCollect and export Teams call data. validateValidate a YAML config file and exit. migrate-configRewrite a legacy YAML config file to the current schema. test-connectionValidate Microsoft Graph auth and exporter connectivity. serviceManage Linux systemd service instances. stateInspect, export, reset, or migrate collector state.
ms-teams-agent run --config <FILE> [options]
Option Description --configRequired. Path to YAML config file. --log-levelOptional. One of DEBUG, INFO, WARNING, ERROR. --call-idOptional. Process a specific call ID. --ignore-stateOptional. Ignore existing state file. --state-fileOptional. Override state DB path. --dry-runOptional. Run collection without exporting to backends and without persisting collection state.
--dry-run reads the existing state database through an in-memory snapshot: the file
is never created, rewritten, migrated or vacuumed, no configuration migration is written
back, and nothing is sent to exporters, collection health or telemetry. Local operational
logs are still written. If an existing state database cannot be read, the run aborts
instead of continuing with empty state.
ms-teams-agent validate --config <FILE> [--skip-secrets]
Option Description --configRequired. Path to YAML config file. --skip-secretsOptional. Validate schema and non-secret values without resolving ${env:...} / ${file:...} secret references.
ms-teams-agent migrate-config [options]
Option Description --pathOptional. Path to YAML config file to migrate. If omitted, CLI prompts for it. --backupOptional. Write a <path>.bak copy before overwrite. --no-backupOptional. Overwrite without writing a backup.
Notes:
If --path is omitted, the command runs in interactive mode and asks for a path.
If neither --backup nor --no-backup is provided, the command asks interactively whether to create a backup.
ms-teams-agent test-connection --config <FILE> [options]
Option Description --configRequired. Path to YAML config file. --log-levelOptional. One of DEBUG, INFO, WARNING, ERROR.
ms-teams-agent service <action> [options]
Actions:
install
install-config
enable
restart
status
disable
remove
provision
enable-service
disable-service
Options:
Option Description --configPath to YAML config file. Required for enable-service, provision, and install-config. Not required for install. --instanceService instance name (for example prod). --force-service-creation, --force-unitForce overwrite of existing service unit template. Valid only with enable-service, install, or provision. --service-restart-if-activeFor install-config only. Restart instance if already active.
ms-teams-agent state [--state-file <FILE>] <action> [options]
Actions:
show: display current state entries.
reset: clear all state (timestamps and dedup cache).
export: export state as JSON.
vacuum: reclaim free space in the state database (SQLite VACUUM).
migrate-v1: import legacy v1 JSON state into v2 SQLite state.
Common option:
Option Description --state-filePath to state DB. Defaults to state.db.
ms-teams-agent state export [options]
Option Description --output, -oWrite JSON to file instead of stdout. --include-objectsInclude processed object IDs and metadata (can be large). --typeFilter by object type. Repeatable. --sinceInclude types processed on/after ISO-8601 datetime. --untilInclude types processed on/before ISO-8601 datetime. --limitMax objects per type, most recent first. Effective only with --include-objects.
ms-teams-agent state migrate-v1 --source <FILE> [options]
Option Description --source, -sRequired. Path to v1 JSON state file. --overwriteOverwrite existing entries in v2 state DB. --force, -fSkip interactive confirmation prompt.
ms-teams-agent validate --config ./config.yaml
# Connectivity test before production rollout
ms-teams-agent test-connection --config ./config.yaml
# Run collector in dry-run mode
ms-teams-agent run --config ./config.yaml --dry-run
# Migrate legacy config format (non-interactive CI mode)
ms-teams-agent migrate-config --path ./config.yaml --no-backup
# Enable service instance
sudo ms-teams-agent service enable-service --config /etc/ms-teams-observability-agent/prod.yaml --instance prod
# Export detailed state snapshot
ms-teams-agent state export --include-objects --type calls_collection --since 2026-03-28 --output ./state.json
# Reclaim free space in the state database
ms-teams-agent state vacuum