Using the CLI

Practical guide to the most-used ms-teams-agent commands for Standalone operations. For complete flags and subcommands, see CLI Reference.

Command Shape

ms-teams-agent <command> [options]

Command	Purpose
run	Start collection and export
validate	Validate config and exit
migrate-config	Migrate a legacy YAML config file to the current schema
test-connection	Test Microsoft auth and backend connectivity
service	Manage Linux systemd service
state	Inspect, export, reset, or migrate state

Validation Commands

Run these before starting collection in production:

# Validate YAML syntax and schema
ms-teams-agent validate --config ./config.yaml

# Validate config + test Microsoft Graph auth + test all exporters
ms-teams-agent test-connection --config ./config.yaml

Config Migration Command

Use this command to rewrite a legacy YAML config file in place using the current schema.

# Interactive mode (prompts for path and backup choice)
ms-teams-agent migrate-config

# Provide file path explicitly
ms-teams-agent migrate-config --path ./config.yaml

# Non-interactive mode for CI/automation (overwrite without backup)
ms-teams-agent migrate-config --path ./config.yaml --no-backup

Options:

• --path: path to the YAML config file to migrate.
• --backup: write a <path>.bak backup before overwriting.
• --no-backup: overwrite without writing a backup.
• If --path and/or backup choice are omitted, the CLI prompts interactively.

Running the Collector

# Continuous collection (main operation)
ms-teams-agent run --config ./config.yaml

# Test pipeline without exporting to backends
ms-teams-agent run --config ./config.yaml --dry-run

# Debug a specific call
ms-teams-agent run --config ./config.yaml --call-id <CALL_ID> --log-level DEBUG

# Run a cycle without existing state
ms-teams-agent run --config ./config.yaml --ignore-state

# Override state database path
ms-teams-agent run --config ./config.yaml --state-file ./state/state.db

Service Management (Linux)

Most service actions require sudo.

# Install and start as a systemd service
sudo ms-teams-agent service enable-service --config /absolute/path/config.yaml

# Check service status (default instance)
sudo ms-teams-agent service status

# Check a named instance
sudo ms-teams-agent service status --instance prod

# Restart a service instance
sudo ms-teams-agent service restart --instance default

# Update config for a running instance (restart only if already active)
sudo ms-teams-agent service install-config \
  --config /etc/config.prod.yaml \
  --instance prod \
  --service-restart-if-active

# Remove a service instance
sudo ms-teams-agent service disable-service --instance default

Available service actions are: install, install-config, enable, restart, status, disable, remove, provision, enable-service, disable-service.

See Service Management for lifecycle procedures and rollout-safe updates.

State Operations

The collector uses a local SQLite state database to track processed objects and deduplication.

# Show current state (safe while service is active)
ms-teams-agent state show

# Export state snapshot to JSON
ms-teams-agent state export --output state-snapshot.json

# Export selected object types with filters
ms-teams-agent state export \
  --include-objects \
  --type calls_collection \
  --since 2026-03-28 \
  --limit 200 \
  --output state-detailed.json

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

# Purge stale pending messages in logs category only
ms-teams-agent state purge-stale --older-than 72 --category logs

# Reset state (forces full re-collection on next run)
ms-teams-agent state reset

Temporary Migration Command

Use this only during v1 to Standalone migration:

ms-teams-agent state migrate-v1 --source ./state-v1.json

# Non-interactive migration for CI/automation
ms-teams-agent state migrate-v1 --source ./state-v1.json --overwrite --force

Recommended Operational Workflow

# 1. Validate config
ms-teams-agent validate --config ./config.yaml

# 2. Test connectivity
ms-teams-agent test-connection --config ./config.yaml

# 3. Start collection
ms-teams-agent run --config ./config.yaml