dekart-cli

Dekart MCP wrapper for your AI agent to create maps from SQL query results.

Works best with the geosql skill — it writes the SQL, this CLI renders the map.

Works with any Dekart instance:

• Dekart Cloud (SaaS, default)
• Local (Docker) (on your machine with persistent local data)
• Self-hosted (your own URL)

Init

pip install dekart
dekart init

dekart init walks you through:

1. Picking the instance (Cloud / self-hosted / localhost).
2. Optionally enabling BigQuery passthrough with an authenticated local gcloud user.
3. Installing Playwright and Chromium for local snapshots unless you pass --local-snapshot skip.
4. Authorizing the CLI in your browser.

The browser opens automatically as the final setup step. Pass --no-browser to print the authorization URL without opening it.

To switch instance later:

dekart config --url <your-url>
dekart init

Config and token: ~/.config/dekart/.

BigQuery passthrough requires the Google Cloud CLI. The CLI prefers the active authenticated non-service-account gcloud user, uses the only available user, or asks you to choose when several are available. The gcloud and Dekart emails may differ. The CLI stores only that account and the selected Dekart URL; it mints short-lived tokens when needed and keeps them in process memory. Run dekart init --bigquery-passthrough enable to enable it later, or use --bigquery-passthrough disable to remove the local binding.

Version telemetry

The CLI sends a best-effort version check with its package version and an opaque random installation ID. GeoSQL and Dekart CLI share the ID at ${XDG_CONFIG_HOME:-~/.config}/dekart/installation_id; deleting that file resets it. Set DO_NOT_TRACK=1 (or DNT=1) to disable the version check before an ID is created. CI sends a reserved non-persisted test ID.

Local Dekart with Docker

Choose Local during dekart init, or manage it directly:

dekart local up
dekart local status
dekart local status --json
dekart local down
dekart local remove

The CLI uses a labeled container named dekart-local and a labeled persistent Docker volume named dekart-local-data. down stops the container without deleting the container or volume. The next up recreates the container from the latest image while preserving the data volume. remove asks for confirmation, then removes both the container and its data volume; use remove --force to skip confirmation. If port 8080 is occupied by another service, the CLI selects the first free port through 8099 and saves that URL before authorization begins.

When the CLI starts or stops Docker, it prints Executing: <docker command> before running it. You can also choose “I will start or connect to Dekart myself” during dekart init; the CLI prints a simple standalone docker run command without CLI labels, container names, or volumes, then asks for the Dekart URL.

The initial Docker commands are:

docker pull dekartxyz/dekart:latest
docker run -d \
  --name dekart-local \
  --label xyz.dekart.cli.managed=true \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v dekart-local-data:/dekart/data \
  dekartxyz/dekart:latest

The CLI never starts, stops, removes, or replaces a same-name container without its management label. Docker is not installed or started automatically; dekart init gives platform-specific instructions when it is unavailable.

Enable local snapshot

Local headless renderer for fast PNG snapshots without a round-trip to the server:

dekart snapshot-local install

Manage:

dekart snapshot-local status
dekart snapshot-local uninstall          # remove renderer
dekart snapshot-local uninstall --purge  # also remove its browser cache

When local snapshot is enabled, dekart snapshot --report-id <id> --out ./snap.png uses it automatically. Pass --remote-only to force server-side rendering.

Agents can request a specific snapshot viewport without editing the saved map:

dekart snapshot --report-id <id> --zoom 12 --lat 52.52 --lon 13.405 --out ./snap.png

--zoom accepts 0 through 24. Use --lat and --lon together.

Include the charts pane when the report has widgets. A wider viewport leaves more room for the map:

dekart snapshot --report-id <id> --include-widgets --width 1920 --out ./snap-with-charts.png

When the server provides a verified render-URL lifetime and an established local page or browser target closes unexpectedly, the CLI retries once with a fresh browser and the same per-operation timeout. Browser launch failures and normal timeouts are not retried; increase a normal timeout explicitly, for example with --timeout 180. Remote capture is never selected automatically. Use --remote-only when the configured Dekart instance provides a remote snapshot endpoint.

Run Prepared Query And Download Rows

Run an already-prepared Dekart query, wait for the job, and save result rows:

dekart run-query --query-id <query-id> --out-dir ./results --wait --json

Pass saved report parameter values as JSON when needed:

dekart run-query --query-id <query-id> --params-json '{"row_limit":"10"}' --out-dir ./results --json

Queries wait by default. Connection queries run and download their warehouse result as before. On a compatible Dekart server, DuckDB queries download their pinned file or warehouse inputs, install the server-required signed core or community extensions, execute the prepared program locally, and save <query-job-id>.parquet. --no-wait returns pending metadata without downloads when a DuckDB warehouse input is still running. Use --json for machine-readable metadata or --print for rows. A DuckDB version mismatch emits a warning to stderr and continues best effort. The first local DuckDB run may need internet access for required extensions such as H3; later runs reuse DuckDB's standard cache.

Resolve a report URL explicitly from a report id:

dekart report-url --report-id <report-id>
dekart report-url --report-id <report-id> --json

Preview Downloaded Rows

Preview a CSV or parquet file produced by dekart run-query:

dekart preview ./results/<result-file>.parquet --limit 20
dekart preview ./results/<result-file>.parquet --schema

Preview output is tab-separated. Parquet and CSV previewing use the bundled DuckDB Python dependency.

Links

• Dekart: dekart.xyz
• geosql skill: github.com/dekart-xyz/geosql