Merge pull request #114 from mapbox/fix/help-descriptions

Fix help and schema descriptions, and let true/false flags send false

Author: zmofei

CHANGELOG.md

@@ -29,6 +29,42 @@ that may never merge. They are not releases and are not listed here.
   API for the per-browser, per-country and per-host breakdown, which it now
   sends only on request. Without the flag the request is unchanged, and each
   product's `dimensions` in `-o json` is `{}`.
+- `static get-image`, `static get-tile` and `tilesets get-tile` no longer
+  need their trailing optional positionals: `<highRes>`, `<format>` and
+  `<quality>` can be left off instead of passed as `""`. Writing `""` still
+  works, so existing scripts are unaffected. `--schema` now reports these
+  arguments as not required.
+- A flag for a true/false API parameter now takes `=false`:
+  `--attribution=false` sends `attribution=false`. Alone it still sends
+  `true`, as before. Where the API defaults to `true` (`--attribution`,
+  `--logo`, `--autocomplete`, `--dedupe`, `--continue-straight` on driving
+  profiles), this is the only way to turn the setting off. A workflow
+  step's `false` still leaves the flag out, as before.
+- `directions --snapping-include-closures` and
+  `--snapping-include-static-closures` take a value: `true` or `false` per
+  coordinate, semicolon-separated (`true;false`). They were switches that
+  sent a single `true`, which the API rejects with a 422 for any route, so
+  no working command changes. In `--schema` they change from a boolean
+  flag to a string option; this is a fix rather than a breaking change for
+  the same reason.
+- `--help` shows each parameter's whole description rather than its first
+  sentence, so the allowed values and what else a parameter needs
+  ("Requires `overview=full`") are no longer cut off.
+- An API command's `--help` shows the opening of its description as plain
+  text, followed by a `Docs:` link, instead of the whole Markdown page with
+  its headings, tables and curl examples (`geocoder batch` was 113 lines).
+  `--schema` still carries the full description.
+- `--id` on a command that is not an API command (`history show`,
+  `auth profiles`, `config list` and the like) is now a usage error, exit
+  code 2. It used to be ignored: `history show --id x` printed the newest
+  run as if it were `x`.
+- `--schema`: `env` and `default` are filled for every argument, including
+  the ones read by hand (`--timeout`, `--output`, `--no-color`, `--profile`,
+  `workflow install --repo`/`--ref`), which only mentioned them in their
+  description. A new top-level `groups` list carries what a command group's
+  own help says, such as `mapbox history`, which `commands` (leaves only)
+  never included.
+- `feedback` moved from the Search help group to Maps and data.
 
 ## 1.1.1 - 2026-10-22
 

Cargo.lock

@@ -119,6 +119,12 @@ terminal-colorsaurus = "1"
 # a signal handler takes `unsafe` this crate does not have. Installed by
 # that command only; every other command keeps the default.
 ctrlc = { version = "3", features = ["termination"] }
+# Reads the specs' Markdown descriptions for `--help`: the opening prose
+# only, with its inline markup rendered rather than printed. A parser rather
+# than pattern matching, because stripping markers by hand is what turned
+# the code spans `and` and `x` into "and or x". Default features off: they
+# are the HTML renderer and a command-line binary.
+pulldown-cmark = { version = "0.13", default-features = false }
 
 [target.'cfg(unix)'.dependencies]
 # For `workflow run`: passing a SIGTERM on to the running step, which a

Cargo.toml

@@ -58,8 +58,7 @@ paths:
             live traffic), `mapbox/driving`, `mapbox/walking`, or
             `mapbox/cycling` are documented, but not necessarily
             exhaustive: some accounts have additional profiles of their
-            own. Sent exactly as typed; the API is the authority on
-            whether a value is valid, not this description.
+            own. Any other value is sent as typed.
           schema:
             type: string
             minLength: 1
@@ -251,8 +250,8 @@ paths:
           required: false
           description: >-
             Zero-based indices into `coordinates` marking which ones get
-            their own arrival instruction — must include `0` and the last
-            index. Requires `steps=true`.
+            their own arrival instruction, semicolon-separated — must
+            include `0` and the last index. Requires `steps=true`.
           schema:
             type: string
           example: "0,2"
@@ -292,12 +291,6 @@ paths:
         - name: "alley_bias"
           in: query
           required: false
-          # Content before the profile note, not after: `first_sentence` in
-          # `src/main.rs` cuts a `--help` line at the first `.`, and
-          # `` `mapbox/driving` only. `` — a real sentence on its own — was
-          # eating everything that followed it. `--schema` and
-          # `docs/commands.md` show the description in full either way —
-          # this ordering is only for the one-line case.
           description: >-
             Bias the route against (negative) or toward (positive) alleys,
             -1 to 1. `mapbox/driving` only.
@@ -352,22 +345,29 @@ paths:
             type: number
             minimum: 0
             maximum: 100
+        # One value per coordinate, not one switch: a lone `true` with two
+        # coordinates is a 422 ("one entry per coordinate, separated by
+        # ';'"), verified against production on 2026-10-23.
         - name: "snapping_include_closures"
           in: query
           required: false
           description: >-
-            Allow snapping to roads carrying a live-traffic closure.
-            `mapbox/driving-traffic` only.
+            Whether each coordinate may snap to a road carrying a live-traffic closure —
+            `true` or `false` per coordinate, semicolon-separated, with an
+            empty entry to skip one (`true;;false`). `mapbox/driving-traffic`
+            only.
           schema:
-            type: boolean
+            type: string
         - name: "snapping_include_static_closures"
           in: query
           required: false
           description: >-
-            Allow snapping to roads carrying a long-term closure.
-            `mapbox/driving-traffic` only.
+            Whether each coordinate may snap to a road carrying a long-term closure —
+            `true` or `false` per coordinate, semicolon-separated, with an
+            empty entry to skip one (`true;;false`). `mapbox/driving-traffic`
+            only.
           schema:
-            type: boolean
+            type: string
         - name: "walking_speed"
           in: query
           required: false

custom-openapi/directions/openapi/directions.yaml

@@ -26,8 +26,8 @@ paths:
         Every feedback item on the account, oldest received first by
         default — filterable by id, status, category, a free-text search
         phrase, trace id, or a time window on when it was created,
-        received, or last updated. Paginated with `--after`/`start_cursor`/
-        `end_cursor` the way every other listing on this CLI is.
+        received, or last updated. Paginated: pass a response's
+        `end_cursor` to `--after` for the next page.
       parameters:
         - name: "access_token"
           in: query
@@ -111,10 +111,6 @@ paths:
             the feedback.
           schema:
             type: string
-        # "ISO 8601" trails each of these six rather than leads them:
-        # `first_sentence` in `src/main.rs` cuts a `--help` line at the
-        # first `.`, and "ISO 8601." on its own left `--help` showing just
-        # that. `--schema` and `docs/commands.md` still show each in full.
         - name: "created_before"
           in: query
           required: false
@@ -207,11 +203,19 @@ paths:
                   description: >-
                     The feedback category. Not checked against a list;
                     `feedback list` shows the ones already in use.
+                # The API accepts any coordinates here and never returns the
+                # feature, so the order is GeoJSON's by definition rather than
+                # by test: on 2026-10-23 both [95, 24.94] and [24.94, 95] were
+                # accepted. docs.mapbox.com says [latitude, longitude].
                 feature:
                   type: object
                   description: >-
                     A GeoJSON Feature the feedback is about, with coordinates
                     in GeoJSON's [longitude, latitude] order.
+                # Verified against production on 2026-10-23: bare base64 is a
+                # 400 ("Image must be a base64 data URI of one of: image/png,
+                # image/jpeg, image/jpg"), a data URI is accepted.
+                # docs.mapbox.com says plain base64, which is wrong.
                 screenshot:
                   type: string
                   description: >-

custom-openapi/feedback/openapi/feedback.yaml

@@ -47,8 +47,7 @@ paths:
             live traffic), `mapbox/driving`, `mapbox/walking`, or
             `mapbox/cycling` are documented, but not necessarily
             exhaustive: some accounts have additional profiles of their
-            own. Sent exactly as typed; the API is the authority on
-            whether a value is valid, not this description.
+            own. Any other value is sent as typed.
           schema:
             type: string
             minLength: 1
@@ -113,14 +112,6 @@ paths:
         - name: "denoise"
           in: query
           required: false
-          # Spelled "0 to 1"/"1", not "0.0-1.0"/"1.0": `first_sentence` in
-          # `src/main.rs` cuts a `--help` line at the first `.`, and this
-          # value's own bounds are the first digits that would appear no
-          # matter where in the sentence they sit, so a literal decimal
-          # point anywhere before the end truncates it — not just at the
-          # front, the way `directions.yaml`'s own fix assumed. `--schema`
-          # and `docs/commands.md` still show the fuller description below
-          # in full, decimals included.
           description: >-
             A larger value removes more of the smaller contours, 0 to 1,
             defaulting to 1. A value of 1 returns only the largest contour

custom-openapi/isochrone/openapi/isochrone.yaml

@@ -49,8 +49,7 @@ paths:
             live traffic), `mapbox/driving`, `mapbox/walking`, or
             `mapbox/cycling` are documented, but not necessarily
             exhaustive: some accounts have additional profiles of their
-            own. Sent exactly as typed; the API is the authority on
-            whether a value is valid, not this description.
+            own. Any other value is sent as typed.
           schema:
             type: string
             minLength: 1
@@ -95,9 +94,10 @@ paths:
           in: query
           required: false
           description: >-
-            Which side of the road to approach each waypoint from,
-            semicolon-separated — `unrestricted` or `curb` per coordinate.
-            Requires `--steps`.
+            Which side of the road to approach each waypoint from, one per
+            waypoint (every coordinate unless `--waypoints` picks some),
+            semicolon-separated — `unrestricted` or `curb`. Requires
+            `--steps`.
           schema:
             type: string
         - name: "geometries"

custom-openapi/map-match/openapi/map-match.yaml

@@ -46,13 +46,12 @@ paths:
           # named beyond `driving`/`walking`/`cycling`. Same fix as
           # `directions.yaml`'s `profile`.
           description: >-
-            The routing profile. `mapbox/driving-traffic` (accounts for
-            live traffic, caps at 10 coordinates instead of 25),
-            `mapbox/driving`, `mapbox/walking`, and `mapbox/cycling` are
+            The routing profile — `mapbox/driving-traffic` (accounts for
+            live traffic, 10 coordinates at most instead of 25),
+            `mapbox/driving`, `mapbox/walking`, or `mapbox/cycling` are
             documented, but not necessarily exhaustive: some accounts have
-            additional profiles of their own. Sent exactly as typed, the
-            API is the authority on whether a value is valid, not this
-            description.
+            additional profiles of their own. Any other value is sent as
+            typed.
           schema:
             type: string
             minLength: 1
@@ -100,17 +99,18 @@ paths:
             filtering the road segments considered by direction of travel.
           schema:
             type: string
+        # Semicolons, never commas: verified against production, a
+        # comma-separated list is a 422 ("may be \"all\" or
+        # semicolon-separated list of 0-based integer indices"). Other index
+        # lists on the Navigation commands vary per parameter, so this one
+        # says so explicitly.
         - name: "sources"
           in: query
           required: false
           description: >-
-            Which coordinates act as sources (matrix rows) — `all`
-            (the default), or zero-based indices, semicolon-separated.
-            Verified against production: a comma-separated list is a 422,
-            "may be \"all\" or semicolon-separated list of 0-based integer
-            indices" — unlike every other index/value list on this CLI's
-            Navigation commands, which are comma- or semicolon-separated
-            per parameter but never comma where this API wants semicolons.
+            Which coordinates act as sources (matrix rows) — `all` (the
+            default), or zero-based indices separated by semicolons
+            (`0;2`), not commas.
           schema:
             type: string
           example: "0;2"
@@ -119,18 +119,14 @@ paths:
           required: false
           description: >-
             Which coordinates act as destinations (matrix columns) — `all`
-            (the default), or zero-based indices, semicolon-separated. See
-            `sources` above — comma-separated is a 422 here specifically.
+            (the default), or zero-based indices separated by semicolons
+            (`0;2`), not commas.
           schema:
             type: string
           example: "1;3"
         - name: "fallback_speed"
           in: query
           required: false
-          # Content before "Legacy", not after: `first_sentence` in
-          # `src/main.rs` cuts a `--help` line at the first `.`, and
-          # "Legacy." on its own left `--help` showing just that word.
-          # `--schema` and `docs/commands.md` still show it in full.
           description: >-
             Replaces a `null` (unreachable) cell with a straight-line
             estimate at this speed, km/h, rather than leaving it `null`.

custom-openapi/matrix/openapi/matrix.yaml

@@ -36,12 +36,15 @@ paths:
     post:
       operationId: batch
       summary: Full detail for one or more places.
+      # `places` has no subcommand, so this, not `info.description`, is
+      # what `mapbox places --help` shows. It always sends the batch
+      # request, one id or many, so there is no get/batch choice to offer.
       description: >-
-        Each `mapbox_id` comes from a Search Box API result (`search
-        forward`/`reverse`/`category`) — this API does not look places up
-        by name or location itself. Always sends a batch request, one id
-        or many, so a single id reads the same way, no `get`/`batch`
-        choice to make. Up to 100 ids in one call.
+        Full detail for one or more places — hours, phone, website,
+        photos, address, coordinates — by the `mapbox_id`s a Search Box
+        result returned (`search forward`, `reverse` or `category`). Up to
+        100 ids per call. Public Preview, with a 1000-records-per-account
+        monthly quota.
       parameters:
         - name: "access_token"
           in: query