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

NAME

iabtcfv2 - CLI tool for GDPR IAB TCF v2 strings

SYNOPSIS

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

OPTIONS

--help, -h

Print a brief help message and exits.

--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

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, -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

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

--check-disclosed-vendors, -d

Require the vendor to appear in the Disclosed Vendors segment when the TC string carries one. Off by default.

--strict, -s

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

--min-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-list 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-list-network-ok

Required when --cmp-list 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-list is a file path.

--cmp-list-verify-ssl, --no-cmp-list-verify-ssl

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

--cmp-list-timeout SECONDS

Per-request timeout for the URL fetch, in seconds. Defaults to 30. Has no effect when --cmp-list 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-list 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-list 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-list /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-list https://cmplist.consensu.org/v2/cmp-list.json \
    --cmp-list-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.