BUG: Fix get-zones argument parsing to match documentation

[cafferata]

I ran into this same issue while working on #4208 and can confirm the behavior @stefanwascoding describes. The only form that works requires the provider name explicitly:

dnscontrol get-zones transip TRANSIP all

WARNING: To retain compatibility in future versions, please change "TRANSIP" to "-". See "https://docs.dnscontrol.org/commands/get-zones"

But following that suggestion also fails:

dnscontrol get-zones transip - all

Arguments should be: credskey providername zone(s) (Ex: r53 ROUTE53 example.com)

So neither the documented 2 argument form (transip all) nor the suggested dash form (transip - all) works.

This pull request fixes the argument parsing so that get-zones accepts 2 arguments (credkey zone), resolving the provider type from the TYPE field in creds.json. The old 3 argument form still works but now shows a deprecation warning with the correct command:

dnscontrol get-zones transip TRANSIP all

WARNING: The provider name argument is deprecated. Please use "dnscontrol get-zones transip all" instead. See "https://docs.dnscontrol.org/commands/get-zones"

With 3+ arguments, the code now detects whether the second argument is a registered provider type to distinguish the deprecated form (credkey provider zone...) from the new multi-zone form (credkey zone1 zone2...):

dnscontrol get-zones --format=nameonly transip dnscontrol.org dnscontrol.nl

dnscontrol.org
dnscontrol.nl

Additionally:

• CLI help is shortened and links to online documentation
• Examples use descriptive credkey names (my_route53 instead of myr53) so they are self-explanatory without the provider name
• Documentation: links are added to get-zones and check-creds
• documentation/commands/get-zones.md is updated to match

Tested against the TransIP provider with the dnscontrol.org zone from #4204.

• go test ./commands/
• dnscontrol get-zones transip all (2 args, new style)
• dnscontrol get-zones transip dnscontrol.org (specific zone)
• dnscontrol get-zones transip dnscontrol.org dnscontrol.nl (multiple zones, new style)
• dnscontrol get-zones transip TRANSIP all (3 args, deprecation warning)
• dnscontrol get-zones transip (too few args, error message)
• dnscontrol get-zones --format=zone transip dnscontrol.org
• dnscontrol get-zones --format=tsv transip dnscontrol.org
• dnscontrol get-zones --format=nameonly transip all

CLI diff

--- before (v4.37.1)
+++ after
@@ -2,7 +2,7 @@
    dnscontrol get-zones - gets a zone from a provider (stand-alone)
 
 USAGE:
-   dnscontrol get-zones [command options] credkey provider zone [...]
+   dnscontrol get-zones [command options] credkey zone [...]
 
 CATEGORY:
    utility
@@ -11,34 +11,18 @@
    Download a zone from a provider.  This is a stand-alone utility.
 
    ARGUMENTS:
-      credkey:  The name used in creds.json (first parameter to NewDnsProvider() in dnsconfig.js)
+      credkey:  The name used in creds.json
-      provider: The name of the provider (second parameter to NewDnsProvider() in dnsconfig.js)
       zone:     One or more zones (domains) to download; or "all".
 
-   FORMATS:
-      --format=js        dnsconfig.js format (not perfect, just a decent first draft)
-      --format=djs       js with disco commas (leading commas)
-      --format=zone      BIND zonefile format
-      --format=tsv       TAB separated value (useful for AWK)
-      --format=nameonly  Just print the zone names
-
-   The columns in --format=tsv are:
-      FQDN (the label with the domain)
-      ShortName (just the label, "@" if it is the naked domain)
-      TTL
-      Record Type (A, AAAA, CNAME, etc.)
-      Target and arguments (quoted like in a zonefile)
-      Either empty or a comma-separated list of properties like "cloudflare_proxy=true"
-
-   The --ttl flag only applies to zone/js/djs formats.
-
    EXAMPLES:
-      dnscontrol get-zones myr53 ROUTE53 example.com
-      dnscontrol get-zones gmain GANDI_V5 example.com other.com
-      dnscontrol get-zones cfmain CLOUDFLAREAPI all
-      dnscontrol get-zones --format=tsv bind BIND example.com
-      dnscontrol get-zones --format=djs --out=draft.js gcloud GCLOUD example.com
+      dnscontrol get-zones my_route53 example.com
+      dnscontrol get-zones my_gandi example.com other.com
+      dnscontrol get-zones my_cloudflare all
+      dnscontrol get-zones --format=tsv my_bind example.com
+      dnscontrol get-zones --format=djs --out=draft.js my_gcloud example.com
 
+   Documentation: https://docs.dnscontrol.org/commands/get-zones
+
 OPTIONS:
    --creds string   Provider credentials JSON file (or !program to execute program that outputs json) (default: "creds.json")
    --format string  Output format: js djs zone tsv nameonly (default: "zone")

Fixes #4235

[TomOnTime]

Thanks for fixing this and cleaning how it works!

[TomOnTime]

nitpick: Previously the code allowed a list of zone names. That's why the -h listing includes [...] at the end of the usage spec:

USAGE:
   dnscontrol get-zones [command options] credkey zone [...]

I'm ok with fixing the code or simply updating the docs. I don't know many times when listing multiple zones is needed.

Related: (mostly thinking out loud. These don't have to be part of this PR). I wonder if we should drop the all and just allow an empty list to mean all zones. I've also thought that we should create list-zones as an alias for get-zones --format=nameonly credkey all

[cafferata]

Thanks for the approval and feedback! I'll address each point:

Multi-zone support: Good catch. I hadn't thought about this scenario (I've never used the multi-zone form myself). Since it's a small fix, I went ahead and implemented it right away by checking whether the second argument is a registered provider type. If it is: deprecated path with warning. If not: new format with multiple zones. This should cover all remaining edge cases around get-zones argument parsing.

list-zones alias: Great idea! I ran into the same need in #4208 when wanting to list domains during init. A dedicated list-zones command would have been a much cleaner fit there. Happy to explore that in a follow-up.

Removing the v3.16 migration notes from the docs: While cleaning up the documentation I kept the "As of v3.16" section as-is, but I think we can safely remove it entirely. v3.16.0 was released over 4 years ago (May 2022). Anyone still on v3.15 or older is unlikely to consult the current docs for migration guidance. What do you think?

[TomOnTime]

Thanks for the approval and feedback! I'll address each point:

Multi-zone support: Good catch. I hadn't thought about this scenario (I've never used the multi-zone form myself). Since it's a small fix, I went ahead and implemented it right away by checking whether the second argument is a registered provider type. If it is: deprecated path with warning. If not: new format with multiple zones. This should cover all remaining edge cases around get-zones argument parsing.

👍

list-zones alias: Great idea! I ran into the same need in #4208 when wanting to list domains during init. A dedicated list-zones command would have been a much cleaner fit there. Happy to explore that in a follow-up.

👍

Removing the v3.16 migration notes from the docs: While cleaning up the documentation I kept the "As of v3.16" section as-is, but I think we can safely remove it entirely. v3.16.0 was released over 4 years ago (May 2022). Anyone still on v3.15 or older is unlikely to consult the current docs for migration guidance. What do you think?

Agreed.

[cafferata]

Thanks! I've pushed the v3.16 migration guide removal. This cleans up references across check-creds.md, creds-json.md, NewRegistrar.md, NewDnsProvider.md, SUMMARY.md, and removes documentation/release/v316.md entirely.

Ready for a final review whenever you have a moment.

[TomOnTime]

Awesome!