Skip to content

Command Line

Jump to bottom
Jeffrie Budde edited this page Apr 10, 2026 · 1 revision

Command-line usage

The CLI is powered by Typer and provides commands for managing migrations, credentials, databases, and telemetry. All commands support --verbose / -v for detailed debug logging with Rich formatting.

Entry point

The tool is installed as onelogin-migration:

onelogin-migration --help

Alternatively, you can use:

onelogin-migration-cli --help

Or run it as a Python module:

python -m onelogin_migration_cli.app --help

Commands overview

Command Purpose
plan Export from source provider (read-only, safe)
provision-attributes Pre-create custom attributes in OneLogin
show-config Display sanitized configuration for troubleshooting
migrate Execute full migration workflow
credentials Manage secure credentials (v0.2.0+)
db Manage application connector database
telemetry View migration analytics and statistics

plan - Export and preview

Exports users, groups, memberships, and applications from the configured source provider without touching OneLogin. Safe to run repeatedly — no writes to OneLogin.

onelogin-migration plan --config config/migration.yaml -v

Options:

  • --config PATH (required) - Path to YAML configuration file
  • --output PATH (optional) - Save export to custom location
  • -v, --verbose - Enable debug logging and per-category snapshots

Output:

  • source_export.json — Complete export with all categories
  • Per-category snapshots: {provider}_{category}_{timestamp}.json

Example:

# Basic export
onelogin-migration plan --config config/migration.yaml

# With custom output path and verbose logging
onelogin-migration plan --config config/migration.yaml \
  --output /tmp/source_export.json -v

migrate - Execute migration

Runs the complete migration workflow with safety controls and resume capability.

onelogin-migration migrate --config config/migration.yaml

Options:

  • --config PATH (required) - Path to YAML configuration
  • --export PATH (optional) - Use pre-generated source export (skips the export phase)
  • --dry-run - Simulate without writing to OneLogin
  • --bulk-user-upload - Generate CSV instead of API calls
  • -v, --verbose - Enable debug logging

What it does:

  1. Exports from source provider (if not provided via --export)
  2. Provisions custom attributes in OneLogin
  3. Creates roles (groups), users, and applications
  4. Assigns users to roles and roles to apps
  5. Persists state for resume capability

Examples:

# Standard migration with dry-run
onelogin-migration migrate --config config/migration.yaml --dry-run

# Production migration with verbose logging
onelogin-migration migrate --config config/migration.yaml -v

# Generate CSV for bulk upload
onelogin-migration migrate --config config/migration.yaml \
  --bulk-user-upload

# Use pre-generated export
onelogin-migration migrate --config config/migration.yaml \
  --export artifacts/source_export.json

provision-attributes - Pre-create custom attributes

Discovers custom attributes from source user profiles and creates them in OneLogin before migration. Run this before migrate to avoid validation errors.

onelogin-migration provision-attributes --config config/migration.yaml

Options:

  • --config PATH (required) - Path to YAML configuration
  • --export PATH (optional) - Use pre-generated source export
  • --dry-run - Preview attributes without creating them
  • -v, --verbose - Show detailed attribute analysis

Examples:

# Preview what attributes would be created
onelogin-migration provision-attributes --config config/migration.yaml --dry-run

# Create attributes in OneLogin
onelogin-migration provision-attributes --config config/migration.yaml

# Use existing export to avoid re-fetching
onelogin-migration provision-attributes --config config/migration.yaml \
  --export artifacts/source_export.json

show-config - Display configuration

Displays the parsed configuration with secrets redacted. Useful for troubleshooting config issues without exposing credentials.

onelogin-migration show-config --config config/migration.yaml

Output is JSON with all secret fields masked — safe to share in bug reports.

db - Database management

Manage the application connector database for OneLogin connector ID mappings.

onelogin-migration db --help

Subcommands

db init - Initialize database

onelogin-migration db init

Creates the connector database with schema and initial data.

db refresh - Update from OneLogin API

onelogin-migration db refresh --config config/migration.yaml

Fetches latest connector information from OneLogin API and updates the database.

db search - Find connector IDs

# Search by application name
onelogin-migration db search --name "Slack"

# Search by protocol
onelogin-migration db search --protocol saml

db stats - Database statistics

onelogin-migration db stats

Shows database statistics including connector counts and categories.

telemetry - Migration analytics

View migration statistics and analytics.

onelogin-migration telemetry --help

Subcommands

telemetry stats - Migration statistics

onelogin-migration telemetry stats

Shows migration success rates, error counts, and performance metrics.

telemetry events - Event history

onelogin-migration telemetry events --limit 50

Displays recent migration events.

telemetry export - Export analytics

onelogin-migration telemetry export --output analytics.csv

Exports telemetry data to CSV format.

Common patterns

Safe exploration:

# 1. Test export
onelogin-migration plan --config config/migration.yaml -v

# 2. Dry-run migration
onelogin-migration migrate --config config/migration.yaml --dry-run

Production workflow:

# 1. Export from source provider
onelogin-migration plan --config config/migration.yaml \
  --output source_export.json

# 2. Pre-create custom attributes
onelogin-migration provision-attributes --config config/migration.yaml \
  --export source_export.json

# 3. Run migration
onelogin-migration migrate --config config/migration.yaml \
  --export source_export.json -v

credentials - Secure credential management

Manage credentials with system keyring integration (v0.2.0+).

onelogin-migration credentials --help

Subcommands

credentials set - Store credentials

# Interactive prompt (recommended for sensitive data)
onelogin-migration credentials set okta token

# Provide value directly
onelogin-migration credentials set okta domain --value "company.okta.com"

# Store in encrypted vault
onelogin-migration credentials set okta token \
  --backend vault --vault-password "mypassword"

credentials get - Retrieve credentials

# Show masked value
onelogin-migration credentials get okta token

# Reveal full value
onelogin-migration credentials get okta token --reveal

credentials list - List all stored credentials

# List all credentials
onelogin-migration credentials list

# Filter by backend
onelogin-migration credentials list --backend keyring

# Show masked values
onelogin-migration credentials list --show-values

credentials delete - Remove credentials

# Delete with confirmation
onelogin-migration credentials delete okta token

# Force delete without confirmation
onelogin-migration credentials delete okta token --force

credentials test - Validate authentication

# Test Okta credentials
onelogin-migration credentials test okta

# Test OneLogin credentials
onelogin-migration credentials test onelogin

credentials migrate - Migrate from YAML

# Migrate credentials from YAML config
onelogin-migration credentials migrate config/migration.yaml

# Migrate to encrypted vault
onelogin-migration credentials migrate config/migration.yaml \
  --backend vault --vault-password "mypassword"

# Skip backup creation
onelogin-migration credentials migrate config/migration.yaml --no-backup

credentials audit - View access logs

# Show last 20 events
onelogin-migration credentials audit

# Show last 50 events
onelogin-migration credentials audit --limit 50

# Filter by event type
onelogin-migration credentials audit --type credential_stored

credentials validate - Check config sanitization

# Validate config has no plaintext credentials
onelogin-migration credentials validate config/migration.yaml

credentials export - Backup vault

# Export encrypted vault
onelogin-migration credentials export backup/vault-2024-01-15.enc

credentials import - Restore vault

# Import vault from backup
onelogin-migration credentials import backup/vault-2024-01-15.enc

Credential management workflow

Initial setup:

# 1. Store credentials securely (service name = provider key from config)
onelogin-migration credentials set source token
onelogin-migration credentials set source domain --value "company.okta.com"
onelogin-migration credentials set onelogin client_id --value "abc123"
onelogin-migration credentials set onelogin client_secret
onelogin-migration credentials set onelogin region --value "us"

# 2. Test authentication
onelogin-migration credentials test source
onelogin-migration credentials test onelogin

# 3. List stored credentials
onelogin-migration credentials list

Migrating from YAML:

# 1. Migrate credentials from existing config
onelogin-migration credentials migrate config/migration.yaml

# 2. Verify migration
onelogin-migration credentials list
onelogin-migration credentials validate config/migration.yaml

# 3. Test credentials
onelogin-migration credentials test okta
onelogin-migration credentials test onelogin

# 4. Delete old YAML file (after verification)
rm config/migration.yaml.bak

Logging

All commands use Rich for formatted console output:

  • INFO - Progress updates and summaries
  • DEBUG (-v flag) - API requests, field mappings, detailed operations
  • WARNING - Skipped items, recoverable errors
  • ERROR - Failures with HTTP status, URL, and response details

Clone this wiki locally