usage: pydiggs [-h] [--schema_path SCHEMA_PATH]
[--dictionary_path DICTIONARY_PATH]
[--schematron_path SCHEMATRON_PATH]
[--output_log | --no-output_log]
{schema_check,schematron_check,dictionary_check,context_check}
diggs_file
A Python package for Data Interchange for Geotechnical and Geoenvironmental
Specialists (DIGGS).
positional arguments:
{schema_check,schematron_check,dictionary_check,context_check}
Available commands for execution
diggs_file Relative or full path of the DIGGS instance file
options:
-h, --help show this help message and exit
--schema_path SCHEMA_PATH
Relative or full path of the DIGGS schema file
(default: auto-detect 2.5.a / 2.6 / 3.0.0 from
instance NS)
--dictionary_path DICTIONARY_PATH
Primary DIGGS dictionary file (default: bundled
properties.xml)
--schematron_path SCHEMATRON_PATH
Schematron schema file (default: bundled DIGGS lxml-
adapted rules)
--output_log, --no-output_log
Write validation logs to the current working directory
(default: True)
Machine-readable findings (JSON, SARIF) for one or many files: pydiggs
validate --help. Validation for other programs (stdio sidecar, HTTP, MCP):
pydiggs serve --help. AGS4 files against the AGS4 rules: pydiggs ags4 check
--help. AGS4 to DIGGS and DIGGS to AGS4: pydiggs convert --help. What changed
between two DIGGS files: pydiggs diff --help. Installed version: pydiggs
--version.
usage: pydiggs ags4 [-h] COMMAND ...
Work with AGS4 files. See: pydiggs ags4 check --help.
positional arguments:
COMMAND
check check AGS4 files against the AGS4 rules (Rules 1 to 20)
options:
-h, --help show this help message and exit
usage: pydiggs ags4 check [-h] [--dictionary FILE]
[--format {text,json,sarif}] [--output FILE]
[--fail-on {error,warning}] [--max-findings N]
[--max-bytes N] [--time-budget SECONDS]
[--absolute-paths]
FILE [FILE ...]
Check AGS4 files against the AGS4 rules (Rules 1 to 20 of the AGS4
specification, Edition 4.2) and report the findings as text, JSON (diggs-
findings 1.2) or SARIF 2.1.0. pyDIGGS bundles no AGS data dictionary: the
rules that need one (7, 9, 10a, 10b, 10c, 18, and parts of 11c, 13, 14 and
19b) run for the file's own DICT group, and for standard groups only with
--dictionary. Not an AGS-approved validator.
positional arguments:
FILE AGS4 files to check
options:
-h, --help show this help message and exit
--dictionary FILE an AGS4 data dictionary (such as the AGS standard
dictionary of the version)
--format {text,json,sarif}
--output FILE write the report here, not stdout
--fail-on {error,warning}
--max-findings N keep at most N findings per file (default 10000; 0: no
limit)
--max-bytes N refuse files larger than N bytes (default 100 MiB)
--time-budget SECONDS
stop checking a file after SECONDS; what was found so
far is reported
--absolute-paths report absolute paths in JSON and SARIF (default:
relative to here)
Exit status: 0 no finding at or above --fail-on; 1 some; 2 usage error, an
unreadable input, or an unusable dictionary.
usage: pydiggs capabilities [-h] [--json]
List what this pydiggs can do: each operation, how stable it is, what it reads
and gives, and whether the extras it needs are installed.
options:
-h, --help show this help message and exit
--json print a diggs-capabilities 1.0 document
(pydiggs.capabilities().to_dict())
usage: pydiggs convert [-h] -o OUT [--to {diggs,ags4}]
[--diggs-version {3.0.0}] [--ags-version {4.2,4.1.1}]
[--residual FILE] [--report FILE]
[--format {text,json}] [--fail-on {error,loss}]
[--force] [--max-bytes N] [--time-budget SECONDS]
IN
Convert an AGS4 file to a DIGGS 3.0.0 document, or (--to ags4) a DIGGS
document to an AGS4 file, by the mapping table described at https://xinp-
hub.github.io/pydiggs/convert-mapping/. Every source value that does not reach
the output is reported as a loss; the output is validated (DIGGS) or checked
against the AGS4 rules (AGS4). pyDIGGS bundles no AGS data dictionary and is
not an AGS-approved tool.
positional arguments:
IN the file to convert: AGS4, or DIGGS XML with --to ags4
options:
-h, --help show this help message and exit
-o OUT, --output OUT where to write the output (DIGGS XML, or the AGS4 file
with --to ags4)
--to {diggs,ags4} the format to convert to: diggs (the default; IN is
AGS4) or ags4 (IN is DIGGS)
--diggs-version {3.0.0}
the DIGGS version to write (--to diggs; default:
3.0.0)
--ags-version {4.2,4.1.1}
the AGS4 version to write (--to ags4; default: 4.2).
The BGS AGS validator and python-ags4 1.2.0 accept
AGS4 only up to 4.1.1 (November 2026)
--residual FILE also write the AGS4 file of what was not converted
here (--to diggs only; not written when everything was
converted)
--report FILE also write the findings report (diggs-findings 1.2
JSON) here
--format {text,json} the summary on stdout: text, or JSON (the result
without the output bytes)
--fail-on {error,loss}
--force replace OUT (and --report) if they exist
--max-bytes N refuse inputs larger than N bytes (default 100 MiB)
--time-budget SECONDS
stop converting after SECONDS; the output is then
partial and says so
Exit status: 0 no finding at or above --fail-on; 1 some; 2 usage error, an
input that cannot be read or is not of the expected format, or an output that
cannot be written.
usage: pydiggs diff [-h] [--format {text,json}] [-o FILE]
[--match {auto,gml-id,natural}] [--rel-tol R]
[--abs-tol A] [--max-changes N] [--time-budget SECONDS]
[--max-bytes N] [--verbose]
OLD NEW
Compare two DIGGS files by what they describe, not by how they are written:
element order, number formatting, line numbers and the gml:id of a record do
not count. Boreholes, samples, tests and the other records are matched by
gml:id, then by a natural key (a borehole's kind and name, a sample's
borehole, name and top), so records stay paired when their gml:ids change: two
exports of the same data with new ids are identical. The renamed ids are
counted, and listed with --verbose. Numbers compare within a tolerance; a
change of unit is always a change, and nothing is converted. The two files may
be different DIGGS versions.
positional arguments:
OLD the earlier DIGGS file
NEW the later DIGGS file
options:
-h, --help show this help message and exit
--format {text,json} the report: text (the default), or JSON (a diggs-diff
document)
-o FILE, --output FILE
write the report here, not to stdout
--match {auto,gml-id,natural}
how records are paired: auto (the default; by gml:id,
then by natural key), gml-id (ids only, also written
gml_id; a record whose gml:id changed is removed and
added) or natural (natural keys only)
--rel-tol R two numbers are equal when they differ by at most R
times the larger one; 0 or more and less than 1
(default 1e-09)
--abs-tol A or by at most A, in the value's own unit (default 0)
--max-changes N list at most N changes (default 10000); the counts
stay exact, and a cut list is an incomplete comparison
--time-budget SECONDS
stop after SECONDS, reading included; the comparison
is then incomplete
--max-bytes N refuse files larger than N bytes (default 100 MiB)
--verbose also list what is not a change: values that are only
written differently (1.50 and 1.5, other separators
that read the same values, double and float) and
records whose gml:id changed; both are always counted
Exit status: 0 the files are identical and the comparison finished; 1 they
differ, or the comparison is incomplete; 2 usage error, an input that cannot
be read or is not DIGGS, or an output that cannot be written.
usage: pydiggs serve [-h] (--stdio | --http | --mcp) [--max-bytes N]
[--max-findings N] [--timeout SECONDS] [--workers N]
[--host H] [--port P] [--allow-path DIR]
[--log-level {debug,info,warning,error,critical}]
[--log-format {text,json}]
Serve DIGGS validation to other programs: a JSON-RPC sidecar on stdin/stdout
(--stdio), an HTTP API (--http, needs pydiggs[server]) or an MCP server on
stdin/stdout (--mcp, needs pydiggs[mcp]). Only the bundled schema,
dictionaries and Schematron rules are used.
options:
-h, --help show this help message and exit
--stdio JSON-RPC 2.0 over NDJSON on stdio
--http HTTP API (pydiggs[server])
--mcp MCP server on stdio (pydiggs[mcp])
--max-bytes N largest document in bytes (default 26,214,400; --stdio
by path 104,857,600; --mcp 10,485,760)
--max-findings N findings kept per document (default 10,000; --mcp 200)
--timeout SECONDS per-request limit in seconds (default 60)
--workers N --http worker processes (default: CPUs-1, 1-4)
--host H --http bind address (default 127.0.0.1)
--port P --http port (default 8000)
--allow-path DIR --stdio: also accept files by absolute path under DIR
(repeatable)
--log-level {debug,info,warning,error,critical}
--log-format {text,json}
Exit status: 0 after a clean shutdown; 2 for bad arguments or a missing extra.
--timeout is a hard limit (process kill) for --http and --mcp, and the default
per-request time budget for --stdio, where the host owns hard limits.
usage: pydiggs validate [-h] [--format {text,json,sarif}] [--output FILE]
[--checks STEP[,STEP...]]
[--diggs-version {2.5.a,2.6,3.0.0,3.1-dev}]
[--schema-path P] [--dictionary-path P]
[--schematron-path P] [--fail-on {error,warning}]
[--max-findings N] [--snippets] [--absolute-paths]
[--max-bytes N] [--timeout SECONDS]
[--local-dictionaries {instance-dir,off}]
[--base-dir DIR] [--allow-network]
PATH [PATH ...]
Validate DIGGS instance files with every native check and report the findings
as text, JSON (diggs-findings 1.2) or SARIF 2.1.0.
positional arguments:
PATH instance files, or directories searched recursively
for *.xml
options:
-h, --help show this help message and exit
--format {text,json,sarif}
--output FILE write the report here, not stdout
--checks STEP[,STEP...]
steps to run (default: all of structure,schema,diction
ary,schematron,geometry,deprecation,context)
--diggs-version {2.5.a,2.6,3.0.0,3.1-dev}
--schema-path P XSD instead of the bundled one
--dictionary-path P primary property dictionary
--schematron-path P Schematron rules file
--fail-on {error,warning}
--max-findings N keep at most N findings per file (default 10000; 0: no
limit)
--snippets include each finding's element XML (off by default: it
carries file data)
--absolute-paths report absolute paths (default: relative to here, else
the bare file name)
--max-bytes N refuse instances larger than N bytes (default 100 MiB)
--timeout SECONDS validate each file in its own process and stop it
after SECONDS (an error)
--local-dictionaries {instance-dir,off}
read local dictionaries only from each instance's
folder (default), or never
--base-dir DIR report paths relative to DIR (default: here, unless
here is / or above home)
--allow-network fetch whitelisted remote code lists that are not
bundled
Exit status: 0 no finding at or above --fail-on; 1 some; 2 usage error, no
input files, or an unreadable input.