1. Purpose

This page provides a complete reference for all Canon command-line interface options organized by command and function.

For conceptual understanding, see Comparison Pipeline.

For choosing the right configuration, see Choosing Configuration.

2. Command syntax 

canon <command> [arguments] [options]

3. Commands

3.1. format command

Format a document using canonicalization rules.

canon format FILE [OPTIONS]

Options:

Option Description

--format FORMAT

Specify format: xml, html, json, yaml

--output FILE

Write output to file (default: stdout)

--preprocessing MODE

Apply preprocessing: none, c14n, normalize, format

3.2. diff command

Compare two documents and show differences.

canon diff FILE1 FILE2 [OPTIONS]

This command supports all 4 layers of Canon’s architecture. See sections below for layer-specific options.

4. Layer 1: Preprocessing options

Controls document normalization before comparison.

Option Description

--preprocessing MODE

Preprocessing mode: none (default), c14n, normalize, format

Modes: * none - No preprocessing (compare as-is) * c14n - Canonicalize (XML C14N, JSON/YAML sorted keys) * normalize - Normalize whitespace throughout * format - Pretty-print with standard formatting

See Preprocessing for details.

5. Layer 2: Algorithm options

Controls which comparison algorithm to use.

Option Description

--diff-algorithm ALGORITHM

Algorithm: dom (default), semantic

Algorithms: * dom - Fast, stable, positional comparison * semantic - Slower, intelligent, detects moves

See Algorithms for details.

6. Layer 3: Match options

Controls what to compare and how strictly.

6.1. Match profiles

Option Description

--match-profile PROFILE

Profile: strict, rendered, spec_friendly, content_only

Profiles: * strict - Exact matching (all dimensions strict) * rendered - Browser rendering (ignores formatting) * spec_friendly - Test-friendly (most common) * content_only - Maximum tolerance

6.2. Match dimensions

Individual dimension control (overrides profile settings):

Option Description

--text-content BEHAVIOR

Text content: strict, normalize, ignore

--structural-whitespace BEHAVIOR

Structural whitespace: strict, normalize, ignore

--attribute-whitespace BEHAVIOR

Attribute whitespace (XML/HTML): strict, normalize, ignore

--attribute-order BEHAVIOR

Attribute order (XML/HTML): strict, ignore

--attribute-values BEHAVIOR

Attribute values (XML/HTML): strict, normalize, ignore

--key-order BEHAVIOR

Key order (JSON/YAML): strict, ignore

--comments BEHAVIOR

Comments: strict, normalize, ignore

--whitespace-type BEHAVIOR

Whitespace type sensitivity: strict (default), normalize

See Match Options for details.

7. Layer 4: Diff formatting options

Controls how differences are displayed.

7.1. Diff mode

Option Description

--diff-mode MODE

Mode: by_line (default for HTML), by_object (default for XML/JSON/YAML)

Modes: * by_line - Traditional line-by-line diff * by_object - Tree-based semantic diff

7.2. Display options

Option Description

--verbose, -v

Show configuration tables and detailed information (diffs always shown when files differ)

--color, --no-color

Enable/disable colored output (default: enabled)

--context-lines N

Lines of context around changes (default: 3)

--diff-grouping-lines N

Group changes within N lines (default: nil)

--show-legend

Display legend for symbols (default: true with verbose)

--show-diffs MODE

Filter displayed differences: all (default), normative, informative

See Diff Formatting for details.

8. Format specification options

Option Description

--format FORMAT

Format for both files: xml, html, json, yaml

--format1 FORMAT

Format of first file (overrides --format)

--format2 FORMAT

Format of second file (overrides --format)

9. General options

Option Description

--help, -h

Show help message

--version, -V

Show version

--debug

Enable debug output

10. Environment variables

Variable Description

CANON_VERBOSE

Set to 1 to enable detailed option tables in verbose mode

NO_COLOR

Set to disable colored output (overrides --color)

11. Complete examples

11.1. Example 1: Basic comparison 

canon diff file1.xml file2.xml --verbose

Uses all defaults: * Layer 1: No preprocessing * Layer 2: DOM algorithm * Layer 3: Format defaults (XML strict matching) * Layer 4: by_object mode with colors

11.2. Example 2: Test-friendly comparison 

canon diff expected.xml actual.xml \
  --match-profile spec_friendly \
  --verbose

Uses: * Layer 1: Normalize preprocessing (from profile) * Layer 2: DOM algorithm (default) * Layer 3: spec_friendly profile * Layer 4: by_object mode with colors

11.3. Example 3: Semantic analysis 

canon diff old.xml new.xml \
  --diff-algorithm semantic \
  --match-profile spec_friendly \
  --diff-mode by_object \
  --verbose

Uses: * Layer 1: Normalize preprocessing * Layer 2: Semantic algorithm (detects moves) * Layer 3: spec_friendly matching * Layer 4: by_object mode (shows operations)

11.4. Example 4: Exact matching with context 

canon diff file1.json file2.json \
  --match-profile strict \
  --diff-mode by_line \
  --context-lines 5 \
  --verbose

Uses: * Layer 1: No preprocessing * Layer 2: DOM algorithm * Layer 3: strict profile (exact matching) * Layer 4: by_line mode with 5 context lines

11.5. Example 5: Custom dimension control 

canon diff page1.html page2.html \
  --preprocessing normalize \
  --text-content normalize \
  --structural-whitespace ignore \
  --attribute-order ignore \
  --comments ignore \
  --diff-mode by_line \
  --verbose

Uses: * Layer 1: Normalize preprocessing * Layer 2: DOM algorithm * Layer 3: Custom dimensions * Layer 4: by_line mode

11.6. Example 6: With CANON_VERBOSE tables 

CANON_VERBOSE=1 canon diff file1.xml file2.xml \
  --match-profile spec_friendly \
  --verbose

Shows: * CANON VERBOSE option tables (Tier 1) * Semantic Diff Report (Tier 2) * Detailed diff (Tier 3)

12. Configuration patterns

12.1. Fast comparison (default) 

canon diff file1.xml file2.xml

  • Minimal processing

  • Fast DOM algorithm

  • Format defaults

  • No verbose output

12.2. Test scenario 

canon diff expected.xml actual.xml \
  --match-profile spec_friendly \
  --verbose

  • Ignores formatting

  • Shows actionable diffs

  • Most common for testing

12.3. Debugging differences 

CANON_VERBOSE=1 canon diff file1.xml file2.xml \
  --diff-algorithm semantic \
  --diff-mode by_object \
  --verbose

  • Full option tables

  • Semantic analysis

  • Operation-based output

  • Maximum information

12.4. Browser-equivalent HTML 

canon diff page1.html page2.html \
  --match-profile rendered \
  --verbose

  • HTML rendering simulation

  • Ignores formatting

  • Attribute order ignored

13. Exit codes

Code Meaning

0

Documents are equivalent

1

Documents differ

2

Error occurred (invalid arguments, file not found, etc.)

14. See also