WebCull - Documentation

Zusammenfassung

WebCull CLI-Befehlsreferenz

Die WebCull CLI ist ein Befehlszeilenwerkzeug zum Finden, Erstellen und Aktualisieren von Lesezeichen aus einem Terminal oder Automatisierungsworkflow. Befehle geben standardmäßig JSON zurück und sind darauf ausgelegt, mit großen Lesezeichenkonten über Limits, Paginierung, Feldauswahl und Ausgabebudgets zu arbeiten.

webcull <command> [options]

Befehl

webcull

Paket

@webcull/cli

Konfigurationspfad

~/.config/webcull/config.json oder der durch WEBCULL_CONFIG festgelegte Pfad.

API-URL

Standard ist https://api.webcull.com. Mit WEBCULL_API_URL überschreiben.

Authentifizierung

CLI autorisieren, bevor Kontobefehle ausgeführt werden

webcull login
webcull auth login
webcull whoami
webcull limits

webcull login startet eine kurzlebige Browser-Freigabe. Das Terminal zeigt einen Kopplungscode, der Browser zeigt denselben Code, und die Freigabe erstellt ein CLI-Token für Lese- und Schreibbefehle für Lesezeichen.

Genehmigen Sie nur eine Anmeldung, die Sie selbst gestartet haben. Vergleichen Sie vor der Genehmigung den Terminalcode mit dem Browsercode.

login

Startet die Browser-Autorisierung und speichert das CLI-Token nach Genehmigung.

auth login

Alias für login.

whoami

Gibt das autorisierte Konto als JSON aus.

limits

Gibt aktuelle CLI-Nutzungslimits und verbleibende Anfragekapazität aus.

Lesebefehle

Breit beginnen, dann bestimmte Lesezeichendatensätze abrufen

webcull bookmarks count [--path <path>]
webcull bookmarks tree [--path <path>] [--max-depth <n>] [--per-parent-limit <n>]
webcull bookmarks search --query <query> [--sort <sort>]
webcull bookmarks get --ids <ids>

bookmarks count

Zählt untergeordnete Elemente unter einem Lesezeichenpfad. Der Standardpfad ist /.

bookmarks tree

Gibt einen begrenzten Baum von einem Pfad zurück. Standards umfassen --limit 50, --max-depth 2 und --max-chars 12000.

bookmarks search

Durchsucht Lesezeichenmetadaten. Das Standard-Ergebnislimit ist 25 und die Standardsortierung ist modified_desc.

bookmarks get

Ruft bestimmte Lesezeichen nach ID ab. Übergeben Sie eine ID, kommagetrennte IDs oder --ids.

Bevorzugen Sie count oder einen flachen tree, bevor Sie größere Ergebnismengen abrufen. Verwenden Sie get, nachdem Sie die benötigten Lesezeichen-IDs kennen.

Ausgabesteuerungen

Payload-Größe begrenzen und Ausgabefelder auswählen

webcull bookmarks tree --path / --max-depth 1 --limit 25 --max-chars 8000 --fields id,type,title,modified
webcull bookmarks get --ids 123,456 --fields id,title,url,notes --max-metadata-chars 1500 --format json
webcull bookmarks search --query 'github api' --limit 20 --format jsonl

--limit <n>

Maximale Anzahl von Ergebnissen, die von Befehlen zurückgegeben wird, die Lesezeichen auflisten.

--page <n>

Seitennummer für Befehle, die seitenweise Ergebnisse unterstützen. Seiten beginnen bei 1.

--max-chars <n>

Maximales Antwortgrößenbudget.

--max-metadata-chars <n>

Maximaler Metadatentext, der pro Lesezeichen enthalten ist.

--fields <list>

Kommagetrennte Ausgabefelder, zum Beispiel id,title,url,parent_id,modified.

--format json|jsonl

Gibt standardmäßig formatiertes JSON aus. jsonl gibt ein Element pro Zeile aus, wenn die Antwort eine Elementliste enthält.

Suche

Abfragebegriffe, Feldfilter und begrenzte Scans verwenden

webcull bookmarks search --query 'github api'
webcull bookmarks search --query 'title:"github" AND notes:api'
webcull bookmarks search --query '(title:"github" OR url:"github.com") AND notes:api'
webcull bookmarks search --query 'github api' --limit 20 --max-scan-rows 500

Klartextkonten verwenden serverseitige Suche. Verschlüsselte Konten verwenden automatisch lokale entschlüsselte Suche, wenn Lesezeichentext durchsucht werden muss.

E2EE search syntax

Lokale entschlüsselte Suche unterstützt einfache Begriffe, Feldfilter und AND. Komplexe lokale OR- und geklammerte Abfragen werden für die lokale Suche verschlüsselter Konten abgelehnt.

--max-scan-rows <n>

Maximale Anzahl von Lesezeichen, die während der lokalen entschlüsselten Suche gescannt werden. Der Befehl begrenzt diesen Wert auf 5000.

--page-size <n>

Anzahl der Lesezeichen, die während der lokalen entschlüsselten Suche gleichzeitig geprüft werden. Der Befehl begrenzt diesen Wert auf 200.

--sort <sort>

Sortierreihenfolge für Such- und Scan-Aufrufe. Standard ist modified_desc.

Schreibbefehle

Lesezeichen erstellen und aktualisieren

webcull bookmarks create --url <url> [--title <title>] [--notes <text>] [--tags <tags>] [--parent-id <id>] [--parent-path <path>] [--dry-run]
webcull bookmarks create --type folder --title <title> [--parent-id <id>] [--dry-run]
webcull bookmarks update <id> [--url <url>] [--title <title>] [--notes <text>] [--tags <tags>] [--parent-id <id>] [--parent-path <path>] [--dry-run]

--url <url>

Erstellt oder aktualisiert eine Lesezeichen-URL. Beim Erstellen eines Lesezeichens erforderlich.

--type folder

Erstellt einen Ordner. Ordnererstellung erfordert --title und akzeptiert kein --url.

--title <title>

Legt den Titel des Lesezeichens oder Ordners fest.

--notes <text>

Legt Lesezeichennotizen fest.

--tags <tags>

Legt kommagetrennte Tags fest. Leerzeichen um jeden Tag werden entfernt.

--parent-id <id>

Platziert das Lesezeichen oder den Ordner unter einem übergeordneten Element per ID.

--parent-path <path>

Platziert das Lesezeichen oder den Ordner per Pfad unter einem übergeordneten Element. Nicht mit --parent-id kombinieren.

--dry-run

Validiert Authentifizierung, Umfang, Drosselungen, Besitz, Platzierung und E2EE-Zustand, ohne die Änderung zu speichern.

Schreibbefehle erhalten Felder, die nicht im Befehl enthalten sind. Sie unterstützen keine Massenschreibvorgänge, rekursiven Schreibvorgänge, automatische Ordnererstellung, Lesezeichen-zu-Ordner-Konvertierung, Ordner-zu-Lesezeichen-Konvertierung, Symbol-Upload oder E2EE-Aktivierungs-, Deaktivierungs- oder Schlüsseländerungsabläufe.

Verschlüsselte Konten

E2EE-Passphrasen bleiben in versteckten Terminal-Eingaben

Bei E2EE-Konten fragt die CLI die E2EE-Passphrase nur über versteckte interaktive Terminal-Eingabe ab. Sie akzeptiert E2EE-Passphrasen niemals in Argumenten, Umgebungsvariablen, Konfigurationsdateien, stdin-Pipes, Logs oder Beispielen.

Verschlüsselte Lesezeichenfelder werden vor Schreibvorgängen lokal verschlüsselt und für unterstützte Lesevorgänge lokal entschlüsselt. Der Server erhält verschlüsselte Werte und erhält niemals Passphrasen, abgeleitete Schlüssel, Passphrase-Hashes oder entschlüsselte Lesezeichenfelder zur E2EE-Validierung.

CLI-Schreibvorgänge sind blockiert, während die E2EE-Konvertierung läuft. Schließen Sie die E2EE-Konvertierung in der App ab, bevor Sie Lesezeichen aktualisieren, die noch konvertiert werden müssen.

Token

CLI-Token sind von Browsersitzungen getrennt

Die CLI speichert ihr Token standardmäßig in ~/.config/webcull/config.json mit Dateimodus 0600. Setzen Sie WEBCULL_CONFIG, um einen anderen Pfad zu verwenden.

Das Token ist von Browser- und Erweiterungssitzungen getrennt. Aktuelle Lesezeichen-CLI-Token enthalten bookmarks:read und bookmarks:write.

Limits

Drosselungen als Taktungshinweise verwenden

WebCull begrenzt CLI-Anfragen, um Konten zu schützen und den Dienst reaktionsfähig zu halten. Lese- und Schreibbefehle haben unterschiedliche Limits.

Lese-Token

60 Anfragen pro Minute, 600 pro Stunde und 3000 pro Tag.

Benutzer oder IP lesen

Benutzer- und IP-Limits bieten zusätzlichen Konto- und Netzwerkschutz.

Schreib-Token

10 Anfragen pro Minute, 100 pro Stunde und 500 pro Tag.

Schreibbenutzer oder IP

Schreibanfragen haben strengere Konto- und Netzwerktaktung als Leseanfragen.

Limit-Abfrage

7 Anfragen pro Minute. Rufen Sie webcull limits sparsam auf.

Warten Sie bei einer gedrosselten Antwort mindestens 60 Sekunden, bevor Sie es erneut versuchen. Grenzen Sie die nächste Anfrage nach Möglichkeit ein. Testlauf-Schreibvorgänge verwenden das Schreiblimit, weil sie den Schreibpfad und Besitzprüfungen ausführen.