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 init¶

Initialisiert einen neuen Workspace.

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

Hinweis: Der Befehl muss im Zielverzeichnis ausgeführt werden. Alternativ kann der Pfad mit --workspace <pfad> übergeben werden.

polycrate workspace¶

Verwaltet den Workspace.

polycrate workspace init¶

Initialisiert einen neuen Workspace (siehe Beispiel oben für das erforderliche Vorgehen im Zielordner).

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

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 block pull¶

Lädt einen Block aus der Registry herunter.

polycrate block pull <block-name>[:<version>]

Parameter: - block-name - Name des Blocks (kann Registry-URL enthalten) - version (optional) - Version des Blocks (Standard: latest)

Optionen: - --version <version> - Spezifische Version

Beispiele:

# Block vom Standard-Registry pullen
polycrate block pull ayedo/k8s/cluster

# Spezifische Version pullen
polycrate block pull ayedo/k8s/cluster:1.2.0

# Von custom Registry pullen
polycrate block pull index.docker.io/my-org/my-block

polycrate block push¶

Lädt einen Block in die Registry hoch.

polycrate block push <block-name>

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

Hinweis: Beim Pushen eines Blocks wird die Version aus der block.poly automatisch als Tag verwendet. Geben Sie kein Tag im Block-Namen an.

Beispiele:

# Block zum Standard-Registry pushen
polycrate block push ayedo/k8s/cluster

# Zu custom Registry pushen
polycrate block push my.registry.com/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

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 - -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 - --snapshot - Zeigt nur den Workspace-Snapshot an, führt nichts aus

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 zusätzlichen Umgebungsvariablen
polycrate run my-block deploy -e ENV=prod -e REGION=eu-west-1

# 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 inspect¶

Zeigt Informationen über einen Block im PolyHub an.

polycrate hub inspect <block-name>

Beispiel:

polycrate hub inspect ayedo/k8s/cluster

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)

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

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:

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 und Logs¶

• --artifacts-root <path> - Artefakte-Root-Verzeichnis (Standard: artifacts)
• --logs-root <path> - Logs-Root-Verzeichnis (Standard: .logs). Nur relevant wenn Transaction-Logging aktiviert oder Event-Handler konfiguriert ist.
• --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> - Pfad zum Runtime-Verzeichnis (Standard: ~/.polycrate/run)

Event-Konfiguration¶

• --event-commit - Auto-Commit für jedes Event
• --event-endpoint <url> - Standard-Event-Endpoint
• --event-handler <handler> - Standard-Event-Handler

Siehe auch¶

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