Metadata-Version: 2.5
Name: dekart
Version: 0.19.0
Summary: Dekart CLI for auth, MCP tool discovery, calls, and file upload flows.
Author: Dekart XYZ
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.8
Requires-Dist: duckdb==1.2.2; python_version < '3.9'
Requires-Dist: duckdb==1.4.3; python_version >= '3.9'
Description-Content-Type: text/markdown

# dekart-cli

[Dekart](https://github.com/dekart-xyz/dekart) MCP wrapper for your AI agent to create maps from SQL query results.

Works best with the [geosql](https://github.com/dekart-xyz/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

```bash
pip install dekart
dekart init
```

`dekart init` walks you through:

1. Picking the instance (Cloud / self-hosted / localhost).
2. Authorizing the CLI in your browser.
3. Optionally enabling BigQuery passthrough with your local `gcloud` user login.
4. Optionally enabling local snapshots.

To switch instance later:

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

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

BigQuery passthrough requires the Google Cloud CLI. For signed-in Dekart users,
the same user account must be authenticated in `gcloud`; anonymous self-hosted
instances prompt you to choose an authenticated `gcloud` user account. 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:

```bash
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:

```bash
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:

```bash
dekart snapshot-local install
```

Manage:

```bash
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:

```bash
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.

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:

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

Pass saved report parameter values as JSON when needed:

```bash
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:

```bash
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`:

```bash
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](https://dekart.xyz)
- geosql skill: [github.com/dekart-xyz/geosql](https://github.com/dekart-xyz/geosql)
