Jeder Klick in der Sharkly UI ist eine Entscheidung, die ein Mensch getroffen hat: diese Task anlegen, jenen Agent zuweisen, einen Run prüfen. Das ist die richtige Oberfläche für Ermessensentscheidungen. Es ist die falsche Oberfläche für die tausendste Wiederholung desselben Klicks. Sobald dein Team festgelegt hat, dass jeder fehlgeschlagene nächtliche Build zu einer Task werden soll, ist das Durchklicken durch Bildschirme kein Workflow mehr, sondern eine lästige Pflicht.
Hier kommt die programmatische Oberfläche ins Spiel. Die Sharkly CLI lässt Menschen, Agents und Skripte von einem Terminal aus mit Sharkly arbeiten: Organisationsressourcen verwalten, einen Computer für die Agent-Ausführung registrieren, den lokalen Dienst inspizieren und wiederkehrende Workflows automatisieren. Dahinter steht eine REST-API unter api.sharkly.ai, die dieselben Personal Access Tokens akzeptiert, die auch die CLI verwendet.
Das ist bei Sharkly wichtiger als bei einem typischen PM-Tool, denn Sharkly ist nicht nur der Ort, an dem Arbeit beschrieben wird. Es ist der Ort, an dem Arbeit ausgeführt wird. Sharkly ergänzt Coding-Tools wie Claude Code und Codex um die gemeinsame Ebene für Tasks, Computer, Kontext, Steuerung und Review – ein skriptgesteuertes sharkly task create legt also nicht bloß ein Ticket an. Ist die Task einem Agent zugewiesen und steht sie in einem Ready-Status, kann sie einen echten Run auf einem echten Computer starten. Die Oberfläche zu skripten heißt, die Workforce zu skripten.
TL;DR
Die Sharkly CLI (Befehl sharkly) ermöglicht es Menschen, Agents und Skripten, von einem Terminal aus mit Sharkly zu arbeiten, und sie ist zugleich der Weg, über den der lokale Dienst auf Remote- und Linux-Hosts installiert wird, damit diese als Computer deinem Fleet beitreten können. Die Authentifizierung ist bewusst aufgeteilt: Ein Personal Access Token (Präfix shk_) meldet einen Menschen oder ein Skript an, ein einmaliges Install-Token (Präfix sit_) registriert einen Computer, und Agent-Runs verwenden eine eingeschränkte Ausführungs-Credential, die Sharkly bereitstellt. Mit einem Token können Skripte Tasks erstellen und bearbeiten, sie kommentieren, Runs und Logs einsehen und Computer verwalten – alles mit --output json für saubere Weiterverarbeitung. Dasselbe shk_-Token funktioniert als Bearer-Token gegenüber der REST-API, und Webhook-Trigger von Automations erlauben es CI und anderen externen Systemen, Agent-Runs mit einer POST-Anfrage zu starten.
Eine Plattform, zwei Oberflächen
Die UI von Sharkly und ihre programmatische Oberfläche sind zwei Eingänge in dasselbe System. Die Task, die dein Skript erstellt, ist dieselbe Task, die ein Teammitglied auf dem Board sieht – mit demselben Status, Workflow, denselben Kommentaren und derselben Ausführungshistorie. Skripting umgeht den gemeinsamen Datensatz nie: Automatisierung speist das System of Record.
Eine sinnvolle Aufteilung ergibt sich aus der Frage, wer entscheidet. Nutze die UI, wenn ein Mensch eine Ermessensentscheidung trifft: eine Anforderung schärfen, einen Diff reviewen, ein Ergebnis abnehmen. Nutze die CLI oder API, wenn die Entscheidung bereits gefallen ist und sich nur noch die Mechanik wiederholt: Tasks aus einem Monitoring-System anlegen, Run-Logs in ein Dashboard ziehen, die Computer-Gesundheit per Cronjob prüfen. Ein Skript kann die Task erstellen und sogar den Run auslösen, aber die Abnahme bleibt beim Menschen.
Die CLI installieren – und was sie installiert
Unter macOS oder Linux genügt für die offizielle Installation ein Befehl:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
Für Windows gibt es einen offiziellen PowerShell-Installer, derzeit nur für AMD64. Auf jeder Plattform prüfst und pflegst du die Installation mit:
sharkly version
sharkly update
Die CLI hat neben ihrer Rolle als Client noch eine zweite Funktion. Die Doku beschreibt zwei Wege, einen Computer anzubinden: Sharkly Desktop auf einem unterstützten privaten Rechner installieren oder die Sharkly CLI und den lokalen Dienst auf einem Remote-Host oder Linux-Rechner installieren. Über den zweiten Weg wird ein Build-Server, eine übrig gebliebene Linux-Kiste oder ein Container zur Ausführungskapazität für deine Agents. Der dabei eingerichtete lokale Dienst registriert den Computer, erkennt installierte Runtimes, sendet Heartbeats, empfängt in die Warteschlange gestellte Runs, bereitet Task-Verzeichnisse vor und streamt den Fortschritt zurück – er baut die Verbindung selbst auf, sodass kein eingehender Port nötig ist.
Wenn du deine erste Maschine noch über die UI anbindest, beschreibt der Getting-started-Guide genau diesen Ablauf.
Drei Credentials, drei Aufgaben
Sharkly verwendet getrennte Credentials für getrennte Zwecke, und diese Trennung solltest du verinnerlichen, bevor du irgendetwas automatisierst.
Ein Personal Access Token beginnt mit shk_ und erlaubt es der CLI, einem Skript oder einem anderen vertrauenswürdigen Client, als dein Benutzerkonto zu handeln. Du erstellst eines in den Einstellungen, wählst eine Gültigkeitsdauer von 30 Tagen, 90 Tagen, 1 Jahr oder ohne Ablauf und kopierst den vollständigen Wert einmal bei der Erstellung. Melde dich über den dialogbasierten Flow an, damit das Token nie in der Shell-Historie landet:
sharkly login --token
sharkly auth status
Ein Computer-Install-Token beginnt mit sit_, läuft nach 30 Minuten ab und kann genau einmal verwendet werden. Seine einzige Aufgabe ist die Registrierung eines Computers:
sharkly computer register --install-token sit_...
Die dritte Credential bekommst du nie zu Gesicht: Ein aktiver Agent-Run erhält eine eingeschränkte Ausführungs-Credential von Sharkly, die auf die Befehlsklassen beschränkt ist, die sein Ausführungskontext zulässt.
Die Doku zieht die Grenze klar: Ein Personal Access Token registriert keinen Computer, und ein Install-Token erstellt keinen menschlichen CLI-Login. Die Registrierung erzeugt eine unabhängige Local-Service-Session – deshalb bringt das spätere Widerrufen deines persönlichen Tokens deine registrierten Computer nicht offline. Ebenso entfernt sharkly auth logout das Token nur aus deinem lokalen Profil; auf dem Server bleibt es gültig, bis du es in den Einstellungen widerrufst.
In CI lässt du den Login-Flow komplett weg. Die CLI liest das Token aus der Umgebungsvariable SHARKLY_TOKEN, die Vorrang vor jedem gespeicherten Profil hat. Befülle sie aus einem geschützten Secret Store wie GitHub Actions Secrets, statt das Token in die Workflow-Datei zu schreiben, und gib die Organisation explizit mit --organization-id an.
Einen Fleet von Computern vom Terminal aus verwalten
Sobald Hosts registriert sind, deckt die Befehlgruppe sharkly computer Inspektion und Wartung ohne Browser ab:
sharkly computer list --output json
sharkly computer show <computer-id> --output json
sharkly computer usage <computer-id> <runtime-id> --days 30 --output json
sharkly computer ping <computer-id> <runtime-id> --wait --output json
sharkly computer update <computer-id> <runtime-id>
list zeigt die für die aktuelle Organisation registrierten Computer, show gibt einen Computer samt seiner Runtimes zurück, usage untersucht eine bestimmte Runtime, ping prüft, ob diese Runtime einen Round Trip abschließen kann, und update fordert ein CLI-Update für eine Runtime an. Der Unterschied, für den es ping gibt: Dass ein Computer online ist, bedeutet nur, dass sein lokaler Dienst Heartbeats sendet – nicht, dass eine bestimmte Runtime gerade einen Run ausführen kann.
Auf dem Host selbst nutzt du für die Routine-Diagnose die benutzerorientierten Befehle:
sharkly computer status --output json
sharkly computer logs --lines 100
Der daemon-Namensraum stellt Prozess-Lebenszyklus- und Festplatten-Steuerung bereit, darunter sharkly daemon disk-usage und sharkly daemon cleanup, wobei letzteres ein Dry Run ist, sofern du nicht --confirm ergänzt. Die Entscheidungsregel aus der Doku: Für die Routine-Diagnose sind computer status und computer logs die erste Wahl; greife nur dann zu daemon, wenn du Prozess-Lebenszyklus, Festplatten-Reporting oder Cleanup brauchst. Der Computers-Beitrag in dieser Reihe geht tiefer auf Ownership, Sichtbarkeit und Cleanup-Richtlinien ein.
Tasks per Skript: Arbeit, die ohne Meeting ankommt
Bei Tasks verdient sich die CLI ihren Platz in einer Pipeline. Die Befehlgruppe liest sich wie eine skriptbare Version des Boards:
sharkly task list --output json
sharkly task search "authentication error" --output json
sharkly task create --title "Investigate authentication error" --output json
sharkly task edit <task-id> --status <status> --output json
sharkly task comment <task-id> --body "Investigation started." --output json
Der naheliegendste CI-Anwendungsfall ist das automatische Anlegen von Arbeit. Ein nächtlicher Job, der ein fehlgeschlagenes Release erkennt, braucht niemanden, der ein Formular ausfüllt:
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
Nutze --body-file oder --body-stdin, wann immer es auf exakten Inhalt ankommt, denn die kurze Form --body dekodiert Escape-Sequenzen. Und da eine einem Agent zugewiesene Task einen Run startet, sobald sie in einem Ready-Status steht, kann dieser eine Befehl der Anfang eines vollständig automatisierten Kreislaufs sein: Das Skript legt die Task an, der zugewiesene Agent übernimmt sie, und Ausführung, Blocker und Ergebnis landen wieder in der Task, wo ein Mensch sie am nächsten Morgen prüft.
Reporting-Skripte bekommen echte Filter statt clientseitigem Durchsuchen. Du kannst nach dem Alter des Status mit --status-changed-within 7d filtern sowie nach benutzerdefinierten Feldern:
sharkly task list --space HF --field "Customer Tier=VIP" --output json
Mehrfach angegebene --field-Flags werden mit AND verknüpft, der Abgleich ist typbewusst und exakt, und gefiltert wird serverseitig vor der Paginierung. Übernimm die Skripting-Konventionen aus der Doku am besten vollständig: --output json explizit anfordern, --color never und --quiet ergänzen, --organization-id sichtbar halten und set -euo pipefail verwenden. Die Exit-Codes sind vertraglich zugesichert: 0 für Erfolg, 1 für Befehls-, Validierungs-, Authentifizierungs- oder Remote-API-Fehler und 2 für vorübergehende Probleme mit dem lokalen Dienst oder dem Netzwerk – das macht Retry-Logik unkompliziert.
Die CLI beschreibt sich außerdem selbst. sharkly schema task create --format json legt die Befehlsregistrierung maschinenlesbar offen, und sharkly tldr task liefert kuratierte Szenarien – was dann wichtig ist, wenn das, was das Skript schreibt, selbst ein Agent ist.
Runs beobachten, ohne ein Dashboard zu öffnen
Die Ausführung lässt sich über dieselbe Oberfläche beobachten:
sharkly run list --task <task-id> --output json
sharkly run view <run-id> --output json
sharkly run log <run-id> --since <sequence> --output json
sharkly run cancel <run-id> --output json
Das --since-Flag macht Polling vernünftig: Ein Monitoring-Skript merkt sich die zuletzt verarbeitete Sequenznummer und holt bei jedem Durchlauf nur neuere Meldungen. Kombiniere das mit sharkly agent list, sharkly automation view und sharkly automation runs, und du kannst aus einem Shell-Skript und jq eine Statusseite für deine Agent-Workforce bauen.
Die REST-API und Webhooks
Alles, was die CLI tut, läuft über die REST-API, und die Doku zeigt den direkten Weg: Sende dein Personal Access Token als Bearer-Token über HTTPS.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
Der Zugriff über die API ist durch die Berechtigungen des Nutzers hinter dem Token begrenzt; das aktuelle Token-Modell kennt keine Auswahl von Scopes pro Token – ein guter Grund, für jeden Dienst ein eigenes Token mit definierter Gültigkeitsdauer anzulegen. Die Endpoint-Referenz findest du unter docs.sharkly.ai, und die --output json-Antworten der CLI sind eine getreue Vorschau auf die Strukturen, mit denen du arbeiten wirst.
Der Verkehr fließt auch in die andere Richtung. Eine Automation kann einen Webhook-Trigger mitbringen: Sharkly generiert eine geheime URL, die eine POST-Anfrage annimmt, und eine gültige Anfrage startet den Agent- oder Crew-Run der Automation. Die vollständige URL wird einmal angezeigt und fungiert standardmäßig als Bearer-Secret, mit optionaler Signaturprüfung. Das ist die eingehende Hälfte der CI-Geschichte: Deine Pipeline sagt Sharkly „etwas ist passiert, starte den Triage-Agent“.
Es lohnt sich, genau zu benennen, was diese Oberfläche nicht ist. Die Sharkly CLI ist kein weiterer Coding-Agent, und die API ist kein Model-Endpoint. Runtimes wie Claude Code und Codex führen die Ausführung durch; die programmatische Oberfläche von Sharkly verwaltet die Ebene darum herum. Diese Neutralität unterscheidet sie von ökosystemgebundenen Optionen wie GitHub Agent HQ, wo Automatisierungsoberfläche und Ausführung innerhalb der Mauern eines einzigen Anbieters liegen.
Wo du anfangen solltest
Fang kleiner an, als du denkst. Erstelle ein Personal Access Token mit 90 Tagen Gültigkeit, führe sharkly login --token aus und skripte den langweiligsten Lesevorgang, den du täglich machst – etwa eine Task-Liste, die per jq in eine Morgen-Zusammenfassung fließt. Lesezugriffe sind ungefährlich und bringen dir die JSON-Strukturen näher. Automatisiere dann einen Schreibvorgang mit eindeutigem Auslöser, etwa das Anlegen einer Task aus einem fehlgeschlagenen CI-Job. Einen Webhook-Trigger richtest du erst ein, wenn sich beides routiniert anfühlt.
Das Muster, das es zu bewahren gilt, ist das, auf dem die ganze Plattform aufbaut: Skripte und Agents erzeugen und erledigen die Arbeit, und Kontext, Fortschritt, Blocker, Ergebnisse und menschliches Review bleiben von der Anfrage bis zum Release sichtbar. Automatisiere die Eingänge. Behalte das Review.
FAQ
Brauche ich die CLI, um Sharkly zu nutzen?
Nein. Sharkly Desktop deckt das Anbinden eines privaten Rechners ab, und die Web-App deckt die tägliche Arbeit mit Tasks ab. Notwendig wird die CLI, wenn du einen Remote-Host oder Linux-Rechner anbindest, denn dort ist die Installation der Sharkly CLI und des lokalen Dienstes der dokumentierte Einrichtungsweg. Wertvoll wird sie immer dann, wenn sich ein Workflow oft genug wiederholt, dass das Durchklicken Zeit kostet.
Worin unterscheiden sich ein Personal Access Token und ein Install-Token?
Ein Personal Access Token (Präfix shk_) authentifiziert einen Menschen oder ein Skript als dein Benutzerkonto – für CLI-Logins, CI-Jobs und direkte API-Anfragen. Ein Computer-Install-Token (Präfix sit_) ist einmalig und kurzlebig, läuft nach 30 Minuten ab und registriert ausschließlich einen Computer. Keines ersetzt das andere.
Kann ich die Sharkly REST-API direkt aufrufen, statt die CLI zu verwenden?
Ja. Sende ein Personal Access Token als Bearer-Token über HTTPS an api.sharkly.ai; in der Doku ist curl -fsS https://api.sharkly.ai/rest/v1/users/current mit einem Authorization: Bearer-Header das gezeigte Muster. Das Token trägt die Berechtigungen deines Benutzerkontos.
Wie erstelle ich eine Task aus einer CI-Pipeline?
Speichere ein shk_-Token als geschütztes CI-Secret und stelle es als Umgebungsvariable SHARKLY_TOKEN bereit, die die CLI automatisch liest. Führe dann sharkly task create mit --title, --body-file für exakten mehrzeiligen Inhalt, einer expliziten --organization-id und --output json aus, damit der Job die ID der erstellten Task erfassen kann.
Bringt das Widerrufen meines Personal Access Tokens meine registrierten Computer zum Stillstand?
Nein. Die Computer-Registrierung erzeugt über das Install-Token eine unabhängige Local-Service-Session, daher stoppt das Widerrufen eines Personal Access Tokens diese Computer nicht. Der Widerruf macht das Token allerdings überall ungültig, wo es für CLI-, API- und Automation-Anfragen verwendet wird – deshalb sollten bei einer Rotation die abhängigen Skripte aktualisiert werden, bevor das alte Token widerrufen wird.
