# KI-CLI und offizieller Skill

> Nutzen Sie die DuckDB-SQL-CLI von DuckLocal mit KI-Agenten: Schemas lokaler Dateien prüfen, eine Anweisung ausführen und begrenztes JSON ohne GUI oder Server zurückgeben.

Source: https://ducklocal.app/docs/de/cli

Eine aufgabenorientierte Übersicht finden Sie unter [SQL für KI-Agenten auf
lokalen Daten](https://ducklocal.app/use-cases/ai-agent-sql/). Diese Seite ist
die vollständige Referenz zu Befehlen und Ausgabe.

## Ohne Fenster ausführen

`ducklocal --help` listet zehn Unterbefehle:

| Befehl | Wirkung |
| --- | --- |
| `ducklocal query` | Eine SQL-Anweisung ausführen und das Ergebnis als JSON ausgeben |
| `ducklocal schema` | Auflisten, was sich abfragen lässt, mit Spalten; `--stats` für die Spaltenstatistik einer Relation |
| `ducklocal open` | SQL, ein Dashboard oder Daten im laufenden Fenster zeigen; `--state` liest zurück, was es zeigt |
| `ducklocal check` | Ein `.dash`-Dashboard prüfen |
| `ducklocal metrics` | Die Metriken eines semantischen Modells auflisten; mit `compile` oder `query` kompilieren oder abfragen |
| `ducklocal comments` | Review-Kommentare lesen und beantworten, die Personen an einem Dashboard hinterlassen haben |
| `ducklocal propose` | Eine Dashboard-Änderung vorschlagen, die die Person prüfen und übernehmen kann |
| `ducklocal project` | Einen portablen Analyseordner und seine Anforderungen prüfen; `relink` korrigiert verschobene Pfade |
| `ducklocal session` | Zurücklesen, wie eine Analyse dorthin gelangt ist, wo sie ist |
| `ducklocal presence` | Zeigen, wer an einem offenen Dashboard arbeitet und wo eine Bearbeitung landen wird |

`ducklocal lsp`, der Language Server, den Editoren für `.dash`-Dateien starten,
und `ducklocal profile`, der alte Alias für `schema --stats`, funktionieren
weiterhin, fehlen aber in `--help`.

`propose`, `project` und `session` sowie die Optionen `--restricted`, `--wait`
und `--if-revision` sind in 0.4.0 hinzugekommen und werden in
[Agent-Workflows](agent-workflows.md) beschrieben. `metrics` und `--format html`
sind neuer als 0.4.1: Sie sind auf dem Branch `main` und erscheinen mit dem
nächsten Release. `metrics` wird in [Semantische Metriken](metrics.md)
beschrieben.

`ducklocal query` führt SQL aus, ohne die GUI, den Verlauf, registrierte Dateien,
Spracheinstellungen oder die globale GUI-Verbindung zu initialisieren. Jeder
Aufruf erstellt eine eigene Verbindung. Wenn Sie DuckLocal ohne Befehle aufrufen
– oder nur mit Dateipfaden, Ordnern und Glob-Mustern –, öffnet sich die normale
GUI. Um einen GUI-Pfad zu öffnen, dessen Name mit einem Befehl übereinstimmt
(`query`, `schema`, `open`, `check`, `metrics`, `comments`, `propose`, `project`,
`session`, `presence`, `profile` oder `lsp`), stellen Sie `./` voran, etwa
`./query`.

## Den Befehl installieren {#get-the-command}

DuckLocal unterstützt macOS 12+ auf Apple Silicon, Windows (x86_64) und Linux
(x86_64). Die CLI läuft direkt aus der Anwendungsdatei, Sie brauchen also keine
separate DuckDB-CLI.

Am schnellsten landet der Befehl über die App auf Ihrem PATH (ab 0.1.1): Öffnen
Sie **Befehlszeile & KI…** – die Roboter-Schaltfläche in der Titelleiste oder
das DuckLocal-Menü – und klicken Sie auf **Befehl installieren**. Derselbe
Dialog installiert den Skill für KI-Agenten; siehe
[Den offiziellen Skill installieren](#install-the-official-skill). Wenn Sie die
Installation überspringen, rufen Sie die ausführbare Datei an ihrem Ort auf:

```bash
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --help
```

Aus einem Source-Checkout baut `cargo build --locked`
`./target/debug/ducklocal`. Die Beispiele unten setzen voraus, dass `ducklocal`
auf Ihrem PATH liegt. Ältere Releases haben möglicherweise kein `query`; prüfen
Sie zuerst `--help`. JSON- und Parquet-Unterstützung ist eingebaut und wird
nicht zur Abfragezeit heruntergeladen.

## Abfrageoptionen {#query-options}

```bash
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"
```

- Genau eines von `--sql SQL` und `--sql-file FILE` ist erforderlich. Dateien
  müssen UTF-8 sein; `-` liest von stdin. Das SQL muss genau eine Anweisung
  enthalten. Der Parser von DuckDB prüft das, bevor die Zieldatenbank geöffnet
  oder irgendetwas ausgeführt wird; Kommentare, Semikolons in Anführungszeichen
  und abschließende Semikolons sind in Ordnung. Skripte werden abgelehnt, nicht
  teilweise ausgeführt.
- `--database PATH` öffnet eine **vorhandene Datei, standardmäßig
  schreibgeschützt**. Ohne diese Option entsteht eine frische
  In-Memory-Datenbank. `--read-write` erfordert `--database` und erlaubt
  ausdrücklich Schreibzugriffe und das Anlegen einer Datenbank (nicht der
  übergeordneten Ordner). Datenbankfehler fallen nie auf den Speicher zurück.
  Wenn DuckDB eine Datei ablehnt, beginnt die Fehlermeldung mit dem Grund, den
  DuckLocal aus dem Dateikopf liest – von einer neueren DuckDB geschrieben, eine
  Datei aus der v0.9-Zeit, eine SQLite-Datei oder überhaupt keine Datenbank –
  und damit, was stattdessen auszuführen ist (bei einer neueren Datei die Kopie
  per `ATTACH … (STORAGE_VERSION)` / `COPY FROM DATABASE` für jenes Release;
  bei SQLite das `ATTACH`, das sie liest), noch vor DuckDBs eigener Meldung.
- `--limit N` ist eine positive Ganzzahl, standardmäßig 1000, und begrenzt die
  zurückgegebenen Zeilen. Zusätzlich gilt ein Budget von 2.000.000 Zellen. Nach
  der Grenze zählt die CLI bis zu 100.000 weitere Zeilen, ohne deren Werte zu
  kodieren, und meldet `total_rows` und `total_rows_exact`. Das begrenzt die
  Ausgabe, nicht die Berechnung oder den Speicher: Sortierungen und Aggregate
  können weiterhin die gesamte Eingabe verarbeiten. Ein Ausführungsfehler nach
  der Ausgabegrenze lässt den Befehl trotzdem scheitern.
- `--format json` (der Standard) ist der unten beschriebene Vertrag.
  `--format md` gibt dasselbe Ergebnis als Markdown-Tabelle aus, für ein
  Dokument oder einen Agenten, der sie liest. `--format html` gibt es als eine
  in sich geschlossene Webseite aus; siehe [HTML-Ausgabe](#html-output). Sonst
  ändert sich nichts:
  dasselbe SQL, dieselben Grenzen, dieselben Fehler.
- Wiederholte oder unbekannte Flags, fehlende Werte, leeres SQL und ungültige
  Limits sind Fehler. Optionen verwenden getrennte Werte, nicht
  `--flag=value`. Relative Pfade werden relativ zum Arbeitsverzeichnis des
  Prozesses aufgelöst, nicht zum Verzeichnis der SQL-Datei. Shell-Pfade in
  Anführungszeichen setzen; innerhalb von SQL Apostrophe verdoppeln
  (`'O''Brien.csv'`). SQL-Bezeichner stehen in doppelten Anführungszeichen.

**Schreibgeschützt ist keine Dateisystem- oder Netzwerk-Sandbox.** SQL wie
`COPY` kann Dateien schreiben, auch wenn die Datenbank schreibgeschützt ist.
Geben Sie Ausgabepfade, Überschreibungen, Datenbankänderungen, die Installation
von Erweiterungen und externen Zugriff vor der Ausführung frei. DuckLocal
installiert Erweiterungen nicht automatisch und wiederholt Vorgänge nicht.
Ausdrückliches `INSTALL`/`LOAD`-SQL bleibt mit Freigabe möglich; installierte
Erweiterungen können automatisch geladen werden. Ein gescheiterter Befehl kann
bereits Nebenwirkungen gehabt haben (etwa vor einem Ausgabefehler); prüfen Sie
das Ziel, bevor Sie es erneut versuchen.

### Markdown-Ausgabe

`--format md` ist eine Darstellung, kein zweiter Vertrag: Die Werte sind die aus
dem JSON, geschrieben so, wie das Ergebnisraster sie zeigt.

| Wert | Dargestellt als |
| --- | --- |
| `NULL` | `NULL` |
| Ganze Zahl, Dezimalzahl, Float | genau die Ziffern, die der Wert trägt – ein `DECIMAL(38,10)` behält seine Skala, `NaN`/`inf`/`-inf` werden ausgeschrieben |
| `DATE` | `YYYY-MM-DD` |
| `TIMESTAMP` | `YYYY-MM-DD HH:MM:SS[.fffffffff]`, mit dem Bruchteil nur, wenn der Wert einen hat, und mit so vielen Ziffern, wie er hat. Es wird keine Zeitzone angehängt; `--format json` behält den Rohzähler |
| `TIME` | `HH:MM:SS[.ffffff]` |
| `INTERVAL` | wie DuckDB ihn schreibt: `1 month 2 days 00:00:00.000003` |
| `BLOB`, `GEOMETRY` | `0x00ff`, bei langer Ausgabe mit `…` gekürzt |
| `LIST`, `STRUCT`, `MAP` | `[1, 2]`, `{x: 1}`, ab 120 Zeichen mit `…` gekürzt |

Ein `|` in einer Zelle wird maskiert und ein Zeilenumbruch wird zu `<br>`, damit
ein Wert die Tabelle nicht sprengt. Auf ein Ergebnis ohne Zeilen folgt
`_0 rows._`, und auf ein Ergebnis, das durch `--limit` oder das Zellenbudget
gekürzt wurde, folgt `_Truncated at 2 of 5000 rows, so this is not the whole
answer._` (`of at least …` jenseits der 100.000-Zeilen-Zählung) – eine Vorschau
soll nicht wie eine vollständige Antwort klingen. Fehler bleiben unverändert:
JSON auf stderr, leeres stdout.

### HTML-Ausgabe {#html-output}

```bash
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html
```

`--format html` schreibt dieselben Werte wie `--format md` als eine einzige
Webseite:

- Zeilen- und Spaltenzahl, die verstrichene Zeit und das SQL hinter dem
  Ergebnis, eingeklappt.
- Die Spaltennamen mit ihren Typen. Zahlen sind rechtsbündig, `NULL`-Werte
  sind markiert.
- Ein Klick auf eine Spaltenüberschrift sortiert; `NULL`-Werte bleiben am Ende.
  Eingaben im Filterfeld behalten nur die passenden Zeilen.
- Ein Ergebnis, das `--limit` oder das Zellbudget gekürzt hat, sagt das, wie in
  Markdown.

Stil und Skript sind eingebettet, und die Seite lädt nichts nach. Sie öffnet
sich also direkt von der Festplatte und lässt sich unverändert veröffentlichen,
etwa auf GitHub Pages. Jede Zelle wird HTML-maskiert.

## Erfassen, was abfragbar ist {#map-what-can-be-queried}

`ducklocal schema` beantwortet „Was gibt es, und welche Spalten hat es?“ in
einem Aufruf, während `DESCRIBE` es Relation für Relation beantwortet. Es ist
das Erste, was ein Agent ausführen sollte.

```bash
ducklocal schema ./data/                          # files, folders, globs
ducklocal schema --database warehouse.duckdb      # tables and views
ducklocal schema warehouse.duckdb --table orders  # one relation, whole
ducklocal schema ./logs/ --full                   # everything, however large
```

PATHs werden so aufgelöst wie beim Ablegen auf das Fenster: die Datendateien
eines Ordners rekursiv (versteckte übersprungen, höchstens 256), die Treffer
eines Glob und eine Datenbankdatei, als wäre sie mit `--database` angegeben.
Zurück kommt ein JSON-Objekt:

```json
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}
```

| Feld | Bedeutung |
| --- | --- |
| `name` | Der Pfad einer Datei wie angegeben (relativ zum Arbeitsverzeichnis, wenn sie darunter liegt), oder der Name einer Tabelle, wie SQL auf dieser Verbindung ihn erreicht: ohne Präfix im Standardschema, sonst `schema.table` |
| `kind` | `file`, `glob`, `table`, `view` oder `workbook` |
| `from` | Das SQL, das es liest, bereit nach `FROM`: ein Pfad in Anführungszeichen oder ein Bezeichner in Anführungszeichen, wo einer nötig ist |
| `rows` | Die Schätzung des Katalogs für eine Tabelle, exakt für Parquet (aus seinem Footer), `null`, wo das Wissen einen Scan erfordern würde – CSV, JSON, Views |
| `column_count`, `columns` | Die Spalten, wie DuckDB sie beschreibt |
| `files` | Bei einem `glob`: wie viele Dateien er trifft |

Ein Glob, dessen Treffer alle dasselbe Format haben, ist eine Relation und wird
so gelesen, wie ein `source` in `.dash` sie liest (`ducklocal schema
'logs/*.csv'`); `--stats` profiliert ihn als eine. Ein Glob über gemischte
Formate und ein Ordner listen ihre Dateien einzeln auf.

Ein kleiner Katalog kommt vollständig zurück (`"detail": "full"`). Ab 12
Relationen oder 400 Spalten ist er stattdessen eine **Zusammenfassung**
(`"detail": "summary"`). Die 5 Relationen mit den meisten Zeilen behalten ihre
Spalten; die übrigen listen Name, Art, Zeilen und Spaltenzahl, und
`without_columns` zählt sie. Für mehr nennt `hint` die beiden Wege: `--table
NAME` für eine Relation (passend über ihren Namen, ihren reinen Tabellennamen
oder den Namen einer Datei) und `--full` für alle. Eine Arbeitsmappe wird mit
ihren `sheets` und ohne Spalten gelistet, da sie keine Tabellenfunktion hat;
`--stats` liest ihr erstes Blatt. Ein PATH, der nicht existiert, oder ein
`--table`, das nichts benennt, ist Exit 2.

Gzip-komprimierter Text wie `.json.gz` und `.csv.gz` ist hier eine Datendatei,
ebenso wie für `source`-Blöcke und das Fenster. Eine Datei, deren Datensätze in
einer einzigen Liste liegen – etwa CloudTrails `{"Records": [...]}` –, kommt mit
einem `hint` zurück: dem SQL, das diese Datensätze als Zeilen liest, weil die
eine Zeile und die eine Spalte sonst nur den Wrapper beschreiben.

## Dateien erkunden und konvertieren

Nachdem bestätigt ist, dass die Datei tatsächlich existiert:

```bash
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"
```

Raten Sie nicht, dass `amount` existiert: Führen Sie zuerst `ducklocal schema`
oder `DESCRIBE` aus. Berechnen Sie vollständige Aggregate in SQL, statt eine
gekürzte Vorschau zu summieren. CLI-Aufrufe teilen weder die registrierten Views
der GUI noch ihre In-Memory-Tabellen untereinander. Persistieren Sie ausdrücklich,
wenn es nötig ist:

```bash
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"
```

Ein Konflikt um die Datenbanksperre ist ein Fehler. Schließen Sie den anderen
Schreiber (auch die GUI) oder verwenden Sie eine freigegebene Kopie; löschen Sie
niemals Sperrdateien und legen Sie nicht stillschweigend eine andere Datenbank
an.

## JSONL und verschachteltes JSON {#jsonl-and-nested-json}

`read_ndjson_objects` ist der Leser für zeilengetrenntes JSON (ein Objekt pro
Zeile, `.jsonl`/`.ndjson`); `read_json`/`read_json_auto` lesen JSON-Dokumente
(ein Array oder ein einzelnes Objekt). Nennen Sie den Leser für eine
JSONL-Datei ausdrücklich, statt sich auf die automatische Erkennung zu
verlassen. `json_extract_string(col, '$.a.b[0].c')` durchläuft einen
verschachtelten Pfad – Objektschlüssel und Array-Indizes – und liefert VARCHAR:

```bash
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"
```

Verwenden Sie stattdessen `json_extract`, wenn das Blatt kein String ist und Sie
es als JSON möchten.

## Spaltenstatistiken

`ducklocal schema --stats` beantwortet die Fragen, die ein Diagramm, eine Skala
und ein Zahlenformat entscheiden, bevor etwas darauf aufgebaut wird. `DESCRIBE`
sagt, dass eine Spalte `DOUBLE` ist; ihre Statistik sagt, dass sie zwei
Nachkommastellen nutzt, dass ihr größter Wert tausendmal so groß wie ihr Median
ist und dass ihre Daten in der Mitte elf Tage überspringen.

```bash
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats
```

`--stats` profiliert eine Relation: die einzige, die die Argumente benennen,
oder die, die `--table` auswählt – zwei oder mehr ohne `--table` ist Exit 2, mit
einem Hinweis darauf. Es lässt sich nicht mit `--full` kombinieren.
`ducklocal profile TARGET [--database PATH]` aus früheren Releases liefert
denselben Bericht und funktioniert weiterhin.

Die Relation ist eine Datendatei – `csv`, `tsv`, `txt`, `parquet`, `json`,
`ndjson`, `jsonl` – oder eine Arbeitsmappe (`xlsx`, `xls`, `xlsb`, `ods`; ihr
erstes Blatt wird als TEMP-Tabelle importiert und profiliert) oder, mit
`--database`, der Name einer Tabelle oder View. Ein Name mit Punkt wird als
`schema.table` gelesen und jeder Teil in Anführungszeichen gesetzt, sodass ein
Name mit Leerzeichen oder Großbuchstaben so funktioniert, wie er geschrieben
ist. Eine Relation, die nichts benennt, ist ein Argumentfehler (Exit 2), kein
SQL-Fehler.

Zurück kommt ein JSON-Objekt: `target`, `relation` (das SQL, gegen das die
Statistiken liefen), `row_count`, `elapsed_ms` und `columns` in der Reihenfolge
der Relation. Pro Spalte:

| Feld | Bedeutung |
| --- | --- |
| `name`, `type` | wie `DESCRIBE` sie meldet |
| `nulls` | Zeilen, in denen die Spalte `NULL` ist |
| `distinct` | exakt, nicht geschätzt |
| `unique` | vorhanden und `true`, wenn `distinct` gleich `row_count` ist |
| `min`, `max` | als Text, damit ein `DECIMAL` seine Ziffern behält |
| `decimals` | Ziffern nach dem Punkt, die die Spalte **tatsächlich nutzt**, was nicht ihre deklarierte Skala ist |
| `median` | ein Wert, den die Spalte enthält, keine Interpolation zwischen zwei Werten |
| `max_over_median` | wie oft der größte Wert größer als der Median ist – die Zahl, die zwischen linearer und logarithmischer Achse entscheidet |
| `covered_days`, `span_days`, `missing_days` | Tage, die die Spalte benennt, Tage zwischen ihren Enden und die Differenz: `0` ist eine durchgehende Reihe, alles andere sind Lücken, über die eine Linie hinwegzeichnen würde |

`decimals`, `median` und `max_over_median` erscheinen bei numerischen Spalten;
die Tagesfelder bei Daten und Zeitstempeln. Spalten vom Typ `LIST`, `STRUCT`,
`MAP` und `UNION` melden nur `nulls` – `min` und `max` sind auf ihnen nicht
definiert.

Eine Textspalte, die Zahlen und ein kurzes Wort wie Rs `NA` enthält, meldet
zusätzlich `null_marker` und `null_marker_rows`. Der Bericht ergänzt dann einen
`hint`, der den `read_csv`-Aufruf nennt, der die Spalte als Zahlen liest.

Statistiken sind exakt und lesen die ganze Relation, kosten also einen
vollständigen Scan. `--limit` gilt nicht: Ein Profil einer Stichprobe ist kein
Profil.

## Arbeit im laufenden Fenster zeigen {#show-work-in-the-running-window}

`ducklocal open` übergibt etwas an das bereits laufende DuckLocal-Fenster – und
startet eines, wenn keines läuft – und holt es nach vorn. So legt ein Agent
seine Arbeit einer Person vor, die dort weiterarbeiten kann:

```bash
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash                    # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch
```

- PATHs öffnen sich so, wie ein Ablegen auf das Fenster sie öffnet: eine
  `.dash`-Datei als Tab, eine DuckDB-Datenbankdatei als Datenbank des Fensters,
  Datendateien, Ordner und Globs als angehängte Views. Relative PATHs werden
  relativ zum Verzeichnis des Befehls aufgelöst. Eine Anfrage, die eintrifft,
  während das Fenster noch startet, wartet, bis sein Start-Öffnen abgeschlossen
  ist.
- `--sql` oder `--sql-file` (`-` liest stdin) öffnet einen neuen Abfrage-Tab mit
  dem Titel aus `--title`. `--run` führt die Abfrage aus, sobald die PATHs
  angehängt sind.
- `--no-launch` schlägt mit der Art `not_running` fehl, statt ein Fenster zu
  starten – für einen Rechner, auf dem ein ungefragt erscheinendes Fenster
  unerwünscht wäre.

Erfolg gibt `{"delivered": true, "launched": BOOL}` aus: die Übergabe, kein
Ergebnis. Was sich öffnet, läuft in der eigenen Sitzung des Fensters – seiner
Verbindung, seinen angehängten Views, seinem Verlauf – und jeder Fehler
erscheint dort, nicht auf stdout. Exit 2 bei Argumentfehlern; 1 mit der Art
`not_running` (kein Fenster erreichbar), `refused` (das Fenster hat die Anfrage
abgelehnt) oder `launch`.

Das Fenster lauscht auf einem Loopback-Port. Es schreibt den Port und ein
zufälliges Token in eine Datei, die nur Ihr Konto lesen kann (siehe
[Einstellungen und App-Daten](settings-and-data.md#where-things-are-stored));
ein anderer Benutzer auf dem Rechner oder eine Webseite, die auf localhost
zielt, kann es nicht erreichen.

### Lesen, was das Fenster zeigt

`ducklocal open --state` geht den umgekehrten Weg: Es öffnet nichts, startet nie
ein Fenster und gibt aus, was das laufende Fenster zeigt – so kann ein Agent
dort ansetzen, wo eine Person aufgehört hat, statt sie zu bitten, ihre Abfrage
einzufügen.

```bash
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active
```

```json
{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}
```

- `database` ist die geöffnete Datenbankdatei oder `":memory:"`; `attached`
  listet die Dateien, die das Fenster als Views registriert hat, mit dem
  View-`name`. Eine CLI-Abfrage kann diese Views nicht lesen – verwenden Sie den
  `path`.
- Ein **Abfrage**-Tab hat `sql`, den Text des Editors unabhängig davon, ob er
  lief, und `result`: `status` ist `empty`, `running`, `rows`, `affected`,
  `failed`, `explain` oder `profile`. Bei Zeilen: `columns`, `row_count`,
  `truncated`, `preview` (die ersten 20 Zeilen, wie das Raster sie zeigt, als
  Strings), `elapsed_ms` und das `sql`, das sie erzeugt hat; bei `affected`
  `count` und `elapsed_ms`; bei einem Fehler `error`.
- Sobald die Person im Chart-Tab Spalten gewählt hat, hat ein Ergebnis auch
  `chart`: `type`, `x`, `y`, `split` und `dash`, also einen `query`- und einen
  `plot`-Block, die dasselbe Diagramm in einem Dashboard zeichnen.
- `explain` ist, was **Explain** zeigt: `plan`, die `EXPLAIN`-Ausgabe von
  DuckDB als Array von Textzeilen, und `elapsed_ms`.
- `profile` ist, was **Profile** zeigt (siehe [SQL-Editor](sql-editor.md)):
  `plan`, den von `EXPLAIN ANALYZE` gemessenen Operatorbaum als Array von
  Wurzeln, jede `{operator, seconds, rows, estimated, children}` – `seconds` ist
  die Eigenzeit des Operators ohne seine Kinder, `rows`, was er produziert hat,
  `estimated` die Schätzung des Optimierers für `rows` (`null`, wo der Plan
  keine nennt), `children` dieselbe Form erneut. `operator_seconds` ist die
  Summe der Eigenzeiten aller Operatoren, also das, wozu sich die Anteile
  addieren, nicht die Wanduhr; `elapsed_ms` ist der ganze Lauf.
- Ein **Dashboard**-Tab hat `path`, `unsaved` und `dashboard`: dessen
  `comments_file`-Pfad, `plots` (Name, Typ, Titel, Abfrage, Zeilen,
  `open_comments` und `failure`, wenn eines nicht zeichnen kann) und seine
  `filters` mit dem, was jeder gewählt hat: `picked`, `value` (der erste Wert),
  `values` (jeder gewählte Wert, in Reihenfolge) und `multiple`. `value: null` mit `picked: true`
  bedeutet, dass der NULL-Wert gewählt wurde.

Mit `--state sales.dash` bleiben nur Tabs übrig, die dieses Dashboard zeigen,
mit `--state --active` nur der aktive Tab. Ein Pfad, der nicht offen ist,
liefert Exit 1, Art `not_open`, mit den offenen Dashboards im Hinweis.
`active_tab` ist der Index des aktiven Tabs innerhalb der zurückgegebenen
`tabs` oder `null`, wenn er nicht darunter ist; `database` und `attached`
bleiben enthalten.

`--state` akzeptiert entweder einen `.dash`-PATH oder `--active`, nicht beides.
`--no-launch` wird akzeptiert und ändert nichts. Andere Optionen, auch `--sql`
und `--run`, sind ungültig (Exit 2). Exit 1 mit der Art `not_running`, wenn kein
Fenster läuft, und `timeout`, wenn es nicht innerhalb von 5 Sekunden antwortet.

## Eine Dashboard-Spezifikation prüfen {#check-a-dashboard-spec}

Das Format selbst – Blöcke, Attribute, Diagrammtypen, SQL-Regeln und häufige
Meldungen – ist in [Dashboards (.dash)](dashboards.md) beschrieben; dieser
Abschnitt behandelt den Befehl.

Eine `.dash`-Datei deklariert ein Dashboard so, wie Terraform Infrastruktur
deklariert – Abfragen und Diagramme als Blöcke, Verweise dazwischen –, statt es
zu skripten. Sie ist für eine Person oder einen Agenten leicht zu schreiben und
zu diffen.

```hcl
query "latency" {
  sql = <<SQL
    SELECT timestamp, service, avg(latency) AS latency
    FROM logs
    GROUP BY timestamp, service
  SQL
}

plot "latency" {
  type   = "line"
  query  = query.latency
  x      = timestamp
  y      = latency
  series = service
}
```

```bash
ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summary
```

Ein `source`-Block benennt Datendateien, relativ zur `.dash`-Datei, die die
Abfragen lesen, und ein `view`-Block hält SQL, das mehrere Abfragen teilen. Ein
`query`-Block enthält ein `sql`-Attribut – eine
schreibgeschützte Anweisung, als Heredoc oder als String. `SELECT`, `WITH`,
`FROM`-first, `VALUES`, `SHOW`, `DESCRIBE`, `SUMMARIZE` und `PIVOT` werden
akzeptiert; alles, was schreiben könnte – DDL, DML, `COPY`, `ATTACH`, `INSTALL`
–, ist eine Diagnose, und die GUI weigert sich, es auszuführen, weil die
Abfragen eines Dashboards bei jedem Öffnen der Datei laufen. Ein `plot`-Block
enthält `type` (eines von `line`, `bar`, `stacked_bar`, `area`, `scatter`,
`pie`, `heatmap`, `histogram`, `map`, `timeline`, `table`, `card`, `text`),
`query` (einen Verweis wie `query.latency` auf einen Abfrageblock derselben Datei), seine
Spalten und optional `title` und `width`. Ein `filter`-Block macht ein
Balkendiagramm oder eine Tabelle klickbar – einen Wert, oder mehrere mit
`multiple = true` an einem Balken –, und eine Abfrage liest die Auswahl
als `$name`. `#` und `//` kommentieren bis zum Zeilenende.
[Dashboards (.dash)](dashboards.md) enthält jedes Attribut.

Ein `text`-Diagramm ist die Ausnahme: Es enthält `title`, `text` oder beides und
nimmt keine `query`. Karten können außerdem `note` und `tone` verwenden; siehe
[Karten und Textbereiche](dashboards.md#cards-and-text-panels).

Zuerst die statischen Prüfungen: das SQL jeder Abfrage durch den echten
DuckDB-Parser auf einer Wegwerf-Verbindung, so wie `query` vor dem Ausführen
prüft, und jedes `$name` gegen die Filterblöcke – das SQL wird mit jedem
`$name` als `TRUE` geparst und ausgeführt, was dem entspricht, was das Dashboard
ausführt, bevor etwas gewählt ist.

Dann läuft jede Abfrage, genau wie das Öffnen des Dashboards sie ausführen
würde – schreibgeschützt, mit ihren Quellen, über denselben Codepfad und
dasselbe Zeilenbudget –, und die Spalten jedes Diagramms werden gegen die
Spalten geprüft, die die Abfrage tatsächlich zurückgibt: ein `y`, das nicht
numerisch ist, ist ein Fehler für jeden Diagrammtyp, ebenso nicht-numerische
Koordinaten oder `size` einer Karte, und ebenso eine Filter-`column`, die die
Abfrage ihres Diagramms nicht zurückgibt.

- **Ohne `--database`** laufen die Abfragen im Speicher, was alles ist, was ein
  Dashboard über seine eigenen `source`-Dateien braucht. Eine Abfrage, die eine
  Tabelle liest, die keine Quelle definiert, kann für eine Datenbank gedacht
  sein, die der Prüfung nicht mitgegeben wurde: Sie wird unter `unresolved`
  (Abfrage, Zeile, Grund) gelistet statt als Fehler behandelt, und die Spalten
  ihrer Diagramme bleiben ungeprüft.
- **Mit `--database PATH`** (vorhandene Datei, schreibgeschützt) laufen sie auf
  dieser Datenbank. Übergeben Sie sie immer, wenn die Abfragen Tabellen einer
  Datenbank lesen: Alles unter `unresolved` blieb ungeprüft.

Jede Abfrage, die einen Filter liest, wird zusätzlich mit einem gewählten Wert
gebunden, ohne diese Variante auszuführen. Das fängt eine Filterspalte ab, die
in einer konsumierenden Abfrage fehlt, auch wenn die erste Variante mit
`$name = TRUE` funktioniert. Ein Filter muss außerdem auf eine Spalte verweisen,
die sein auswählendes Diagramm zurückgibt.

Ausführen statt nur Planen ist wichtig: Manche Fehler, etwa eine Umwandlung,
die der Build nicht durchführen kann, oder ein Wert, der sich nicht konvertieren
lässt, zeigen sich erst, wenn Zeilen gelesen werden, und eine Prüfung, die sie
durchgehen lässt, würde ein Dashboard übergeben, das nicht zeichnen kann.
Abfragen laufen vollständig, eine Prüfung gegen eine große Datenbank dauert
also so lange wie das Öffnen des Dashboards.

Erfolg ist ein JSON-Objekt, das die Quellen der Datei (mit jedem `resolved`-Pfad),
die Views, die Abfragen (mit ihren Ergebnisspalten und `rows`, wie viele jede ohne Auswahl
zurückgab, plus `truncated: true`, wenn das Zeilenbudget des Dashboards sie
abgeschnitten hat), die Filter (mit den `queries`, die jeden lesen), die
Diagramme, `unresolved` und `empty` – die Abfragen, die liefen und keine Zeilen
zurückgaben – auflistet. Eine leere Abfrage besteht jede andere Prüfung, ist
aber meist ein regulärer Ausdruck, ein Filter oder ein Join, der nichts traf;
sehen Sie sich jede an. Mit `--summary` ist Erfolg eine kompakte JSON-Zeile:

```json
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}
```

Die fünf Blockfelder sind Anzahlen; `unresolved` listet die Abfragen, die nicht
geprüft werden konnten, und `empty` die, die keine Zeilen zurückgaben.

Ein fehlerhafter Block wird ausgelassen, während gültige Blöcke weiter durch die
Validierung laufen. Spezifikationsfehler und Abfragefehler werden im selben Lauf
gesammelt, je ein `file:line: message`. Existiert eine
Spezifikationsdiagnose, ist der Exit 2 mit der Art `spec`; scheitert nur die
SQL-Ausführung oder -Bindung, ist er 1 mit der Art `sql`. Datenbank- und
I/O-Fehler enden ebenfalls mit 1. `--summary` verbirgt keine Diagnosen.

Dieselbe Datei öffnet sich als Dashboard-Tab in der GUI – `ducklocal
dashboard.dash`, `ducklocal open dashboard.dash` oder per Ziehen auf das Fenster
–, mit Diagrammen auf einem 12-Spalten-Raster, und ein Diagramm, das nicht
zeichnen kann, zeigt den Grund direkt an. Siehe [Dashboards (.dash)](dashboards.md).

## Metriken aus einem semantischen Modell {#metrics}

```bash
ducklocal metrics                       # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data
```

`ducklocal metrics` liest ein Apache-Ossie-Modell, `model.ossie.yaml`, und
listet seine Metriken und Felder. `compile` gibt das eine DuckDB-`SELECT` aus,
das eine Anfrage beantwortet, und liest keine Daten; `query` führt es aus wie
`ducklocal query` und fügt ein `semantic`-Objekt mit dem SQL und dem `sha256`
des Modells hinzu. Eine Anfrage, die das Modell nicht exakt beantworten kann,
wird abgelehnt, mit Exit-Code 2 und einem `kind` wie `metric_fanout`.
[Semantische Metriken](metrics.md) beschreibt das Modellformat, jede Option und
jede Ablehnung.

## Review-Kommentare zu einem Dashboard {#review-comments-on-a-dashboard}

Personen prüfen ein Dashboard, indem sie seine Diagramme im Fenster
kommentieren – mit dem Zeiger auf ein Diagramm und einem Klick auf die
Sprechblase (siehe [Mit Kommentaren prüfen](dashboards.md#review-with-comments)).
`ducklocal comments` ist die Seite des Agenten: Es liest die Threads und
beantwortet sie, ohne Fenster.

```bash
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"
```

- Ohne Aktion werden die offenen Threads ausgegeben:
  `{file, comments_file, open, threads}`. `--all` schließt erledigte ein.
- Jeder Thread hat `id`, `plot` und was der Agent braucht, um ihn in der
  Spezifikation zu finden: `plot_title`, `plot_query` und `plot_lines`, die
  erste und die letzte Zeile des `plot`-Blocks (`null`, wenn die Spezifikation
  nicht parst). `plot_missing` ist `true`, wenn kein Diagramm dieses Namens
  mehr übrig ist. Dann `resolved` und `comments`, jeweils mit `author` (`user`
  oder `agent`), bei einem Kommentar eines Agenten dessen `name` (der Name, den
  [`presence`](#agent-presence) zeigt), `text` und `at` (RFC 3339, lokale Zeit).
- `--reply ID --text TEXT` fügt die Antwort des Agenten hinzu. Eine Antwort auf
  einen erledigten Thread öffnet ihn wieder, sofern nicht auch `--resolve`
  angegeben ist.
- `--resolve ID` und `--reopen ID` ändern den Zustand eines Threads; `--add
  PLOT --text TEXT` startet einen Thread, signiert als der Agent.
- Die Nummer eines Threads funktioniert als seine ID: `--reply 1` bedeutet
  `c1`. `--add` lehnt ein Diagramm ab, das die Spezifikation nicht hat (Exit
  2), und der Hinweis listet ihre Diagramme auf.
- Eine Aktion gibt `{thread}` aus, wie er geändert wurde.

Die Threads liegen neben der Spezifikation, in `FILE.comments.json`. Ein
laufendes Fenster bemerkt eine Änderung innerhalb einer Sekunde und zeigt sie
am Diagramm. Eine unbekannte Thread-ID ist Exit 2, mit einem Hinweis zum
Auflisten der Threads; eine Spezifikationsdatei, die nicht existiert, ist
Exit 1.

Ein Review von Anfang bis Ende: die offenen Threads lesen, die Spezifikation
bearbeiten, `ducklocal check` ausführen, dann jeden Thread mit dem, was sich
geändert hat, beantworten und mit `--resolve` abschließen. Verwenden Sie
`--reply` ohne `--resolve`, um der Person eine Rückfrage zu stellen.

## Agentenaktivität zeigen {#agent-presence}

`check` und `comments` teilen einem laufenden Fenster automatisch mit, an
welchem Dashboard der Agent arbeitet. `presence` kann eine Bearbeitung
ankündigen, bevor sie geschieht:

```bash
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle
```

- `--doing` akzeptiert `reading`, `editing` oder `idle` (`done` ist ein Alias
  für `idle`).
- `--plot` nimmt kommagetrennte Diagrammnamen. Bei `editing` sind neue Namen
  erlaubt und erscheinen als Platzhalter. Bei `reading` oder `idle` ist ein
  unbekannter Name Exit 2.
- Der angezeigte Name kommt aus `--agent`, dann `DUCKLOCAL_AGENT`, dann der
  erkannten Agentenumgebung (Claude, Codex, Cursor oder Gemini), mit
  Rückfall auf `Agent`.
- Die Ausgabe ist `{delivered}`. Ohne laufendes Fenster entsteht
  `{"delivered":false}` ohne Fehler und ohne ein Fenster zu starten.

Der Name bleibt in der Ecke des Dashboards, solange Befehle die Sitzung aktiv
halten. Klicken Sie ihn für das Aktivitätsprotokoll an. Dreißig Sekunden Stille
oder `--doing idle` beenden die Sitzung; geänderte und hinzugefügte Diagramme
bleiben markiert, bis sie angesehen wurden, und Hinweise auf entfernte
Diagramme, bis sie verworfen werden. Siehe
[Einen Agenten bei der Arbeit sehen](dashboards.md#agent-presence).

## Eine Dashboard-Spezifikation mit LSP bearbeiten {#edit-a-dashboard-spec-with-lsp}

`ducklocal lsp` ist ein Language-Server-Protocol-Server für `.dash`-Dateien über
stdio, den Editoren starten. Er gibt jedem LSP-fähigen Editor, was der
Spezifikationseditor der GUI selbst hat:

- **Diagnosen**: die, die `check` meldet, veröffentlicht bei jedem Öffnen und
  jeder Änderung (Volltext-Synchronisierung, alle mit Schweregrad Error – es
  sind Fehler, kein Stil).
- **Vervollständigung**: Blocktypen, Attributnamen, Diagrammtypen und die Namen
  nach `query.` und `plot.`, jeweils mit einer Textänderung, die das gerade
  getippte Wort ersetzt.
- **Hover**: Dokumentation für Blöcke, Attribute und Verweise.
- **Zur Definition springen**: von einem Verweis `query.name` oder `plot.name`
  zum Namen seines Blocks.

Mit `--database PATH` wird das SQL jeder Abfrage zusätzlich vom echten
DuckDB-Parser validiert, so wie `check --database` es tut.

Richten Sie die generische LSP-Unterstützung Ihres Editors für `*.dash`-Dateien
auf `ducklocal lsp` – der Befehl nimmt keine Dokumentargumente; der Editor
spricht über stdio mit ihm. In Neovim (0.10+):

```lua
vim.api.nvim_create_autocmd("FileType", {
  pattern = "dash",
  callback = function(event)
    vim.lsp.start({
      name = "ducklocal",
      cmd = { "ducklocal", "lsp" },
      root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
    })
  end,
})
```

In VS Code tut jede generische LSP-Erweiterung dasselbe mit dem Befehl
`ducklocal`, den Argumenten `["lsp"]` und dem Dokumentselektor `dash`.
Exitcodes: **0** nach einem sauberen `shutdown`/`exit`, **1**, wenn der Client
ohne eines verschwindet, **2** bei einer fehlerhaften Befehlszeile oder einem
gescheiterten Protokoll-Handshake.

## JSON-Vertrag

Erfolgreiche Abfragen schreiben genau ein JSON-Objekt nach stdout, gefolgt von
einem Zeilenumbruch:

```json
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}
```

`columns` und jede Zeile bewahren die Spaltenreihenfolge und doppelte
Spaltennamen. `type` ist die **Arrow-Debug-Darstellung**, nicht der ursprüngliche
DuckDB-SQL-Typname (HUGEINT und DECIMAL können sich etwa einen Arrow-Träger
teilen). `row_count` zählt zurückgegebene Zeilen. `total_rows` zählt die
erzeugten Zeilen, einschließlich der nach der Ausgabegrenze gezählten;
`total_rows_exact: false` bedeutet, dass das Zählen nach bis zu 100.000 weiteren
Zeilen aufhörte, diese Summe also eine Untergrenze ist. Keine der beiden Zahlen
ist eine Anzahl betroffener Zeilen. `elapsed_ms` misst Vorbereitung, Ausführung
und Zeilenkodierung, nicht das Laden von Dateien oder den Verbindungsaufbau.
Ergebnisse ohne Zeilen behalten ihre Metadaten. DDL/DML legen das tatsächliche
DuckDB-Ergebnis offen, einschließlich `Count`-Spalten: INSERT/COPY liefern
üblicherweise `[[N]]`; CREATE TABLE liefert üblicherweise keine Zeilen. Sie
werden nicht am ersten SQL-Schlüsselwort klassifiziert.

Kodierungen von Zellen:

| SQL-Wert | JSON-Kodierung |
| --- | --- |
| NULL | `null` (nie der String `"NULL"`) |
| Boolean, endlicher Float | JSON-Boolean/JSON-Zahl |
| Ganzzahl innerhalb ±9.007.199.254.740.991 | JSON-Zahl |
| Größere Ganzzahl, auch HUGEINT/UHUGEINT | `{"encoding":"integer","value":"9007199254740992"}` |
| Dezimalzahl | `{"encoding":"decimal","value":"123.450"}` mit exaktem Dezimaltext |
| Text, Enum | JSON-String |
| Blob, Geometrie | `{"encoding":"hex","value":"00ff"}`; Kleinbuchstaben-Bytes, Geometrie verwendet WKB |
| Datum | `{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}`; Tage seit 1970-01-01 |
| Zeitstempel | `{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}`; vorzeichenbehaftete Zählung seit der Unix-Epoche; die Einheit kann auch Second/Millisecond/Microsecond sein |
| Zeit | `{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}`; Zählung seit Mitternacht |
| Intervall | `{"encoding":"interval","months":1,"days":2,"nanos":"3000"}` |
| NaN, positive/negative Unendlichkeit | `{"encoding":"float","value":"NaN"}` / `"inf"` / `"-inf"` |
| Liste, Array | JSON-Array, rekursiv kodiert (auch verschachtelte Nullen) |
| Struct | `{"encoding":"struct","fields":[["name",VALUE],...]}` |
| Map | `{"encoding":"map","entries":[[KEY,VALUE],...]}`; kein JSON-Objekt, damit Schlüssel ihre Typen behalten |
| Union | `{"encoding":"union-value","value":VALUE}`; nur der aktive Wert, das Mitglieds-Tag bleibt nicht erhalten |

Temporale `value`s sind exakte Zählungen, es geht also keine Bruchteilsgenauigkeit
verloren; Unendlichkeits-Sentinels von Datum und Zeitstempel bleiben rohe
Zählungen. Daneben ist `iso` derselbe Wert als ISO-8601-Text zum Lesen, mit so
vielen Bruchziffern, wie die Einheit fasst. Ein Zeitstempel aus einer Spalte mit
Zeitzone (Arrow-Metadaten) ist ein UTC-Zeitpunkt, und sein `iso` endet auf `Z`.
`--format md` stellt Daten und Zeitstempel ebenfalls lesbar dar. Weil der
festgelegte Arrow-Wrapper von DuckDB verschachtelte HUGEINT, UHUGEINT und
DECIMAL(38,0) nicht unterscheiden kann, erzeugen Nicht-NULL-Vorkommen einen
klaren Fehler, statt stillschweigend Vorzeichen oder Genauigkeit zu ändern.
Casten Sie solche Felder in SQL ausdrücklich nach VARCHAR. Unbekannte nicht
unterstützte Typen erzeugen ebenfalls einen Fehler; verwechseln Sie einen
Fehler nicht mit einem leeren Ergebnis. Die Union-Kodierung ist eine Darstellung
des aktiven Werts, kein verlustfreier Roundtrip einer Union.

Fehler schreiben ein JSON-Objekt nach **stderr** und lassen stdout leer:

```json
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}
```

`hint` ist da, wenn der nächste Schritt bekannt ist, in den Begriffen dieser CLI
selbst: das Flag, das ein falsch geschriebenes hätte sein sollen, `--read-write` für
einen Schreibvorgang, der auf einer schreibgeschützten Datenbank abgelehnt
wurde, `ducklocal schema` für eine Tabelle, die nicht existiert, `TRY_CAST` für
einen Wert, der sich nicht konvertieren lässt, das Aufteilen eines Skripts mit
mehr als einer Anweisung, oder `AS` für ein Schlüsselwort, das als reiner
Spaltenalias verwendet wird (`SELECT count(*) AS minutes`, oder setzen Sie es in
Anführungszeichen). Ein Agent sollte darauf reagieren, bevor er das SQL neu
schreibt. Er fehlt, wenn DuckDBs eigener Meldung nichts hinzuzufügen ist, etwa
bei einem Syntaxfehler.

Exitcodes: **0** Erfolg, **2** ungültige Argumente/Anweisungsanzahl, **1** SQL-,
Datenbank-, I/O- oder Ausgabefehler. Die Fehlerarten sind `argument`, `sql`,
`database`, `io`, `output`, `spec` für `check` und `not_running`, `not_open`,
`refused`, `timeout` oder `launch` für `open`. Prüfen Sie den Exit-Status, bevor
Sie stdout parsen, und `truncated`, bevor Sie Vollständigkeit melden. Hilfe und
Version sind reine Textausnahmen. Transportfehler wie eine geschlossene
stdout-Pipe können keinen leeren oder vollständigen Ausgabestrom garantieren.

## Den offiziellen Skill installieren {#install-the-official-skill}

Der Skill bringt einem Agenten die Gewohnheiten bei, die seine Antworten ehrlich
halten: das Schema prüfen, eine begrenzte Stichprobe ansehen, Aggregate in SQL
berechnen, `truncated` prüfen und aus zurückgegebenen Werten antworten. Er deckt
Schema-Einsicht, Spaltenstatistiken, Konvertierungen, Datenbankabfragen,
`.dash`-Dashboards und ihre Review-Kommentare sowie das Übergeben von Arbeit an
das Fenster und das Zurücklesen ab; er bietet keinen S3-Browser,
raumspezifische Befehle, Sitzungsgedächtnis oder einen MCP-Server.

**Aus der App.** Öffnen Sie **Befehlszeile & KI…** (die Roboter-Schaltfläche in
der Titelleiste oder das DuckLocal-Menü):

- **Befehl installieren** legt `ducklocal` auf Ihren `PATH`, sodass die Shell
  eines Agenten ihn ausführen kann.
- **Zu Claude Code hinzufügen** schreibt den Skill nach
  `~/.claude/skills/ducklocal`, wo Claude Code ihn in jedem Projekt findet. Es
  werden nur die beiden Dateien des Skills geschrieben; alles andere in diesem
  Ordner bleibt erhalten. Wenn ein DuckLocal-Update einen neueren Skill
  mitbringt, bietet der Dialog **Skill aktualisieren** an.
- **Kurzanleitung kopieren** kopiert eine kurze Erklärung für jeden anderen
  Agenten – Codex, Cursor, ein Chatfenster –, die den Befehl und seine
  Verwendung nennt.

**Von Hand.** Der Skill ist
[`skills/ducklocal`](https://github.com/JetSquirrel/ducklocal/tree/main/skills/ducklocal).
Um ihn stattdessen einem einzelnen Projekt hinzuzufügen (Beispiel für Claude
Code):

```bash
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/
```

Prüfen Sie ein vorhandenes Ziel zuerst, statt lokale Änderungen zu überschreiben.
Andere Agenten können dieselbe `SKILL.md` plus `references/cli.md` in ihrem
unterstützten Skill-Verzeichnis verwenden.
