Command-line client¶
The official GeoJibe CLI is an HTTP client for an existing GeoJibe installation. It does not run Docker, GDAL, DuckDB, QGIS, or a GeoJibe server on your computer.
Package version 0.1.1. The CLI is a thin wrapper around the Python SDK.
Install¶
or
Authenticate¶
Create a token in GeoJibe → Account → API Tokens, then:
Enter the GeoJibe URL (your installation origin, not /api/v1) and the token.
Token input is hidden. On success: Authenticated successfully.
Logout deletes the token stored on this computer. It does not revoke the PAT. Revoke tokens in Account → API Tokens.
Jobs vs Workspaces¶
| Resource | CLI group | Meaning |
|---|---|---|
| Jobs | geojibe jobs |
Persistent automation. Can be scheduled and run repeatedly. |
| Workspaces | geojibe workspace |
Temporary interactive processing. Automatically expire. |
Do not use Job ids with Workspace commands, or the reverse.
Commands¶
geojibe --help
geojibe --version
geojibe auth login|status|logout
geojibe config set-url|set-token|show
geojibe sources list|get|create|delete
geojibe destinations list|get|create|delete
geojibe jobs list|get|run|enable|disable|delete|create|update|runs|retry
geojibe recipes list|get|create|delete
geojibe workspace upload|info|preview|convert|download
geojibe workspace transform get|set|clear|preview
geojibe transformations list|show
--json writes machine-readable JSON to stdout. --quiet / -q reduces
output. --debug prints HTTP method, URL, and status to stderr (never the
token). --insecure disables TLS verification for development certificates
only and is not saved.
The CLI does not invent extra commands for Canvas-only API routes. If a subcommand is not listed here, it is not in 0.1.1.
Configuration¶
config show prints a masked token only.
| OS | Path |
|---|---|
| Linux | ~/.config/geojibe/config.toml ($XDG_CONFIG_HOME if set) |
| macOS | ~/Library/Application Support/geojibe/config.toml |
| Windows | %APPDATA%\geojibe\config.toml |
Automation¶
GEOJIBE_CONFIG_DIR overrides the directory that contains config.toml
(development and tests). It is not required for normal use.
--url and --token override the environment, which overrides saved
configuration.
Sources, Destinations, Recipes, Jobs¶
geojibe sources list
geojibe sources list --json
geojibe sources get <id>
geojibe destinations list
geojibe recipes list
geojibe jobs list
geojibe jobs get <id>
geojibe jobs run <id>
geojibe jobs run <id> --wait
geojibe jobs runs <id>
Create sends the public API body from a JSON file:
geojibe sources create --file source.json
geojibe destinations create --file destination.json
geojibe recipes create --file recipe.json
geojibe jobs create --file job.json
geojibe jobs update <id> --file job.json
{
"name": "Neighborhoods",
"source_id": "…",
"transform_mode": "sql",
"sql": "SELECT * FROM source WHERE population > 1000",
"output_format": "GeoJSON",
"destination_id": "…",
"destination_target": {"schema": "public", "table": "neighborhoods", "write_mode": "replace"},
"schedule": {"kind": "daily", "timezone": "UTC", "hour": 2, "minute": 0}
}
Existing Job JSON without pipeline is unchanged and keeps legacy/inferred
stage presence. To record Canvas stages, send an optional pipeline object:
pipeline |
Meaning |
|---|---|
| omitted | Legacy/inferred behavior (stages stay present) |
{} |
Legacy/inferred behavior (stages stay present) |
explicit false |
That stage is absent |
explicit true |
That stage is present |
Create and update preserve explicit false flags. geojibe jobs get shows
recorded stages when the Job includes pipeline.
geojibe jobs enable <id>
geojibe jobs disable <id>
geojibe jobs retry <id> <run-id>
geojibe jobs delete <id>
geojibe sources delete <id>
geojibe destinations delete <id>
geojibe recipes delete <id>
Stored connector secrets are never displayed.
Temporary Workspace¶
Upload a file, inspect it, preview, transform, convert, and download. Processing stays on the GeoJibe server.
geojibe workspace upload bees.gpkg
geojibe workspace upload bees.gpkg --json
geojibe workspace info <id>
geojibe workspace preview <id> --layer apiary
geojibe workspace preview <id> --layer apiary --spatial
geojibe transformations list
geojibe transformations show buffer
geojibe workspace transform set <id> --file pipeline.json
geojibe workspace transform get <id>
geojibe workspace transform preview <id> --layer apiary
geojibe workspace transform preview <id> --layer apiary --spatial
geojibe workspace convert <id> --format GeoJSON --layer apiary
geojibe workspace download <id> buffered-bees.geojson
geojibe workspace transform clear <id>
--json is the scripting interface. The workspace ID is id:
ID=$(geojibe workspace upload bees.gpkg --json | jq -r '.id')
geojibe workspace preview "$ID" --layer apiary --json
pipeline.json uses the same body as the public Workspace API / Python SDK.
Do not hard-code the catalog; ask the server:
SQL and Python are sibling fields in that file (sql, python), not fake
operation types. The CLI does not execute SQL or Python locally.
--spatial prints a geometry/CRS summary. It does not render a map. Use
--json when you need the GeoJSON FeatureCollection.
--file - reads a pipeline from stdin:
Quiet mode prints only the workspace id on upload:
Python¶
The same package is the SDK:
from geojibe import GeoJibe
client = GeoJibe(url="https://<host>", token="gjp_...")
ws = client.workspaces.upload("roads.gpkg")
See Python SDK.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Failure (including a finished Run with status failed) |
| 2 | Usage / local config |
| 3 | Authentication (401 / missing credentials) |
| 4 | Authorization (403 / missing PAT scope) |
| 5 | Not found (404) |
| 6 | Validation (400 / 409 / 422) |
| 7 | Network (DNS, connection refused, TLS, timeout) |
| 8 | GeoJibe server error (5xx) |