CLI: invalid --geom/--geometry value prints a traceback and exits 1 instead of a usage error

Bắt đầu với Geometry.convert trong planet/cli/types.py và check_geom trong planet/cli/validators.py; sau đó đọc test_item_coverage_invalid_geometry trong tests/integration/test_data_cli.py. Dùng các bài kiểm thử CLI để tái hiện tệp không hợp lệ, JSON sai định dạng, GeoJSON không hợp lệ và giá trị rỗng. Hoàn thành khi các giá trị không hợp lệ tạo ra lỗi sử dụng rõ ràng với mã thoát dự kiến trên các lệnh được liệt kê và các bài kiểm thử hồi quy đều đạt.

Expected behavior
An invalid --geom or --geometry value gives a one-line usage error and exit code 2. planet data filter --geom nofile.json already does this for a missing file and for malformed JSON:

Error: Invalid value for '--geom': File not found.

DESIGN.md lists exit code 2 for "invalid syntax or unknown or invalid parameter".

For GeoJSON that parses but fails validation (bad coordinate, open ring), data filter prints a clean one-line Error: Each linear ring must contain at least 4 positions but exits 1, because it validates inside the command body (translate_exceptions). Whether that case should exit 2 or 1 is a design choice. The change proposed below makes it exit 2, matching the other invalid-parameter errors, but a clean one-line error is the main point.

Actual behavior (describe the problem)
A value that is not a valid inline geometry prints a Python traceback (38 to 51 lines, depending on the input) and exits 1. This happens for a mistyped file name, a malformed inline JSON string, and GeoJSON that fails validation (bad coordinate, open ring). All eight commands that take the option do it: data search, data search-create, data search-update, data item-coverage, subscriptions request-catalog, subscriptions request-source, mosaics search and mosaics download.

For a mistyped file name or malformed JSON, the last line is also wrong: FeatureError: Expected scheme pl:features. No feature reference was passed.

An empty value (--geom "", for example from an unset shell variable) is dropped. It parses to None, so data search sends no geometry filter. I checked this by parsing the arguments only; nothing was sent. subscriptions request-catalog --geometry "" fails with TypeError: 'NoneType' object is not subscriptable.

Cause:

1. Geometry.convert in planet/cli/types.py tries JSON(), then falls back to CommaSeparatedString(), which accepts any non-empty string. The real error ("File not found", "JSON string is not valid JSON") is dropped and the string is treated as a feature reference. If both types fail, it returns None. The fallback was added in 0b2ce07 ("Support feature refs as strings"), first released in 2.10.0.
2. check_geom in planet/cli/validators.py runs as a click callback while arguments are parsed. translate_exceptions wraps only the command body, so the FeatureError or GeoJSONError it raises is never turned into a click error.

test_item_coverage_invalid_geometry in tests/integration/test_data_cli.py does not catch this. It asserts exit_code == 1, which CliRunner also reports for an unhandled exception.

Catching PlanetError in check_geom and raising click.BadParameter removes the traceback. Falling back to feature references only when the value starts with pl: restores the real file and JSON messages and rejects the empty value. That test then needs exit_code == 2, like the other invalid-parameter tests. With that change on main, all eight commands print the usage error and exit 2, and pytest tests passes (919 tests).

I can send a PR.

Related Issues
None found. #337 (robust GeoJSON validation) is related but asks for more validation, not for these errors to be reported cleanly. #384 (closed) concluded that the exit codes in DESIGN.md are adequate.

Workaround
The command fails before any request is sent. For a GeoJSON error, the last line of the traceback is correct. For a file or JSON error it is misleading, so check the file name and JSON first. planet data filter --geom <file> reports file and JSON errors correctly.

Minimum, Complete, Viable Code Sample
No API key or network is needed. It fails while arguments are parsed.

> planet data search PSScene --geom nofile.json
Traceback (most recent call last):
  File ".../bin/planet", line 12, in <module>
    sys.exit(main())
  ...
  File ".../planet/cli/validators.py", line 26, in check_geom
    geoms.update(geojson.as_geom_or_ref(geom))
  File ".../planet/geojson.py", line 60, in as_geom_or_ref
    return as_ref(data)
  File ".../planet/geojson.py", line 102, in as_ref
    data = convert_ref_to_dict(data)
  File ".../planet/geojson.py", line 91, in convert_ref_to_dict
    if validate_ref(data):
  File ".../planet/geojson.py", line 75, in validate_ref
    raise FeatureError("Expected scheme pl:features")
planet.exceptions.FeatureError: Expected scheme pl:features
> echo $?
1

Last line of the output for other inputs:

> planet data search PSScene --geom '{"type": "Polygon"'
planet.exceptions.FeatureError: Expected scheme pl:features
> planet data search PSScene --geom '{"type":"Point","coordinates":[1,"a"]}'
planet.exceptions.GeoJSONError: Not a GeoJSON coordinate value
> planet data search PSScene --geom '{"type":"Polygon","coordinates":[[[0,0],[1,0],[1,1]]]}'
planet.exceptions.GeoJSONError: Each linear ring must contain at least 4 positions
> planet subscriptions request-catalog --item-types PSScene --asset-types ortho_analytic_4b --geometry nofile.json --start-time 2022-01-01
planet.exceptions.FeatureError: Expected scheme pl:features
> planet subscriptions request-catalog --item-types PSScene --asset-types ortho_analytic_4b --geometry '' --start-time 2022-01-01
TypeError: 'NoneType' object is not subscriptable
> planet data filter --geom nofile.json
Error: Invalid value for '--geom': File not found.

Environment Information

• Operation System Information: macOS-27.0.1-arm64-arm-64bit
• Python version: 3.12.15 (main, Oct 9 2026, 15:10:57) [Clang 22.1.3 ]
• Planet package version: planet, version 3.7.0 (PyPI wheel, and main at a6c66cb, which is the 3.7.0 tag). click 8.5.0.

Installation Method

• pip wheel (uv pip install planet) and from source (pip install -e .)

Found and reproduced with an AI coding assistant, then checked by me.