How trevonix/trxo works
1. What this repo is
TRXO is a Python CLI for managing Ping configurations across PingOne Advanced Identity Cloud, PingAM, and PingIDM. Its core job is to move configuration objects between environments, compare them, store them locally or in Git, and safely apply changes.
2. Primary entrypoint and command surface
src/trxo/main.py is the runtime entrypoint. The CLI is organized into command groups under src/trxo/commands/: export, imports, batch, config, logs, and project. This gives the tool a clear top-level flow: authenticate, choose an operation, then delegate to a specialized command handler.
3. Authentication boundary
Auth is split by environment type in src/trxo/auth/:
- service_account.py for PingOne Advanced Identity Cloud
- on_premise.py for PingAM/PingIDM
- token_manager.py for token lifecycle handling
The command layer uses a shared auth manager, so authentication is centralized rather than duplicated across commands.
4. Export pipeline
Export logic lives under src/trxo/commands/export/ with one module per configuration domain: realms, applications, OAuth, SAML, connectors, policies, managed objects, themes, scripts, webhooks, and more. These modules likely collect data from Ping APIs and normalize it into files or versioned artifacts through shared base/export manager classes.
5. Import pipeline
Import logic mirrors export under src/trxo/commands/imports/. The symmetry suggests a two-way configuration migration model: export from a source, then import into a target. Shared utilities such as component_mapper, file_loader, sync_handler, and cherry_pick_filter indicate support for selective imports, dependency handling, and sync mode.
6. Storage modes and Git-backed workflow
A major architectural boundary is storage. TRXO can persist exported configuration either to the local filesystem or to a Git repository. The Git-specific path is handled in src/trxo/utils/git/ with repository, branch, credential, and operation helpers, while src/trxo/utils/export/ contains file saving, metadata building, versioning context, and rendering. This is the foundation for auditability, diffing, and rollback.
7. Diff and change-preview subsystem
The diff stack in src/trxo/utils/diff/ supports “preview before import.” data_fetcher, diff_engine, diff_manager, diff_reporter, and insights_generator work together to compare current and desired state and produce human-readable change summaries. This is a key safety boundary between read-only comparison and mutation.
8. Batch and automation flow
src/trxo/commands/batch/ supports large-scale operations, likely for realm-wide or multi-object migration. The presence of a config generator and batch manager shows this repo is built not just for interactive CLI use, but also for repeatable pipeline-style execution in CI/CD or scripted migrations.
9. Configuration and validation
src/trxo/commands/config/ manages tool setup, auth configuration, and validation. This layer separates user/environment settings from operational commands, which helps keep auth, storage, and runtime options consistent across exports/imports.
10. Safety, rollback, and deletion handling
TRXO includes explicit safeguards in utility code such as rollback_manager, deletion_manager, and hash-based tracking. Together with Git storage and diff previews, these form the tool’s “safe deployment” boundary: detect what will change, apply selectively, and recover when needed.
11. Logging and observability
src/trxo/logging/ provides structured logging, formatting, utilities, and masking of sensitive values. The README and logs command indicate logging is a first-class operational feature, used for tracing API activity and troubleshooting without exposing secrets.
12. Important external dependencies and runtime context
The system is a Python package (pyproject.toml) with MkDocs documentation and GitHub Actions workflows for CI, docs deployment, and releases. The main external systems it interacts with are Ping configuration APIs and Git repositories; those are the two dominant integration boundaries in the architecture.
13. How the main data flow works
Typical flow: authenticate to a Ping environment, export configuration objects through resource-specific modules, normalize and store them locally or in Git, optionally diff source vs target, then import selected changes into the destination with rollback and sync/cherry-pick controls. The repo is structured around that end-to-end migration lifecycle rather than around a single isolated command.
Main entry points: main.py Main CLI · auth_manager.py Auth manager · manager.py Import flow · shared Shared CLI
Components 20
CLI surface
Entry points, command dispatch, and user-facing operations.
- Main CLI · Runtime entrypoint that boots the command-line interface.
src/trxo/main.py - Shared CLI · Common command base, auth wiring, and CLI option handling.
src/trxo/commands/shared - Config cmd · Tool setup, auth configuration, and validation commands.
src/trxo/commands/config - Logs cmd · User-facing logging and log inspection command surface.
src/trxo/commands/logs.py - Project cmd · Project-level command surface for repo/workspace operations.
src/trxo/commands/project.py
Migration pipelines
Export, import, batch, and diff flows for Ping configuration movement.
- Export flow · Coordinates resource-specific export handlers.
src/trxo/commands/export/manager.py - Export domains · Per-domain exporters for realms, apps, OAuth, SAML, policies, scripts, themes, and more.
src/trxo/commands/export - Import flow · Coordinates resource-specific import handlers.
src/trxo/commands/imports/manager.py - Import domains · Per-domain importers mirroring the export side.
src/trxo/commands/imports - Batch ops · Batch export/import and config generation for repeatable migration runs.
src/trxo/commands/batch - Diff engine · Fetches data, computes diffs, and generates change summaries before import.
src/trxo/utils/diff
Support systems
Authentication, storage, Git, logging, and shared utilities.
- Auth layer · Service-account and on-premise authentication with token lifecycle handling.
src/trxo/auth - Auth manager · Shared authentication coordination used by commands.
src/trxo/commands/shared/auth_manager.py - Export storage · Stores exported configuration locally or through Git-backed workflows.
src/trxo/utils/export - Git utils · Repository, branch, credential, and operation helpers for Git-backed exports.
src/trxo/utils/git - Import utils · Component mapping, file loading, cherry-pick filtering, and sync handling.
src/trxo/utils/imports - Safety ops · Rollback, deletion, and hash tracking for controlled changes.
src/trxo/utils - Logging · Structured logging, formatting, and secret masking.
src/trxo/logging - Config store · Persistent tool settings and configuration state.
src/trxo/utils/config_store.py - API config · Shared Ping API header and request configuration.
src/trxo/config/api_headers.py
Connections 22
- Main CLI → Shared CLI: dispatches · Main CLI routes commands through the shared command layer.
- Main CLI → Config cmd: exposes · CLI exposes setup and validation commands.
- Main CLI → Logs cmd: exposes · CLI exposes logging-related commands.
- Main CLI → Project cmd: exposes · CLI exposes project-level commands.
- Shared CLI → Auth manager: uses · Shared command layer centralizes authentication handling.
- Shared CLI → Config store: reads/writes · Shared command layer relies on stored runtime settings.
- Config cmd → Auth manager: configures · Config commands set up and validate authentication.
- Auth manager → Auth layer: delegates to · Authentication manager delegates to environment-specific auth implementations.
- Export flow → Export domains: orchestrates · Export manager coordinates per-domain exporters.
- Import flow → Import domains: orchestrates · Import manager coordinates per-domain importers.
- Export domains → Auth manager: requires · Exports need authenticated API access.
- Import domains → Auth manager: requires · Imports need authenticated API access.
- Export domains → Export storage: persists to · Exported artifacts are written to local or Git-backed storage.
- Export storage → Git utils: optionally uses · Git-backed storage delegates repository operations to Git helpers.
- Import flow → Import utils: uses · Import orchestration depends on mapping, loading, and sync helpers.
- Import flow → Diff engine: previews changes · Import flow uses diffing to preview intended changes.
- Diff engine → Export storage: compares against · Diffing compares desired artifacts against stored state.
- Diff engine → Safety ops: informs · Diff results feed rollback and deletion safeguards.
- Batch ops → Export flow: runs · Batch export wraps the export orchestration.
- Batch ops → Import flow: runs · Batch import wraps the import orchestration.
- Logging → Main CLI: supports · Logging is a cross-cutting runtime concern for the CLI.
- API config → Auth layer: supports · API headers and request settings support authenticated Ping calls.