gonemaster-client(1)

NAME

gonemaster-client - HTTP API client for gonemaster-server

SYNOPSIS

gonemaster-client [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS]

DESCRIPTION

gonemaster-client interacts with a running gonemaster-server instance via its REST API. It can submit test jobs, monitor progress, retrieve results, manage the job queue, and query the domain/tag/run/entry analysis APIs.

GLOBAL OPTIONS

–server URL: Base API URL (default: http://localhost:8080/api/v1).
–timeout DURATION: HTTP request timeout (default: 30s).
–format FORMAT: Output format: pretty, json, or json-stream (default: pretty).
–output PATH: Write output to a file instead of stdout.
–locale LOCALE: Locale for translated messages (default: en).
–no-color: Disable ANSI colors in pretty output.
–header NAME:VALUE: Extra HTTP header (repeatable).
–version: Print version and exit.

COMMANDS

jobs create

Submit a single test job.

–domain DOMAIN: Zone to test (required).
–min-level LEVEL: Minimum severity level.
–tests TEST: Run specific test(s) (repeatable).
–wait: Wait for completion and display results.
–view VIEW: Result view: summary, modules, raw, json.

jobs batch

Submit a batch of test jobs.

–domain DOMAIN: Zone to test (repeatable).
–file PATH: File with one domain per line (repeatable).
–stdin: Read domains from stdin.
–from-tag TAG: Re-run all domains currently in this tag. Mutually exclusive with –domain/–file/–stdin.
–tag TAG: Apply this tag to all batch domains (repeatable; creates tag/domain records if needed).
–wait: Wait for all jobs to complete.
–per-job: Show per-job results when waiting.

jobs list

List jobs with optional filters.

–status STATUS: Filter by job status.
–limit N: Maximum results (default: 100).

jobs get JOB-ID

Get details for a single job.

jobs watch JOB-ID

Watch a job until completion.

jobs cancel JOB-ID

Cancel a running job.

jobs purge

Delete completed jobs older than a given age, along with their results.

–older-than N: Delete jobs finished more than N days ago. 0 (default) uses the server’s configured retention_days. Returns an error if both are 0.

domains list

List domains in the registry.

–tag TAG: Filter to domains in this tag.
–name SUBSTRING: Filter by domain name substring.
–level LEVEL: Filter by exact latest level (e.g. ERROR).
–limit N: Maximum results (default: 100).

domains get DOMAIN-NAME

Get details for a domain (tags, run count, latest level).

domains runs DOMAIN-NAME

List run history for a domain.

–limit N: Maximum results (default: 20).

domains tag DOMAIN-NAME TAG [TAG…]

Add a domain to one or more tags (creates tag records if needed).

domains untag DOMAIN-NAME TAG [TAG…]

Remove a domain from one or more tags.

tags list

List all tags.

tags create TAG-NAME

Create a new tag.

–description TEXT: Optional description.

tags delete TAG-NAME

Delete a tag (domain records and runs are preserved).

tags domains TAG-NAME

List domains in a tag.

–limit N: Maximum results (default: 100).

tags summary TAG-NAME

Show per-severity domain counts for a tag.

tags add-domains TAG-NAME [DOMAIN…] [–file PATH] [–stdin]

Add domains to a tag in bulk. Creates domain records if needed.

–file PATH: File with one domain per line (repeatable).
–stdin: Read domains from stdin.

runs list

List completed runs.

–tag TAG: Filter to runs for domains in this tag.
–domain SUBSTRING: Filter by domain name substring.
–batch BATCH-ID: Filter by batch ID.
–level LEVEL: Filter by worst level.
–limit N: Maximum results (default: 100).

runs get RUN-ID

Get metadata for a single run.

runs results RUN-ID

Fetch and display results for a run.

–view VIEW: Result view: summary, modules, raw, json.

entries query

Query individual engine log entries across runs.

–tag TAG: Filter by domain tag.
–module MODULE: Filter by module name (e.g. DNSSEC).
–testcase TESTCASE: Filter by testcase name.
–entry-tag TAG: Filter by log event tag (e.g. DS_ALGO_NOT_SUPPORTED).
–level LEVEL: Filter by severity level.
–latest: Only entries from each domain’s latest run.
–limit N: Maximum results (default: 100).

Use –format csv to download results as CSV.

batches get BATCH-ID

Get batch summary.

batches watch BATCH-ID

Watch a batch until completion.

batches cancel BATCH-ID

Cancel all jobs in a batch.

batches remove BATCH-ID

Remove a batch. Use –cancel-running to cancel active jobs first.

queue pause

Pause the job queue.

queue resume

Resume the job queue.

results

Retrieve and display test results.

–job-id ID: Fetch results for a job (repeatable).
–batch-id ID: Fetch results for a batch.
–view VIEW: Result view: summary, modules, raw, json.
–aggregate: Aggregate results across jobs.
–split-dir PATH: Write per-job results to separate files in a directory.

EXAMPLES

Test a single domain and wait for results:

gonemaster-client jobs create --domain example.com --wait

Batch test from a file and tag all domains:

gonemaster-client jobs batch --file domains.txt --tag tld --wait --per-job

Re-run all domains in a tag:

gonemaster-client jobs batch --from-tag tld --tag tld --wait

Get results for a completed job:

gonemaster-client results --job-id abc123 --view summary

List domains with ERROR or worse:

gonemaster-client domains list --tag tld --level ERROR

Show per-severity summary for a tag:

gonemaster-client tags summary tld

List recent runs for a domain:

gonemaster-client domains runs example.com

Fetch full results for a run:

gonemaster-client runs results <run-id> --view summary

Export all DNSSEC entries for a tag as CSV:

gonemaster-client --format csv entries query --tag tld --module DNSSEC --latest

Watch a batch in progress:

gonemaster-client batches watch batch-456

Purge completed jobs older than 90 days:

gonemaster-client jobs purge --older-than 90

Use a remote server with JSON output:

gonemaster-client --server https://gm.example.com/api/v1 \
    --format json jobs create --domain example.com --wait