CLI-Referenz¶

Diese Seite dokumentiert alle verfügbaren Polycrate-CLI-Befehle mit ihren Optionen und Parametern.

Grundlegende Befehle¶

polycrate version¶

Zeigt die aktuelle Version von Polycrate an.

polycrate version

polycrate help¶

Zeigt Hilfe zu Polycrate-Befehlen an.

polycrate help [command]

polycrate update¶

Aktualisiert Polycrate auf die neueste Version.

polycrate update [version]

Parameter:

• version (optional) - Spezifische Version, auf die aktualisiert werden soll

Beispiel:

polycrate update
polycrate update 0.22.1

Workspace-Verwaltung¶

polycrate workspace¶

Verwaltet den Workspace.

polycrate workspace create¶

Erstellt einen neuen Workspace über die Polycrate API — inklusive GitLab-Repository, Encryption-Credential und lokalem Clone.

polycrate workspace create ORG_NAME WORKSPACE_NAME [PATH] [flags]

Voraussetzungen:

• API muss konfiguriert sein (api.enabled: true, api.api_key)
• Organisation muss existieren und zugänglich sein
• PoP-Name muss angegeben werden (--pop)

Flags:

Beispiele:

# Standard: Clone nach ~/.polycrate/workspaces/acme/production
polycrate workspace create acme production --pop fra1

# Mit SSH-Key-Generierung
polycrate workspace create acme production --pop fra1 --with-ssh-keys

# Expliziter Zielpfad
polycrate workspace create acme production --pop fra1 /data/workspaces/production

Ablauf:

1. Organisation per API auflösen (Name → UUID)
2. PoP per API auflösen (Name → UUID)
3. Workspace über API erstellen (GitLab-Repo + Encryption-Credential werden automatisch angelegt)
4. Polling bis Repository und Credential bereit sind
5. Repository per SSH klonen (kein system-git erforderlich)
6. Lokale workspace.poly initialisieren

polycrate workspace init / polycrate init¶

Initialisiert einen neuen Workspace.

mkdir my-workspace
cd my-workspace
polycrate workspace init --with-name my-workspace

# Kurzform (Alias)
polycrate init --with-name my-workspace

Hinweis: Der Befehl muss im Zielverzeichnis ausgeführt werden. Alternativ kann der Pfad mit --workspace <pfad> übergeben werden. polycrate init ist ein Alias für polycrate workspace init.

polycrate workspace inspect¶

Zeigt detaillierte Informationen über den Workspace an.

polycrate workspace inspect

polycrate workspace snapshot¶

Zeigt den aktuellen Workspace-Snapshot an.

polycrate workspace snapshot

Verwendung:

# Snapshot als YAML ausgeben
polycrate workspace snapshot

# Snapshot in Datei speichern
polycrate workspace snapshot > snapshot.yml

polycrate workspace encrypt¶

Verschlüsselt alle sensiblen Workspace-Dateien (secrets.poly und alle Dateien in artifacts/secrets/) mit age-Verschlüsselung.

polycrate workspace encrypt

Key-Quellen (in Prioritätsreihenfolge):

1. Polycrate API (automatisch wenn api.enabled: true)
2. WORKSPACE_ENCRYPTION_KEY Umgebungsvariable
3. Interaktiver Prompt

Beispiele:

# Mit API (automatisch)
polycrate workspace encrypt

# Mit Umgebungsvariable
export WORKSPACE_ENCRYPTION_KEY="AGE-SECRET-KEY-..."
polycrate workspace encrypt

polycrate workspace decrypt¶

Entschlüsselt alle verschlüsselten Workspace-Dateien (alle .age-Dateien in secrets.poly.age und artifacts/secrets/**/*.age).

polycrate workspace decrypt

Beispiel:

export WORKSPACE_ENCRYPTION_KEY="AGE-SECRET-KEY-..."
polycrate workspace decrypt

polycrate workspace status¶

Zeigt den umfassenden Verschlüsselungsstatus des Workspace an, einschließlich Key-Verfügbarkeit, Datei-Status, Git-Status und Empfehlungen.

polycrate workspace status

Zeigt an:

• Key-Status und Quelle (API, ENV, oder nicht verfügbar)
• Verschlüsselte und unverschlüsselte Dateien
• .gitignore-Schutzstatus
• Git-Repository-Informationen (Branch, Commit, Remote-Status)
• Sicherheitsempfehlungen

Beispiel:

polycrate workspace status
# Ausgabe:
# Workspace: https://polycrate.example.com/workspaces/abc123
# 🔑 Key Status: ✅ Key available
# 📁 File Status: 4 encrypted files
# 🔒 Security Status: ✅ All checks passed

polycrate workspace update¶

Aktualisiert Workspace-Dependencies.

polycrate workspace update

polycrate workspace list¶

Listet Workspaces aus der Polycrate API (Standard) oder aus dem lokalen Workspace-Verzeichnis auf.

# API-Workspaces (Standard, oder Fallback auf lokal wenn keine API)
polycrate workspace list

# Explizit lokale Workspaces
polycrate workspace list --local

# Mit Vorfilter
polycrate workspace list --filter production

# Tabellenausgabe ohne TUI
polycrate workspace list --no-pager

# Detaillierte Tabellenausgabe (lokal)
polycrate workspace list --local --no-pager -v

Optionen:

Modus-Entscheidung:

• --local=true → Lokale Workspaces aus ~/.polycrate/workspaces/
• --local=false (Standard):
  • API konfiguriert → Workspaces aus der Polycrate API
  • API nicht konfiguriert → Automatischer Fallback auf lokal

TUI-Navigation:

Action-Menü (Remote/API):

• open – Workspace in der Polycrate UI öffnen (Browser)
• gitlab – GitLab-Repository im Browser öffnen
• clone – Repository lokal klonen

Action-Menü (Lokal):

• open – Workspace-Details und Pfad anzeigen
• status – Workspace-Status abrufen
• git-sync – Git-Änderungen synchronisieren

polycrate workspace changelog¶

Zeigt das Workspace-Changelog in einer interaktiven TUI an.

# Interaktive TUI
polycrate workspace changelog

# Changelog-Format anzeigen (für LLMs)
polycrate workspace changelog --spec

# Ohne TUI
polycrate workspace changelog --no-tui

Optionen:

Das Changelog wird aus CHANGELOG.poly im Workspace-Root gelesen.

Workspace Git-Aliase¶

Diese Commands sind Aliase für die entsprechenden polycrate git * Commands und ermöglichen eine intuitivere UX, bei der alle Workspace-bezogenen Operationen unter polycrate workspace verfügbar sind.

polycrate workspace pull¶

Pullt Änderungen vom Remote-Repository. Alias für polycrate git pull.

polycrate workspace pull
polycrate workspace pull --remote origin --branch main

polycrate workspace push¶

Pusht Commits zum Remote-Repository. Alias für polycrate git push.

polycrate workspace push
polycrate workspace push --remote origin --branch main

polycrate workspace sync¶

Automatischer Sync-Workflow: Stage → Commit → Pull → Push. Alias für polycrate git sync.

polycrate workspace sync

Ablauf:

1. Prüft auf uncommitted Changes → Auto-Commit
2. Fetch vom Remote
3. Pull bei Remote-Änderungen
4. Push lokaler Commits

polycrate workspace add¶

Stagt Dateien für den nächsten Commit. Alias für polycrate git add.

polycrate workspace add file.txt
polycrate workspace add blocks/my-block/
polycrate workspace add --all

polycrate workspace commit¶

Erstellt einen Commit. Alias für polycrate git commit.

polycrate workspace commit -m "feat: add feature"
polycrate workspace commit --message "fix: bug"

Ohne -m Flag wird interaktiv nach der Commit-Message gefragt.

Block-Verwaltung¶

polycrate block¶

Verwaltet Blocks im Workspace.

polycrate block list¶

Listet alle Blocks im Workspace auf.

polycrate block list

Beispiel:

polycrate block list
# Ausgabe:
# - ayedo/k8s/cluster
# - ayedo/docker/stack

polycrate block init¶

Initialisiert einen neuen Block eines spezifischen Typs.

polycrate block init <block-name> [options]

Optionen:

• --kind <kind> - Art des Blocks (z.B. ansible, script)

Beispiel:

polycrate block init my-block --kind ansible

polycrate block inspect¶

Zeigt detaillierte Informationen über einen Block an.

polycrate block inspect <block-name>

Beispiel:

polycrate block inspect ayedo/k8s/cluster

polycrate blocks pull / polycrate pull¶

Lädt einen Block aus der Registry herunter.

polycrate blocks pull <registry/path/block-name>:<version> [--workspace <pfad>]
# Kurzform:
polycrate pull <registry/path/block-name>:<version> [--workspace <pfad>]

Parameter:

• registry/path/block-name - Vollständiger Registry-Pfad zum Block (Pflicht)
• version - Version des Blocks (Pflicht, oder latest)

Optionen:

• --workspace <pfad> - Workspace-Pfad für die Block-Installation (Standard: aktuelles Verzeichnis)

Beispiele:

# Von cargo.ayedo.cloud pullen
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.2.0

# Kurzform
polycrate pull cargo.ayedo.cloud/ayedo/k8s/polycrate-operator:0.3.33

# Von eigener Registry pullen
polycrate blocks pull registry.my-org.com/infra/postgres:1.0.0

# Neueste Version
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/victoria-metrics-stack:latest

polycrate blocks push¶

Lädt einen Block in die Registry hoch.

polycrate blocks push <registry/path/block-name> [--exclude <pattern> ...]

Parameter:

• block-name - Name des Blocks (kann Registry-URL enthalten)

Optionen:

• --exclude <pattern> - Glob-Patterns zum Ausschluss vom OCI-Image (mehrfach nutzbar, z.B. --exclude .specs --exclude "*.log")
• --workspace <pfad> - Workspace-Pfad (Standard: aktuelles Verzeichnis)

Hinweis: Beim Pushen eines Blocks wird die Version aus der block.poly automatisch als Tag verwendet. Geben Sie kein Tag im Block-Namen an. Standardmäßig wird .specs/ ausgeschlossen.

→ Vollständige Dokumentation: Registry – Exclude-Patterns beim Push

Beispiele:

# Block zum Standard-Registry pushen
polycrate blocks push cargo.ayedo.cloud/ayedo/k8s/cluster

# Zu custom Registry pushen
polycrate blocks push my.registry.com/my-org/my-block

# Mit zusätzlichen Excludes
polycrate blocks push cargo.ayedo.cloud/my-org/my-block --exclude .git --exclude "*.log"

# Kurzform (Alias für blocks push)
polycrate push cargo.ayedo.cloud/my-org/my-block

polycrate block readme¶

Zeigt die README-Datei eines Blocks an.

polycrate block readme <block-name>

Beispiel:

polycrate block readme ayedo/k8s/cluster

polycrate block validate¶

Validiert die Konfiguration eines Blocks.

polycrate block validate <block-name>

Beispiel:

polycrate block validate ayedo/k8s/cluster

polycrate block changelog¶

Zeigt das Changelog eines Blocks in einer interaktiven TUI an.

# Interaktive TUI
polycrate block changelog <block-name>

# Changelog-Format anzeigen
polycrate block changelog <block-name> --spec

# Ohne TUI
polycrate block changelog <block-name> --no-tui

Optionen:

Beispiel:

polycrate block changelog postgres-base

Das Changelog wird aus CHANGELOG.poly im Block-Verzeichnis gelesen.

Action-Verwaltung¶

polycrate run¶

Führt eine Action oder einen Workflow aus.

polycrate run <block-name> <action-name> [options]
polycrate run <workflow-name> [options]

Optionen:

• -f, --force - Bestätigt alle Prompts automatisch
• -K, --ask-become-pass - Fordert das Ansible become/sudo-Passwort interaktiv an
• -l, --local - Führt die Action lokal aus (ohne Container)
• -i, --interactive - Macht den Container interaktiv
• -b, --build - Baut ein Custom Image aus dem Workspace Dockerfile.poly (Standard: true)
• -p, --pull - Pullt das Workspace Image vor der Ausführung (Standard: true)
• -e, --env <KEY=value> - Zusätzliche Umgebungsvariablen
• -m, --mount <host:container> - Zusätzliche Mounts für den Container
• --set <key=value> - Override von action.config (Helm-Style, mehrfach nutzbar, z.B. --set database.host=prod.local)
• --snapshot - Zeigt nur den Workspace-Snapshot an, führt nichts aus

→ Vollständige --set-Dokumentation: Actions – Runtime Config Overrides

Beispiele:

# Action ausführen
polycrate run my-block install

# Mit force flag (keine Prompts)
polycrate run my-block install --force

# Lokal ausführen (ohne Container)
polycrate run my-block install --local

# Mit Ansible become/sudo-Passwort (für Playbooks mit become: yes)
polycrate run my-block install --ask-become-pass

# Mit zusätzlichen Umgebungsvariablen
polycrate run my-block install -e ENV=prod -e REGION=eu-west-1

# Mit action.config Overrides (--set)
polycrate run my-block migrate --set database.host=prod-db.internal --set database.port=5433

# Nur Snapshot anzeigen
polycrate run my-block install --snapshot

polycrate install¶

Führt die install Action eines Blocks aus.

polycrate install <block-name> [options]

Beispiel:

polycrate install ayedo/k8s/cluster

polycrate uninstall¶

Führt die uninstall Action eines Blocks aus.

polycrate uninstall <block-name> [options]

Beispiel:

polycrate uninstall ayedo/k8s/cluster

polycrate prune¶

Führt die prune Action eines Blocks aus (typischerweise zum Aufräumen von Artefakten).

polycrate prune <block-name> [options]

Beispiel:

polycrate prune ayedo/k8s/cluster

polycrate action¶

Verwaltet Actions.

polycrate action list¶

Listet alle verfügbaren Actions im Workspace auf.

polycrate action list

polycrate action inspect¶

Zeigt detaillierte Informationen über eine Action an.

polycrate action inspect <block-name> <action-name>

Beispiel:

polycrate action inspect my-block install

polycrate action run¶

Führt eine Action aus (identisch mit polycrate run).

polycrate action run <block-name> <action-name>

Workflow-Verwaltung¶

polycrate workflow¶

Verwaltet Workflows.

polycrate workflow list¶

Listet alle verfügbaren Workflows im Workspace auf.

polycrate workflow list

polycrate workflow inspect¶

Zeigt detaillierte Informationen über einen Workflow an.

polycrate workflow inspect <workflow-name>

Beispiel:

polycrate workflow inspect deploy-all

polycrate workflow run¶

Führt einen Workflow aus.

polycrate workflow run <workflow-name> [options]

Optionen: Identisch mit polycrate run

Beispiel:

polycrate workflow run deploy-all --force

PolyHub-Integration¶

polycrate hub¶

Interagiert mit dem Polycrate Hub.

polycrate hub list¶

Listet alle Blöcke im Hub mit interaktiver TUI.

# Interaktive TUI (Standard)
polycrate hub list

# Mit Filter
polycrate hub list --filter postgres

# Nach Kind filtern
polycrate hub list --kind k8sapp

# Tabellenausgabe ohne TUI
polycrate hub list --no-tui

Optionen:

TUI-Navigation:

Action-Menü nach Auswahl:

• view-versions – Alle Versionen anzeigen
• view-block – block.poly anzeigen
• view-readme – README anzeigen
• copy-name – Block-Name zum Kopieren

polycrate hub inspect¶

Zeigt Informationen über einen Block im PolyHub an.

polycrate hub inspect <block-name>

Optionen:

Beispiele:

polycrate hub inspect ayedo/k8s/cluster
polycrate hub inspect postgres-base --readme
polycrate hub inspect postgres-base:1.2.0

API-Integration¶

polycrate api¶

Zeigt API-Informationen an.

polycrate api

Optionen:

• --api-enabled - Aktiviert API-Integration
• --api-url <url> - API-URL (Standard: https://hub.polycrate.io)
• --api-api-key <key> - API-Key für Authentifizierung
• --api-submit-action-runs - Sendet Action-Ergebnisse an API (Standard: true)

Container-Debugging¶

polycrate debug¶

Startet eine interaktive Debug-Shell im Polycrate-Container mit der gleichen Konfiguration wie bei einem Action Run.

polycrate debug [options]

Beschreibung:

Der debug Befehl startet den Polycrate-Container mit allen Mounts, Environment-Variablen und Netzwerk-Konfiguration wie bei einem normalen Action Run, öffnet aber statt einer Action auszuführen eine interaktive Bash-Shell.

Optionen:

Beispiele:

# Debug-Container im aktuellen Workspace starten
polycrate debug

# Mit explizitem Workspace-Pfad
polycrate debug -w /path/to/workspace

# Mit zusätzlichen Mounts
polycrate debug -m /local/path:/container/path

# Mit zusätzlichen Environment-Variablen
polycrate debug -e MY_VAR=value

# Mit Native Docker Mode
polycrate -N debug

Ausgabe:

$ polycrate debug
✓ Pulling image cargo.ayedo.cloud/library/polycrate:0.28.0

Starting debug container: polycrate-debug-a1b2c3d4
Workspace: /home/user/my-workspace
Image: cargo.ayedo.cloud/library/polycrate:0.28.0
Type 'exit' to leave the container

root@polycrate:/workspace# kubectl get pods -A
root@polycrate:/workspace# exit
$

Use Cases:

• Playbook-Debugging: Ansible-Playbooks manuell ausführen und testen
• Environment-Inspektion: Prüfen welche Variablen im Container gesetzt sind
• Pfad-Validierung: Überprüfen ob Mounts korrekt ankommen
• Tool-Verfügbarkeit: Testen ob benötigte Tools im Image vorhanden sind
• Netzwerk-Debugging: Netzwerkverbindungen aus dem Container testen

Kubernetes¶

polycrate k8s debug¶

Startet einen Debug-Pod im Kubernetes-Cluster mit dem Polycrate-Image und verbindet sich automatisch.

polycrate k8s debug [options]

Beschreibung:

Der k8s debug Befehl erstellt temporär:

1. Einen ServiceAccount polycrate-admin (falls nicht vorhanden)
2. Ein ClusterRoleBinding mit cluster-admin Rechten
3. Einen Debug-Pod mit dem Polycrate-Image

Nach Beenden der Shell wird der Pod automatisch gelöscht.

Optionen:

Voraussetzungen:

• Gültiger Workspace mit Kubeconfig (kubeconfig.yml oder artifacts/secrets/kubeconfig.yml)
• Cluster-Admin-Berechtigung zum Erstellen von ServiceAccounts und ClusterRoleBindings

Beispiele:

# Debug-Pod in kube-system starten
polycrate k8s debug

# Debug-Pod in anderem Namespace
polycrate k8s debug -n default

# Mit explizitem Workspace
polycrate k8s debug -w /path/to/workspace

Ablauf:

$ polycrate k8s debug
INFO Starting debug pod polycrate-debug-1701234567 in namespace kube-system
INFO Creating service account polycrate-admin in namespace kube-system
INFO Creating cluster role binding polycrate-admin-cluster-admin
INFO Pod polycrate-debug-1701234567 created, waiting for it to be ready...
INFO Pod is running, attaching...

# Jetzt in der interaktiven Shell im Cluster:
bash-5.1# kubectl get pods -A
bash-5.1# helm list -A
bash-5.1# exit

INFO Debug session ended
INFO Cleaning up debug pod polycrate-debug-1701234567...
INFO Debug pod deleted

Use Cases:

• Cluster-Debugging: Direkter Zugriff auf den Cluster mit allen Polycrate-Tools
• Netzwerk-Tests: Testen von Service-Konnektivität innerhalb des Clusters
• Helm/Kubectl: Ausführen von Helm- oder Kubectl-Befehlen im Cluster-Kontext
• Log-Analyse: Zugriff auf Logs und Ressourcen ohne lokale Kubeconfig

Git-Integration¶

Native Git-Integration ohne externe Git-Installation (basiert auf go-git).

polycrate git status¶

Zeigt den Git-Status des Workspace-Repositories.

polycrate git status

Farbcodierung:

• new: (grün) – Neue Datei
• modified: (gelb) – Geänderte Datei
• deleted: (rot) – Gelöschte Datei
• renamed:/copied: (cyan) – Umbenannte/Kopierte Datei

polycrate git add¶

Stagt Dateien für den nächsten Commit.

# Einzelne Datei
polycrate git add <datei>

# Alle Änderungen
polycrate git add --all
polycrate git add -a

polycrate git commit¶

Erstellt einen neuen Commit.

polycrate git commit --message "Commit-Nachricht"
polycrate git commit -m "Commit-Nachricht"

polycrate git push¶

Pusht Commits zum Remote-Repository.

polycrate git push

polycrate git pull¶

Pullt Änderungen vom Remote-Repository. Prüft vorher auf Konflikte.

polycrate git pull

polycrate git sync¶

Automatischer Sync-Workflow: Stage → Commit → Pull → Push.

polycrate git sync

Ablauf:

1. Alle Änderungen stagen
2. Automatischer Commit
3. Remote-Änderungen pullen
4. Lokale Commits pushen

Operator¶

Der Polycrate Operator ermöglicht automatisiertes Multi-Tenant-Management über Keycloak, GitLab, Harbor, ArgoCD und Kubernetes Cluster.

polycrate operator crds¶

Gibt CRD-Definitionen für die Installation aus.

# Alle CRDs ausgeben
polycrate operator crds

# Bestimmten CRD-Typ ausgeben
polycrate operator crds --kind Organization

# CRDs in Dateien speichern
polycrate operator crds --output-dir ./crds/

# Nur CRD-Namen auflisten
polycrate operator crds --list

Optionen:

polycrate operator install-crds¶

Installiert alle Operator-CRDs direkt ins Kubernetes Cluster.

# Mit Standard-Kubeconfig
polycrate operator install-crds

# Mit spezifischer Kubeconfig
polycrate operator install-crds --kubeconfig ~/.kube/admin.yaml

# Dry-run (zeigt was installiert würde)
polycrate operator install-crds --dry-run

Optionen:

Ausgabe:

Installing Polycrate Operator CRDs
==================================
Cluster: https://kubernetes.example.com:6443

✓ softwaredeliveryplatforms.polycrate.io: created
✓ organizations.polycrate.io: created
✓ contactgroups.polycrate.io: created
✓ contacts.polycrate.io: created
✓ gitlabgroups.polycrate.io: created
✓ harborprojects.polycrate.io: created
✓ argocdprojects.polycrate.io: created
✓ k8sclusters.polycrate.io: created
✓ operatorconfigs.polycrate.io: created

Summary: 9 installed, 0 updated, 0 failed

polycrate operator run¶

Startet den Polycrate Operator.

# Lokal mit Kubeconfig
polycrate operator run --kubeconfig ~/.kube/config

# Mit Leader Election (für HA-Deployments)
polycrate operator run --leader-elect

# Mit Metrics aktiviert
polycrate operator run --metrics-bind-address :8080

Optionen:

Endpoints:

polycrate operator health¶

Prüft den Health-Status eines laufenden Operators.

# Lokalen Operator prüfen (Standard: localhost:8081)
polycrate operator health

# Remote-Operator prüfen
polycrate operator health --url http://polycrate-operator.polycrate:8081

Optionen:

Ausgabe:

Polycrate Operator Health Check
================================
URL: http://localhost:8081

✓ Liveness (healthz):  OK
✓ Readiness (readyz):  OK

Status: HEALTHY

polycrate operator status¶

Zeigt den Status aller Operator Custom Resources im Cluster.

# Status aller Ressourcen anzeigen
polycrate operator status

# Mit spezifischer Kubeconfig
polycrate operator status --kubeconfig ~/.kube/config

Optionen:

Ausgabe:

Polycrate Operator Status
=========================
Cluster: https://kubernetes.example.com:6443

SoftwareDeliveryPlatforms
-------------------------
  NAME        NAMESPACE    PHASE   KEYCLOAK  GITLAB  HARBOR  ARGOCD
  production  polycrate    Ready   ✓         ✓       ✓       ✓

Organizations
-------------
  NAME       NAMESPACE    SDP         PHASE
  acme-corp  polycrate    production  Ready

ContactGroups
-------------
  NAME             NAMESPACE    SDP(s)        PHASE
  platform-admins  polycrate    [production]  Ready

Contacts
--------
  NAME      NAMESPACE    EMAIL                  ORGANIZATIONS  PHASE
  john-doe  polycrate    john.doe@example.com   acme-corp      Ready

K8sClusters
-----------
  NAME               NAMESPACE    API SERVER                        PHASE      K8S VERSION
  production-cluster polycrate    https://api.prod.example.com:6443 Connected  1.28.4

Weitere Befehle¶

polycrate checksum¶

Berechnet die MD5-Checksumme eines Verzeichnisses.

polycrate checksum <directory>

Beispiel:

polycrate checksum ./blocks/my-block

polycrate completion¶

Generiert Autocompletion-Skripte für verschiedene Shells. Polycrate unterstützt dynamische Completion, d.h. kontextabhängige Vorschläge wie z.B. verfügbare SSH-Hosts.

polycrate completion <shell>

Unterstützte Shells:

• bash
• zsh
• fish
• powershell

Einrichtung:

# Einmalig aktivieren
source <(polycrate completion zsh)

# Permanent (in ~/.zshrc)
echo 'source <(polycrate completion zsh)' >> ~/.zshrc

# Einmalig aktivieren
source <(polycrate completion bash)

# Permanent (in ~/.bashrc)
echo 'source <(polycrate completion bash)' >> ~/.bashrc

# Oder systemweit
polycrate completion bash > /etc/bash_completion.d/polycrate

polycrate completion fish > ~/.config/fish/completions/polycrate.fish

polycrate completion powershell | Out-String | Invoke-Expression

# Permanent (in Profil)
polycrate completion powershell >> $PROFILE

Features:

• Command-Completion: Alle Polycrate-Befehle und Flags
• SSH-Host-Completion: polycrate ssh <TAB> zeigt verfügbare Hosts aus dem Inventory
• Block-Completion: Block-Namen werden vorgeschlagen

Beispiel:

polycrate ssh <TAB>
# web-1    ubuntu@192.168.1.10
# web-2    ubuntu@192.168.1.11
# db-1     postgres@192.168.1.20

Globale Flags¶

Diese Flags können mit jedem Befehl verwendet werden:

Docker & Container¶

• -N, --docker-native - Native Docker SDK statt Docker CLI verwenden (experimentell)
• --no-pager - Deaktiviert den interaktiven TUI-Pager für Output
• --non-interactive - Erzwingt nicht-interaktiven Modus (überspringt alle Prompts)

Workspace-Konfiguration¶

• -w, --workspace <path> - Pfad zum Workspace (Standard: $PWD)
• --workspace-config <file> - Name der Workspace-Config-Datei (Standard: workspace.poly)
• --workspace-dir <path> - Pfad zum Workspaces-Verzeichnis (Standard: ~/.polycrate/workspaces)

Block-Konfiguration¶

• --blocks-root <path> - Blocks-Root-Verzeichnis (Standard: blocks)
• --blocks-config <file> - Name der Block-Config-Datei (Standard: block.poly)
• --blocks-auto-pull - Automatisches Pullen fehlender Blocks (Standard: false)

Container-Konfiguration¶

• --image-ref <ref> - Workspace-Image-Referenz (Standard: cargo.ayedo.cloud/library/polycrate)
• --image-version <version> - Workspace-Image-Version (Standard: latest)
• --dockerfile <file> - Workspace-Dockerfile (Standard: Dockerfile.poly)
• --container-root <path> - Container-Root-Verzeichnis (Standard: /workspace)

Artefakte¶

• --artifacts-root <path> - Artefakte-Root-Verzeichnis (Standard: artifacts)
• --workflows-root <path> - Workflows-Root-Verzeichnis (Standard: workflows)

SSH-Konfiguration¶

• --ssh-private-key <file> - SSH-Private-Key (Standard: id_rsa)
• --ssh-public-key <file> - SSH-Public-Key (Standard: id_rsa.pub)
• --ssh-use-passphrase - Aktiviert SSH-Key-Passphrase-Support ⚠️ Experimental

Registry-Konfiguration¶

• --registry-url <url> - URL der OCI-Registry (Standard: cargo.ayedo.cloud)
• --registry-base-image <image> - Base-Image für Block-Packaging (Standard: cargo.ayedo.cloud/library/scratch:latest)

PolyHub-Konfiguration¶

• --hub-url <url> - URL des PolyHub (Standard: https://hub.polycrate.io)
• --hub-username <username> - PolyHub-Benutzername
• --hub-password <password> - PolyHub-Passwort
• --hub-api-key <key> - PolyHub-API-Key

Entwicklung und Debugging¶

• --dev - Entwicklungsmodus für Blocks
• --loglevel <level> - Log-Level (Standard: 1)
• --logformat <format> - Log-Format (json/yaml/default)
• --merge-debug - Merge-Debugging aktivieren
• --merge-v2 - Merge v2 verwenden
• --validate-block-config - Block-Konfiguration validieren

Weitere Flags¶

• -o, --output-format <format> - Output-Format (Standard: yaml)
• --auto-commit - Automatisches Commit des Workspace vor/nach Action-Ausführung
• --check-updates - Prüft beim Start auf Updates
• --config-dir <path> - Pfad zum Config-Verzeichnis (Standard: ~/.polycrate)
• --config-file <path> - Pfad zur Config-Datei (Standard: ~/.polycrate/polycrate.yml)
• --editor <editor> - Editor zum Öffnen des Workspace (Standard: code)
• --kubeconfig <path> - Pfad zur globalen Kubeconfig (Standard: ~/.kube/config)
• --remote-root <path> - Remote-Root für Remote-Hosts (Standard: /polycrate)
• --runtime-dir <path> - Basis für temporäre Laufzeit-Dateien (Standard: ~/.polycrate/run) — siehe Runtime-Verzeichnis

Runtime-Verzeichnis¶

Das Flag --runtime-dir setzt die Basis für alle pro Transaktion angelegten temporären Dateien (Ausführungs-Skripte, Workspace-Snapshots, OCI-Zwischenstände, Analyse-Skripte usw.). Der Standard ist ~/.polycrate/run, also run unterhalb des mit --config-dir wählbaren Konfigurationsverzeichnisses (siehe Konfiguration).

Struktur: Pro CLI-Ausführung nutzt Polycrate eine Transaktions-ID (TXID). Temporäre Dateien liegen unter <runtime-dir>/<TXID>/. Dieses Verzeichnis wird nicht beim Start jeder Transaktion angelegt, sondern lazy, sobald das erste Artefakt geschrieben wird. Commands, die ausschließlich im Workspace lesen oder schreiben (z. B. polycrate spec list ohne Container-Artefakte), erzeugen dadurch kein leeres run/<TXID>/.

Aufräumen: Nach Ende der Transaktion wird <runtime-dir>/<TXID>/ wieder entfernt, sodass keine verwaisten Ordner zurückbleiben.

Sandboxes, CI und Agent-Umgebungen: Ist ~/.polycrate nicht beschreibbar, setzen Sie einen expliziten, beschreibbaren Pfad — oft zusammen mit --config-dir:

polycrate spec list --config-dir /tmp/polycrate-config --runtime-dir /tmp/polycrate-run -w /pfad/zum/workspace

Tools¶

Die polycrate tools-Sammlung bietet nützliche Hilfswerkzeuge für Entwicklung und Operations.

polycrate tools¶

Zeigt einen interaktiven Selector zur Auswahl eines Tools an.

polycrate tools

Verfügbare Tools¶

Beispiele¶

# Passwort generieren
polycrate tools pwgen
polycrate tools pwgen 32 -s           # 32 Zeichen mit Sonderzeichen

# age-Keypair für Workspace-Verschlüsselung (ohne externe age-CLI)
polycrate tools pwgen -a age

# Auf Datenbank warten
polycrate tools wait tcp://db:5432 -t 60

# Zertifikat prüfen
polycrate tools cert google.com
polycrate tools cert cert.pem -k key.pem

# DNS-Lookup
polycrate tools dns -t MX gmail.com

# YAML/JSON vergleichen
polycrate tools diff old.yaml new.yaml

# Checksum verifizieren
polycrate tools hash -v "abc123..." downloaded.tar.gz

Für detaillierte Hilfe zu jedem Tool:

polycrate tools <tool> --help

polycrate tools pwgen¶

Generiert sichere Passwörter (konfigurierbarer Zeichensatz), Hashes (z. B. bcrypt, SHA256) oder ein age-X25519-Keypair.

polycrate tools pwgen -a age

Die Zeile AGE-SECRET-KEY-... setzen Sie als WORKSPACE_ENCRYPTION_KEY, wenn Sie die Polycrate API nicht nutzen. Siehe Workspace-Verschlüsselung — Encryption Key ohne Polycrate API.

polycrate spec — Spec-Driven Development¶

Commands für das Spec-Lifecycle-Management. Specs dokumentieren Probleme, Analysen und Lösungen strukturiert in .specs/ und bilden die Grundlage für reproduzierbare Releases.

Subcommands¶

Status-Lifecycle¶

planned → in-progress → ready → implemented
   └──────────────────────────────────────→ cancelled (jederzeit)

Spec-Typen¶

Beispiele¶

# SDD initialisieren
polycrate spec init

# Neue Spec anlegen (mit Typ-Scaffolding)
polycrate spec create --name "Login Timeout Fix" --type fix
polycrate spec create --name "Dark Mode" --type feat

# Quick-Capture während Implementierung
polycrate spec note "S3 upload schlägt silent fehl bei 403" --type fix --label s3

# Spec ausarbeiten
polycrate spec update 0 --set status=in-progress
polycrate spec update 0 --section problem="Nach 30 Minuten Inaktivität..."
polycrate spec update 0 --section-file solution=/tmp/solution.md   # aus Datei
polycrate spec update 0 --section-stdin solution                   # aus Stdin

# Labels und Abhängigkeiten
polycrate spec update 0 --add-label auth --add-label backend
polycrate spec link 0 --needs 3          # Alias: --add-needs 3
polycrate spec list --label auth --blocked

# Finalisieren und implementieren
polycrate spec finalize 0
polycrate spec update 0 --set status=implemented

# Abbrechen mit Begründung
polycrate spec update 0 --set status=cancelled --set cancellation_reason="Replaced by spec #5"

# Manual für AI-Agents lesen
polycrate spec manual --no-pager

polycrate release — Release-Management¶

Commands für das Release-Lifecycle-Management. Konsumiert implementierte Specs und produziert Release-Artefakte (CHANGELOG, Versionsdatei, Git-Tag).

Subcommands¶

Release-Finalize Guards¶

Vor release finalize werden automatisch geprüft:

Beispiele¶

# Kandidaten prüfen
polycrate release diff 1.0.0

# Release erstellen
polycrate release create 1.0.0 --spec 0 --spec 1

# Changelog schreiben
polycrate release update 1.0.0 \
  --set type=feat \
  --set message="Login Timeout Fix + neue API-Integration" \
  --changelog-item "FIX: Session-Timeout auf 8h erhöht" \
  --changelog-item "FEAT: Neue Endpoint-Validierung" \
  --set docs_url="https://docs.ayedo.de/polycrate/releases/cli/1.0.0/"

# Status und Warnings prüfen
polycrate release status 1.0.0

# Release abschließen (Guards → Version setzen → Git-Tag)
polycrate release finalize 1.0.0

# Danach workspace synchronisieren
polycrate workspace sync

Siehe auch¶

• Erste Schritte
• Workspaces
• Blocks
• Actions
• Workflows
• Registry