CLI Reference

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

Command Shape

ms-teams-agent <command> [options]

Global Options

Option	Description
--version	Print the agent version and exit.

Commands

Command	Description
run	Collect and export Teams call data.
validate	Validate a YAML config file and exit.
migrate-config	Rewrite a legacy YAML config file to the current schema.
test-connection	Validate Microsoft Graph auth and exporter connectivity.
service	Manage Linux systemd service instances.
state	Inspect, export, reset, or migrate collector state.

run

ms-teams-agent run --config <FILE> [options]

Option	Description
--config	Required. Path to YAML config file.
--log-level	Optional. One of DEBUG, INFO, WARNING, ERROR.
--call-id	Optional. Process a specific call ID.
--ignore-state	Optional. Ignore existing state file.
--state-file	Optional. Override state DB path.
--dry-run	Optional. Run collection without exporting to backends.

validate

ms-teams-agent validate --config <FILE>

Option	Description
--config	Required. Path to YAML config file.

migrate-config

ms-teams-agent migrate-config [options]

Option	Description
--path	Optional. Path to YAML config file to migrate. If omitted, CLI prompts for it.
--backup	Optional. Write a <path>.bak copy before overwrite.
--no-backup	Optional. 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.

test-connection

ms-teams-agent test-connection --config <FILE> [options]

Option	Description
--config	Required. Path to YAML config file.
--log-level	Optional. One of DEBUG, INFO, WARNING, ERROR.

service

ms-teams-agent service <action> [options]

Actions:

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

Options:

Option	Description
--config	Path to YAML config file. Required for enable-service, provision, and install-config. Not required for install.
--instance	Service instance name (for example prod).
--force-service-creation, --force-unit	Force overwrite of existing service unit template. Valid only with enable-service, install, or provision.
--service-restart-if-active	For install-config only. Restart instance if already active.

state

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.
• purge-stale: move stale pending outbox messages to dead-letter.
• migrate-v1: import legacy v1 JSON state into v2 SQLite state.

Common option:

Option	Description
--state-file	Path to state DB. Defaults to state.db.

state export

ms-teams-agent state export [options]

Option	Description
--output, -o	Write JSON to file instead of stdout.
--include-objects	Include processed object IDs and metadata (can be large).
--type	Filter by object type. Repeatable.
--since	Include types processed on/after ISO-8601 datetime.
--until	Include types processed on/before ISO-8601 datetime.
--limit	Max objects per type, most recent first. Effective only with --include-objects.

state purge-stale

ms-teams-agent state purge-stale --older-than <HOURS> [options]

Option	Description
--older-than	Required. Positive number of hours used as the stale threshold.
--category	Optional. Limit to logs or errors (default: both).
--dry-run	Optional. Show how many rows would be purged without modifying the DB.

state migrate-v1

ms-teams-agent state migrate-v1 --source <FILE> [options]

Option	Description
--source, -s	Required. Path to v1 JSON state file.
--overwrite	Overwrite existing entries in v2 state DB.
--force, -f	Skip interactive confirmation prompt.

Practical Examples

# 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

# Dry-run stale pending outbox cleanup (7 days)
ms-teams-agent state purge-stale --older-than 168 --dry-run

# Purge stale pending error rows only
ms-teams-agent state purge-stale --older-than 72 --category errors