/ 
GDPR-IAB-TCFv2-0.511
⭐ Starred 1 / iabtcfv2

NAME

iabtcfv2 - CLI tool for GDPR IAB TCF v2 strings

SYNOPSIS

iabtcfv2 [options] <subcommand> [subcommand-options]

Run with -h for a short overview, or --help for the full manual.

OPTIONS

-h

Print a brief summary (synopsis + common options + pointer to --help) and exits. Pair with a subcommand for a per-subcommand summary, e.g. iabtcfv2 dump -h.

--help

Print the full manual (this document) and exits. Same as iabtcfv2 help. For per-subcommand manuals, run iabtcfv2 <sub --help> or iabtcfv2 help <sub>.

--version, -V

Print the version and exits.

--man

Prints the manual page and exits.

SUBCOMMANDS

dump

Parses TC strings and outputs them as JSON.

validate

Validates TC strings against a vendor identity and a set of purpose lists, emitting one JSON record per string (or text lines with --text).

DUMP

Usage

iabtcfv2 dump [options] [tc_strings...]

Run `iabtcfv2 dump -h` for a short summary, or `--help` for this manual.

Description

Parses TC strings and outputs them as JSON.

Options

--pretty, -p

Output human-readable, indented JSON.

--compact, -c

Output a compact JSON representation (lists of IDs instead of boolean maps).

--vendor-id, -v ID

Filter the output to only show data for a specific vendor ID.

--strict-legal-basis, -s

Enable strict specification validation. In this mode, the tool will fail if mandatory segments are missing (e.g., Disclosed Vendors in TCF v2.3).

--ignore-errors, -i

Do not output any JSON error object for failed strings.

--fail-fast, -f

Stop processing and exit the program immediately upon the first parse error.

--errors-to-stderr, -e

Output JSON error objects to STDERR instead of STDOUT.

--enable-warnings, -w

Emit human-readable warning messages on STDERR when a TC string fails to parse. Off by default; enable to get diagnostic context alongside the JSON error object.

--quiet, -q

Suppress all output on STDOUT. The exit code still reflects whether parsing succeeded, which is convenient for shell-style if iabtcfv2 dump -q "$tc" checks. Combine with --enable-warnings if you want diagnostics on STDERR.

Examples

# Dump a string to JSON line
iabtcfv2 dump CPi...AAA

# Dump multiple strings (one JSON object per line)
iabtcfv2 dump CPi...AAA CPj...BBB

# Read from STDIN
cat strings.txt | iabtcfv2 dump

# Pipe through `jq -s` if you need a single JSON array
cat strings.txt | iabtcfv2 dump | jq -s .

Short option bundling

Single-character flags can be bundled together after a single dash. The last option in the bundle may take a value as the next argument.

# Equivalent of `--pretty --ignore-errors`
iabtcfv2 dump -pi CPi...AAA

# Equivalent of `--compact --pretty`
iabtcfv2 dump -cp CPi...AAA

# Last bundled short can take a value: -p (pretty) + -v <id> (vendor-id)
iabtcfv2 dump -pv 284 CPi...AAA

# Long options accept the GNU `=value` form too
iabtcfv2 dump --vendor-id=284 CPi...AAA

Bundling does NOT support abbreviating long options (`--ver` is not accepted as a shortcut for `--version`); always use the full long-option name or its single-character short alias.

DOCKER USAGE

This tool is also available as a Docker image on Docker Hub.

Basic Usage

docker run --rm peczenyj/gdpr-iab-tcfv2 dump "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

Processing Streams (STDIN)

To process a stream of strings via pipe:

cat strings.txt | docker run -i --rm peczenyj/gdpr-iab-tcfv2 dump

To type strings manually:

docker run -it --rm peczenyj/gdpr-iab-tcfv2 dump

VALIDATE

Usage

iabtcfv2 validate --vendor-id <id> [options] [tc_strings...]

Run `iabtcfv2 validate -h` for a short summary, or `--help` for this manual.

Description

Validates TC strings against a vendor identity and a set of declared purpose lists. The vendor must be allowed for every purpose in --consent-purposes on a consent basis, and for every purpose in --legitimate-interest-purposes on a legitimate-interest basis. Purposes listed in --flexible-purposes are checked using the GVL flexible-purpose semantics, with the default basis derived from which list also contains the purpose. See GDPR::IAB::TCFv2::Validator for the underlying rule engine.

By default the subcommand emits one JSON object per input TC string on STDOUT. With --text it emits one human-readable line per string instead.

Output shape

A successful validation produces:

{"tc_string":"CO...","vendor_id":32,"valid":true}

A failure in default (fail-fast) mode produces a singular reason:

{"tc_string":"CO...","vendor_id":32,"valid":false,
 "reason":"vendor 32 not allowed for purpose 1 (consent)"}

A failure in --all mode produces a plural reasons array:

{"tc_string":"CO...","vendor_id":32,"valid":false,
 "reasons":["...","..."]}

A parse error produces the same shape as the dump subcommand:

{"tc_string":"INVALID","error":"...","success":false}

Required options

--vendor-id, -v ID

The numeric vendor ID to validate against. Required.

Purpose options

--consent-purposes, -C 1,2,3

Comma-separated list of purpose IDs that the vendor must be allowed to process on a consent basis.

--legitimate-interest-purposes, -L 1,2,3

Comma-separated list of purpose IDs that the vendor must be allowed to process on a legitimate interest basis.

--flexible-purposes, -F 1,2,3

Comma-separated list of purpose IDs that the vendor declared as flexible. Each ID listed here MUST also appear in either --consent-purposes or --legitimate-interest-purposes; the membership determines the default legal basis used for the flexible-purpose check.

Rule options

--verify-disclosed-vendors, -d

Require the vendor to appear in the Disclosed Vendors segment. When the TC string carries the segment, the vendor must be present. If the segment is absent, it only fails if --min-tcf-policy-version is set to 5 or higher (TCF v2.3+).

--strict-legal-basis, -s

Enable strict spec validation in the underlying parser (see dump --strict).

--min-tcf-policy-version, -m N

Reject TC strings whose Global Vendor List policy version is below N. Checked first, before any vendor- or purpose-level rules.

--cmp-validator PATH-OR-URL

Validate the cmp_id embedded in each TC string against an IAB CMP registry snapshot. The argument is detected as a URL when it starts with http:// or https://, otherwise it is treated as a local file path. Failures yield a reason mentioning the unknown or deleted CMP id.

When the argument is a URL, the standard HTTP-proxy environment variables (https_proxy, http_proxy, no_proxy) are honored automatically.

--cmp-validator-network-ok

Required when --cmp-validator is a URL. Without this flag, URL fetching is refused (mirrors the library's network_ok => 1 opt-in: fetching from an arbitrary URL is intentional, never accidental). Has no effect when --cmp-validator is a file path.

--cmp-validator-verify-ssl, --no-cmp-validator-verify-ssl

Verify TLS certificates when fetching from an HTTPS URL. On by default; disable with --no-cmp-validator-verify-ssl only when targeting a server with a self-signed or otherwise non-public-CA certificate. Has no effect when --cmp-validator is a file path.

--cmp-validator-timeout SECONDS

Per-request timeout for the URL fetch, in seconds. Defaults to 30. Has no effect when --cmp-validator is a file path.

--all, -a

Accumulate every failing rule into a reasons array instead of short-circuiting on the first failure. The output JSON uses plural reasons (array) instead of singular reason (string).

Output options

--pretty, -p

Output human-readable, indented JSON.

--text, -t

Output one human-readable line per TC string instead of JSON. Format:

OK     <tc>  vendor <id>
FAIL   <tc>  vendor <id>: <reason>
ERROR  <tc>: <parse error>

In --all mode, multi-reason failures span multiple indented lines.

--ignore-errors, -i

Skip parse errors silently (still bumps the exit code). Validation failures are still emitted.

--fail-fast, -f

Exit immediately on the first parse error or the first invalid TC string. Validation failures are emitted before exiting; parse errors are not (matches the dump contract).

--errors-to-stderr, -e

Route parse-error records to STDERR instead of STDOUT.

--enable-warnings, -w

Emit human-readable warning messages on STDERR when a TC string fails to parse, and when the --cmp-validator registry snapshot is older than 28 days. Off by default.

--quiet, -q

Suppress all output on STDOUT. The exit code still reflects validity, which is convenient for shell-style if iabtcfv2 validate -q -v 32 ... "$tc" checks.

Exit codes

  • 0 — every input TC string was parsed and validated cleanly.

  • 1 — at least one TC string failed validation or could not be parsed.

  • 2 — bad CLI usage (missing --vendor-id, incoherent purpose lists, unreachable --cmp-validator source).

Examples

# Single string, fail-fast
iabtcfv2 validate -v 32 -C 1,3 -L 7 CO...AAA

# All reasons, pretty JSON, text-friendly
iabtcfv2 validate -av 32 -C 1,3 -L 7 -t CO...AAA

# Pipeline-friendly: just the exit code
if iabtcfv2 validate -q -v 32 -C 1,3 "$tc"; then ...

# Many strings as JSON Lines (one record per line); pipe through
# `jq -s` if you need a single JSON array.
iabtcfv2 validate -v 32 -C 1,3 CO...AAA CO...BBB
iabtcfv2 validate -v 32 -C 1,3 CO...AAA CO...BBB | jq -s .

# Reject TC strings that name an unknown or deleted CMP, using a
# local snapshot of the IAB CMP registry.
iabtcfv2 validate -v 32 --cmp-validator /etc/iab/cmp-list.json CO...AAA

# Same, but fetching the registry over HTTPS through whatever
# proxy `https_proxy` points at.
iabtcfv2 validate -v 32 \
    --cmp-validator https://cmplist.consensu.org/v2/cmp-list.json \
    --cmp-validator-network-ok \
    CO...AAA

DESCRIPTION

iabtcfv2 is a command-line interface for the GDPR::IAB::TCFv2 library.

Warning: Name Change

Previous versions of this distribution (v0.300) included a standalone utility named iabtcf-dump. This has been unified into the iabtcfv2 tool using the dump subcommand.

BUGS

Report bugs and feature requests at https://github.com/peczenyj/GDPR-IAB-TCFv2/issues.