# CLI

> Die Kommandozeile docsello – Markdown-Ordner hochladen, Bereiche herunterladen, Seiten bearbeiten und Screenshots neu aufnehmen.

`docsello` ist die Kommandozeile für Docsello, gebaut für CI-Pipelines: Sie lädt Ordner mit Markdown-Dateien in
Bereiche, holt Bereiche als Dateien zurück, bearbeitet einzelne Seiten und stößt Screenshots und Veröffentlichungen
an. Sie ist eine einzelne Datei ohne Abhängigkeiten und braucht Node.js ab Version 22.4.

## Installation

Die CLI ist Teil des Docsello-Quellcodes. Aus einem Checkout baust du sie mit:

```bash
pnpm install
pnpm --filter @docsello/cli build
node packages/cli/dist/docsello.mjs --help
```

Ab Version 0.1.6 hängt außerdem an jedem [GitHub-Release](https://github.com/Ceddini/docsello/releases) die fertige
Datei `docsello.mjs` (über npm gibt es die CLI nicht):

```bash
gh release download --repo Ceddini/docsello --pattern docsello.mjs   # neuestes Release, z. B. v0.1.6 anhängen zum Festlegen
node docsello.mjs --help
```

Solange das Repository privat ist, braucht `gh` dafür Lesezugriff darauf.

Die Datei `docsello.mjs` kannst du überallhin kopieren. In den Beispielen unten steht kurz `docsello` dafür.

## Verbindung

Die CLI braucht die Adresse deiner Docsello-Installation und einen [API-Token](doc:api-tokens):

```bash
export DOCSELLO_URL=https://docs.example.com
export DOCSELLO_TOKEN=dsl_…
docsello whoami
```

Reihenfolge: Optionen (`--url`, `--token`) vor Umgebungsvariablen vor einer Datei `docsello.json` im aktuellen
Ordner. Die Datei kann Standardwerte enthalten – den Token aber nie:

```json
{
  "url": "https://docs.example.com",
  "space": "handbuch",
  "dir": "docs",
  "prune": true,
  "ignore": ["entwuerfe", "**/*.draft.md"]
}
```

Erlaubt sind `url`, `space`, `dir`, `locale`, `prune`, `publish` und `ignore`; unbekannte Schlüssel sind ein Fehler.

## Befehle

| Befehl | Wofür |
|---|---|
| `docsello whoami` | Workspace, Rolle des Tokens, Tarif |
| `docsello spaces` | Tabelle aller Bereiche |
| `docsello push <ordner> --space <bereich>` | Ordner in einen Bereich hochladen und veröffentlichen |
| `docsello sync [ordner]` | Eine ganze Dokumentation aus `spaces.json` abgleichen, siehe [Docs aus Git](doc:docs-aus-git) |
| `docsello pull --space <bereich> <ordner>` | Bereich als Markdown-Dateien herunterladen |
| `docsello page get <bereich> <pfad>` | Markdown einer Seite ausgeben |
| `docsello page put <bereich> <pfad> --title <titel>` | Eine Seite schreiben (aus `--file` oder der Standardeingabe) |
| `docsello publish --site <website>` | Die ganze Website neu generieren |
| `docsello changelog <datei> --space <bereich>` | Eine `CHANGELOG.md` in einen Changelog-Bereich importieren |
| `docsello screenshots capture --all` | Screenshots neu aufnehmen (oder `--key <schlüssel>`, mehrfach möglich) |

`docsello <befehl> --help` zeigt alle Optionen. Mit `--json` gibt jeder Befehl maschinenlesbares JSON aus, `--no-color`
schaltet Farben ab. Exit-Codes: `0` erfolgreich, `1` fehlgeschlagen (API- oder Importfehler), `2` falscher Aufruf.

## push

```bash
docsello push docs --space handbuch                 # hochladen und veröffentlichen
docsello push docs -s handbuch --prune              # … und Seiten, die es nicht mehr gibt, in den Papierkorb
docsello push docs -s handbuch --dry-run            # nur zeigen, was passieren würde
docsello push docs -s handbuch --publish=false      # nur Entwürfe speichern
docsello push docs -s handbuch --create-space -m "$(git log -1 --pretty=%s)"
```

| Option | Bedeutung |
|---|---|
| `--space`, `-s` | Ziel-Bereich |
| `--prune` | Seiten, die nicht im Ordner sind, in den Papierkorb verschieben |
| `--dry-run` | Nichts ändern, nur anzeigen |
| `--publish=<bool>` | Veröffentlichen (Standard) oder nur Entwürfe |
| `--message`, `-m` | Notiz für den Verlauf, z. B. die Commit-Nachricht |
| `--locale` | In diese Sprache importieren |
| `--create-space` | Bereich anlegen, falls es ihn nicht gibt |
| `--ignore <glob>` | Dateien oder Ordner überspringen (mehrfach möglich) |

Große Ordner werden in mehreren Anfragen hochgeladen. Unveränderte Dateien erzeugen keine neue Fassung. `--prune`
läuft erst nach allen Teilen und wird übersprungen, wenn etwas fehlgeschlagen ist. `node_modules`, `.git` und Dateien,
die mit einem Punkt beginnen, werden immer übersprungen.

### Ordner-Aufbau

| Im Ordner | In Docsello |
|---|---|
| `anleitung.md` | Seite `anleitung` |
| `02-anleitung.md` | Seite `anleitung`, an zweiter Stelle (die Zahl bestimmt die Reihenfolge) |
| `03-einrichtung/` | Gruppe „Einrichtung“ mit den Dateien darin als Unterseiten |
| `03-einrichtung/index.md` oder `README.md` | Inhalt der Seite `einrichtung` selbst (statt einer Gruppe) |
| `_category_.json` (`label`, `position`) | Titel und Reihenfolge eines Ordners (wie bei Docusaurus) |

Frontmatter: `title`, `description`, `icon`, `order` (oder `sidebar_position`), `slug`, `visibility`, `date`,
`hidden` (in Navigation und Suche ausblenden) und `toc` (`false` = kein Inhaltsverzeichnis). Ohne
`title` wird die erste `# Überschrift` zum Titel.

## pull

```bash
docsello pull --space handbuch ./handbuch
```

Schreibt jede Seite als `<pfad>.md` (Seiten mit Unterseiten als `<pfad>/index.md`) mit Frontmatter, dazu
`_category_.json` für Gruppen. Ein erneutes `push` desselben Ordners meldet alles als unverändert. Ziel muss ein leerer
Ordner sein – oder du übergibst `--force` (überschreibt Dateien, löscht nichts).

## page get / page put

```bash
docsello page get handbuch zahlungen/stripe --frontmatter
docsello page put handbuch zahlungen/stripe --title Stripe --file stripe.md --publish
echo "Hallo" | docsello page put handbuch hallo --title Hallo
```

`page put` speichert ohne `--publish` nur einen Entwurf.

## changelog

```bash
docsello changelog CHANGELOG.md --space neuigkeiten --title-prefix "Version "
```

Importiert jede Version als datierten Eintrag (Format siehe [Bereiche einrichten](doc:bereiche)). Mit
`--include-unreleased` auch den Abschnitt „Unreleased“, mit `--no-publish` nur als Entwürfe.