convert

opnDossier convert¶

Convert OPNsense configuration files to structured formats.

Synopsis¶

The 'convert' command processes one or more OPNsense config.xml files and transforms them into structured documentation and export formats. Use convert when you need a human-readable report or a machine-readable export — not when you need compliance analysis or structural validation.

OUTPUT FORMATS: Select the output encoding with --format:

markdown  - Rendered markdown report (default)
json      - JSON export for programmatic access
yaml      - YAML export for configuration management
text      - Plain text (markdown without ANSI formatting)
html      - Self-contained HTML report

CONTENT OPTIONS: --comprehensive - Emit every section, including rarely used ones --include-tunables - Include all system tunables (default suppresses defaults) --section - Restrict output to specific sections (e.g. system,firewall) --wrap / --no-wrap - Control text wrapping for terminal rendering --redact - Redact passwords, SNMP community strings, private keys

OUTPUT DESTINATION: By default, output is printed to stdout. Use --output/-o to save to a file. When processing multiple input files, --output is ignored and each output file is auto-named after the input (config.xml -> config.md, config.json, ...). Use --force to overwrite existing files without prompting.

RELATED: audit - Convert plus compliance checks (STIG/SANS/firewall) display - Convert then render to the terminal in one step validate - Validate config.xml before conversion sanitize - Redact a config.xml before distribution

opnDossier convert [file ...] [flags]

Examples¶

  # Convert configuration to markdown (default)
  opnDossier convert my_config.xml

  # Convert to JSON format
  opnDossier convert my_config.xml --format json

  # Convert to YAML and save to a file
  opnDossier convert my_config.xml -f yaml -o documentation.yaml

  # Convert to self-contained HTML
  opnDossier convert my_config.xml --format html -o report.html

  # Generate a comprehensive report
  opnDossier convert my_config.xml --comprehensive

  # Convert only specific sections
  opnDossier convert my_config.xml --section system,network

  # Convert multiple files to JSON (each output auto-named)
  opnDossier convert config1.xml config2.xml --format json

  # Redact sensitive fields (passwords, SNMP community strings, private keys)
  opnDossier convert config.xml --format json --redact

  # Validate then convert (recommended workflow)
  opnDossier validate config.xml && opnDossier convert config.xml -f json -o output.json

Options¶

  -o, --output string      Output file path for saving converted configuration (default: print to console)
  -f, --format string      Output format for conversion (markdown, json, yaml, text, html) (default "markdown")
      --force              Force overwrite existing files without prompting for confirmation
      --include-tunables   Include all system tunables in report output (markdown, text, HTML only; JSON/YAML always include all tunables)
      --section strings    Specific sections to include in output (comma-separated, e.g., system,network,firewall)
      --wrap int           Text wrap width in characters (-1 = auto-detect terminal width, 0 = no wrapping, recommended: 80-120) (default -1)
      --no-wrap            Disable text wrapping (alias for --wrap 0)
      --comprehensive      Generate comprehensive detailed reports with full configuration analysis
      --redact             Redact sensitive fields (passwords, keys, community strings) in output
  -h, --help               help for convert

Options inherited from parent commands¶

      --color string         Color output mode (auto, always, never) (default "auto")
      --config string        Configuration file path (default: $HOME/.opnDossier.yaml)
      --debug                Enable debug-level logging (all messages, for troubleshooting)
      --device-type string   Force device type (supported: opnsense, pfsense). Bypasses auto-detection.
      --minimal              Minimal output mode (suppresses progress and verbose messages)
      --no-progress          Disable progress indicators
  -q, --quiet                Suppress all output except errors and critical messages
      --timestamps           Include timestamps in log output
  -v, --verbose              Enable info-level logging (warnings, errors, and informational messages)