matchers:*

Manage PII column-detection rules stored in clonio.pii-matchers.yaml.

Clonio detects personally identifiable information (PII) columns automatically by matching column names against a set of rules called matchers. Matchers are grouped into semantic categories and can use regex, glob, or literal patterns. When a column matches, a configured transformation strategy (fake, hash, mask, etc.) is applied during cloning:dump.

The binary ships a baseline set of matchers. You can customise detection by initialising a clonio.pii-matchers.yaml file in your project root and editing it — it contains no credentials and is safe to commit.

Sub-commands

• matchers:init — write the baseline to disk
• matchers:update — add new baseline matchers to an existing file
• matchers:list — show the effective matcher set
• matchers:check — test a column name against the active matcher set

matchers:init

Write the full baseline PII matcher configuration to clonio.pii-matchers.yaml.

clonio matchers:init

Options

Behaviour

1. If clonio.pii-matchers.yaml already exists and --force is not set, prompts for confirmation.
2. Writes all baseline groups and matchers to the file.
3. Prints a summary of groups and matcher counts.

Example output

  Writing PII matcher baseline to clonio.pii-matchers.yaml ...

  Groups written:
    personal_identity     5 matchers
    contact               3 matchers
    location              6 matchers
    financial             3 matchers
    authentication        2 matchers
    network               1 matchers

  Total: 20 matchers across 6 groups

  Edit clonio.pii-matchers.yaml to customise detection, then commit it to your repository.
  Run matchers:update after upgrading Clonio to add new baseline matchers.

  Tip: clonio.pii-matchers.yaml contains no credentials and is safe to commit.
       Make sure clonio.json is in your .gitignore.

Notes

• Run this once per project to get started.
• After editing clonio.pii-matchers.yaml, the file is the sole source of truth. The baseline is only used when the file is absent.
• After upgrading Clonio, run matchers:update to pick up any new baseline matchers.

matchers:update

Sync an existing clonio.pii-matchers.yaml with the current binary baseline by adding any new matchers that are in the baseline but not in your file.

clonio matchers:update

Options

Behaviour

1. Reads the existing clonio.pii-matchers.yaml.
2. Compares it against the baseline shipped in the current binary.
3. Reports any new baseline matchers (additions) and any matchers in your file that no longer exist in the baseline (orphans).
4. If --dry-run is not set, writes the additions to the file. Orphans and your customisations are left untouched.

Example output — new matchers found

  Checking clonio.pii-matchers.yaml against binary baseline ...

  New matchers added:
    financial             →  crypto_wallet_address  "Crypto Wallet Address"
    network               →  mac_address            "MAC Address"   (new group)

  Orphaned matchers (in file but no longer in baseline):
    personal_identity     →  maiden_name  "Maiden Name"
    ⚠  These are no longer recognised by the current Clonio baseline.
       They may be custom entries or from an older version.
       Remove them manually if they are no longer needed.

  2 matchers added. 1 orphaned matcher reported. Your existing customisations were not changed.

Example output — up to date

  Checking clonio.pii-matchers.yaml against binary baseline ...

  clonio.pii-matchers.yaml is up to date. No changes needed.

Exit codes

matchers:list

Show the full effective matcher set — from clonio.pii-matchers.yaml if it exists, otherwise from the binary baseline.

clonio matchers:list

Options

Example output

The table includes a Sensitivity column indicating the risk level of each matcher:

  Effective PII matchers  (source: binary baseline)

  +---+-----------------------------+----------------+---------------------------------+-----------+----------------------+----------+
  |   | Group                       | Key            | Name                            | Sensitivity | Transformation     | Source   |
  +---+-----------------------------+----------------+---------------------------------+-----------+----------------------+----------+
  | ✓ | Government-Issued Identif…  | national_id    | National ID / SSN               | critical  | hash → sha256        | baseline |
  | ✓ | Government-Issued Identif…  | passport_number| Passport Number                 | critical  | hash → sha256        | baseline |
  | ✓ | Personal Identity           | first_name     | First Name                      | high      | fake → firstName     | baseline |
  | ✓ | Contact Information         | email_address  | Email Address                   | high      | fake → safeEmail     | baseline |
  | ✓ | Financial Data              | credit_card    | Credit Card Number              | critical  | mask                 | baseline |
  | ✓ | Medical & Health            | medical_record_id | Medical Record Number        | critical  | hash → sha256        | baseline |
  | — | Authentication & Secrets    | api_token      | API Token / Key                 | critical  |                      | baseline, disabled |
  +---+-----------------------------+----------------+---------------------------------+-----------+----------------------+----------+

  Total: 34 active matchers across 10 groups  (13 disabled)
  Source: binary baseline — run matchers:init to customise

Source annotation

Each row is annotated with its source:

• baseline — from the binary baseline (when no file exists)
• file — defined in clonio.pii-matchers.yaml
• baseline, disabled / file, disabled — matcher is present but enabled: false

Sensitivity levels

matchers:check

Test a column name against the active matcher set and show the result, including a live example of the transformation applied to a real input value.

clonio matchers:check <column> [value]

Arguments

Options

Example — match found (built-in example)

clonio matchers:check credit_card

  Column "credit_card" matched:

    Matcher:        credit_card
    Group:          financial
    PII category:   "Credit Card Number"
    Sensitivity:    critical
    Source:         binary baseline
    Matched by:     /^(credit[-_]?card|card[-_]?number|cc[-_]?number|payment[-_]?card|pan)$/i  (regex)

    Transformation:
      strategy:       mask
      visible_chars:  4
      mask_char:      "*"
      preserve_format: false

    Example:
      Input:   4242424242424242
      Output:  4242************

Example — match found with custom value

clonio matchers:check credit_card 5555555555554444

    Example:
      Input:   5555555555554444
      Output:  5555************

Example — fake strategy (input is not used)

clonio matchers:check email

    Example:
      Input:   john.doe@example.com
      Output:  emily.smith@example.net  (faker generates fresh data — input value is not used)

Example — no match

clonio matchers:check created_at

  Column "created_at" — no matcher found

  This column will be treated as strategy: keep by cloning:dump.

Example section behaviour

For fake strategy the output is always freshly generated by Faker regardless of the input value — the note is shown to make this clear.

Value validation

The following are rejected with an error message (exit 0):

• Empty or whitespace-only string
• Strings longer than 10,000 characters
• Strings containing binary or control characters

Exit codes

Always exits 0, regardless of whether a match is found or validation fails.

The clonio.pii-matchers.yaml file

File format

# yaml-language-server: $schema=https://schema.clonio.dev/pii-matchers/v1.json
version: "1"

groups:
  contact:
    name: "Contact Information"
    matchers:
      email_address:
        name: "Email Address"
        enabled: true
        patterns:
          - "/^(e[-_]?mail|email[-_]?addr(ess)?)$/i"
          - reply_to
          - "*_email"
        transformation:
          strategy: fake
          faker_method: safeEmail
          faker_arguments: []

Pattern syntax

Transformation strategies

Recommended workflow

# 1. Initialise the matcher file in your project
clonio matchers:init

# 2. Review and edit clonio.pii-matchers.yaml
#    Enable any disabled matchers relevant to your data
#    (e.g. medical, biometric, salary — disabled by default)
# 3. Commit clonio.pii-matchers.yaml to version control

# 4. Test that a column is classified correctly
clonio matchers:check user_email
clonio matchers:check ssn 123-45-6789   # test with a real value

# 5. After upgrading Clonio, sync new baseline matchers
clonio matchers:update

Built-in matcher groups

The binary ships 10 matcher groups covering all major PII categories:

¹ Disabled by default — enable in clonio.pii-matchers.yaml when relevant to your schema.