---

name: cli-data-and-network description: "Diagnose pyproj installation and native PROJ runtime state, use the CLI safely, select PROJ data directories, and plan network-backed transformation-grid discovery without hiding downloads or mutating state unexpectedly." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

CLI, data, and network operations

Use this route when the task is about installing or importing pyproj, checking its Python/PROJ versions, reading pyproj CLI help, selecting PROJ data locations, enabling network access, or finding and synchronizing transformation grids. Start with the read-only diagnostic when the runtime is uncertain: scripts/diagnose_pyproj.py.

Route and boundaries

• Installation prerequisites, CLI syntax, data-directory precedence, network policy, and grid synchronization belong here.
• CRS construction/database questions go to ../crs-and-database/SKILL.md.
• Coordinate operations, missing-grid operation selection, and transform accuracy go to ../coordinate-transformations/SKILL.md.
• Ellipsoid distances, azimuths, and areas go to ../geodesic-calculations/SKILL.md.
• Maintainer CI, wheel/release automation, and build-pipeline edits are out of scope. Source-build prerequisites are documented only to diagnose an install.

Minimal operating sequence

1. Run python -m pyproj --help (or the installed pyproj --help) and the bundled diagnostic. Confirm that import succeeds, runtime and compiled PROJ versions are compatible, and a valid directory containing proj.db is selected.
2. For a detailed report, run python -m pyproj -v or pyproj -v. Compare PROJ (runtime), PROJ (compiled), data dir, database versions, Python, and dependency information. Do not treat a version report as proof that a particular grid is installed.
3. Decide whether the job needs no grids, a bounded pre-download, or PROJ network access. Keep network disabled unless the task explicitly permits remote resources, and never replace this decision with an automatic wrapper.
4. Before sync, choose an explicit target and a filter. Prefer pyproj sync --list-files for inspection, while remembering that obtaining the grid manifest may itself fetch files.geojson when it is absent or stale. Use an explicit directory and review the listed names before any download.
5. If a failure mentions SQLite, proj.db, a missing data directory, or a runtime/compiled mismatch, follow references/troubleshooting.md before retrying a transformation.

Operating contracts

• Inputs: an installed package or source-build request; optional CLI arguments; optional PROJ_DATA/legacy PROJ_LIB, PROJ_NETWORK, and CA bundle settings; and, for grid discovery, a source id, filename, area of use, or geographic west,south,east,north bounding box.
• Outputs: help/version text; a selected data-directory string; a boolean network state; or a tuple of GeoJSON feature dictionaries from pyproj.sync.get_transform_grid_list. A sync download writes a manifest and grid files only where the selected CLI target permits it.
• Validation: import must complete; get_data_dir() must resolve to a path containing proj.db; runtime and compiled PROJ versions should match for a coherent install; filters must be narrow enough to review; checksums must pass when the sync implementation supplies one.
• Recovery: isolate PROJ_DATA/PROJ_LIB and competing installations, select one coherent data tree, restart the Python process after changing environment variables, then rerun the read-only checks. For network or checksum failures, preserve the original partial-download cleanup behavior and retry only after checking target writability, CA certificates, network permission, and available disk space.

Linked depth

• CLI command reference covers parser behavior, arguments, outputs, and side-effect boundaries.
• Installation and runtime covers wheels/conda/source prerequisites, version inspection, data paths, and network APIs.
• Grid synchronization covers manifest filtering, antimeridian boxes, download policy, and safe preflight.
• Troubleshooting covers native mismatches, SQLite errors, invalid paths, certificates, and recovery ordering.

This route deliberately does not download grids itself. The bundled diagnostic is read-only and has safe defaults; a human or calling workflow must explicitly approve any sync download.