Skip to content

CLI Reference

This page documents the current ms-teams-agent CLI.

Terminal window
ms-teams-agent <command> [options]
OptionDescription
--versionPrint the agent version and exit.
CommandDescription
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.
Terminal window
ms-teams-agent run --config <FILE> [options]
OptionDescription
--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.

Terminal window
ms-teams-agent validate --config <FILE> [--skip-secrets]
OptionDescription
--configRequired. Path to YAML config file.
--skip-secretsOptional. Validate schema and non-secret values without resolving ${env:...} / ${file:...} secret references.
Terminal window
ms-teams-agent migrate-config [options]
OptionDescription
--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.
Terminal window
ms-teams-agent test-connection --config <FILE> [options]
OptionDescription
--configRequired. Path to YAML config file.
--log-levelOptional. One of DEBUG, INFO, WARNING, ERROR.
Terminal window
ms-teams-agent service <action> [options]

Actions:

  • install
  • install-config
  • enable
  • restart
  • status
  • disable
  • remove
  • provision
  • enable-service
  • disable-service

Options:

OptionDescription
--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.
Terminal window
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:

OptionDescription
--state-filePath to state DB. Defaults to state.db.
Terminal window
ms-teams-agent state export [options]
OptionDescription
--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.
Terminal window
ms-teams-agent state migrate-v1 --source <FILE> [options]
OptionDescription
--source, -sRequired. Path to v1 JSON state file.
--overwriteOverwrite existing entries in v2 state DB.
--force, -fSkip interactive confirmation prompt.
Terminal window
# Validate configuration
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