CLI Reference

Reference of all Polycrate CLI commands with options and parameters: workspace and block management, run, Git aliases, Kubernetes, observability, spec-driven development, operator, hub, and tools.

This page documents every available Polycrate CLI command with its options and parameters.

Basic commands

polycrate version

Shows the current Polycrate version.

polycrate version

polycrate help

Shows help for Polycrate commands.

polycrate help [command]

polycrate update

Updates Polycrate to the latest version.

polycrate update [version]

Parameters:

• version (optional) - Specific version to update to

Example:

polycrate update
polycrate update 0.51.3

Workspace management

polycrate workspace

Manages the workspace.

polycrate workspace create

Creates a new workspace via the Polycrate API — including a GitLab repository, encryption credential, and local clone.

polycrate workspace create ORG_NAME WORKSPACE_NAME [PATH] [flags]

Prerequisites:

• API must be configured (api.enabled: true, api.api_key)
• Organization must exist and be accessible
• PoP name must be provided (--pop)

Flags:

Examples:

# Default: clone into ~/.polycrate/workspaces/acme/production
polycrate workspace create acme production --pop fra1

# With SSH key generation
polycrate workspace create acme production --pop fra1 --with-ssh-keys

# Explicit target path
polycrate workspace create acme production --pop fra1 /data/workspaces/production

Flow:

1. Resolve the organization via the API (name → UUID)
2. Resolve the PoP via the API (name → UUID)
3. Create the workspace via the API (GitLab repo + encryption credential are created automatically)
4. Poll until the repository and credential are ready
5. Clone the repository over SSH (no system git required)
6. Initialize the local workspace.poly

polycrate workspace clone

Clones an existing workspace via the Polycrate API. The CLI resolves ORG/WORKSPACE, reads git_ssh_url, and clones the repository with go-git (no system git required).

polycrate workspace clone ORG/WORKSPACE [PATH]

Prerequisites:

• API must be configured (api.enabled: true, api.api_key) — see API Integration
• The user must have access to the workspace (API permissions)
• git_ssh_url must be set on the workspace
• SSH key for the Git remote (e.g. ~/.ssh/id_ed25519)

Path semantics:

If the target directory already exists, the command aborts (no pull, no overwrite).

This differs from workspace create: there an optional PATH is the exact target directory.

Examples:

# Default: clone into ~/.polycrate/workspaces/acme/acme-production-1
polycrate workspace clone acme/acme-production-1

# Parent = current directory → ./acme-production-1
cd ~/.polycrate/workspaces/acme
polycrate workspace clone acme/acme-production-1 .

# Parent = /tmp → /tmp/acme-production-1
polycrate workspace clone acme/acme-production-1 /tmp

Flow:

1. Validate the ORG/WORKSPACE reference as slugs
2. Look up the workspace via the API (without permission: not found or not accessible)
3. Read git_ssh_url — empty/NULL is an error
4. Clone the repository over SSH (go-git)
5. No workspace init afterwards — the repo already contains workspace.poly

polycrate workspace init / polycrate init

Initializes a new workspace.

mkdir -p $HOME/.polycrate/workspaces/acme/acme-demo-1
cd $HOME/.polycrate/workspaces/acme/acme-demo-1
polycrate workspace init --with-name acme-demo-1 --with-organization acme

# Short form (alias)
polycrate init --with-name acme-demo-1 --with-organization acme

Note: Run it in the target directory or set an absolute path with -w / --workspace. polycrate init is an alias for polycrate workspace init. Path convention: Best practices.

polycrate workspace inspect

Shows detailed information about the workspace.

polycrate workspace inspect

polycrate workspace snapshot

Shows the current workspace snapshot.

polycrate workspace snapshot

Usage:

# Print the snapshot as YAML
polycrate workspace snapshot

# Save the snapshot to a file
polycrate workspace snapshot > snapshot.yml

polycrate workspace encrypt

Encrypts all sensitive workspace files (secrets.poly and all files in artifacts/secrets/) with age encryption.

polycrate workspace encrypt

Key sources (in priority order):

1. Polycrate API (automatic when api.enabled: true)
2. WORKSPACE_ENCRYPTION_KEY environment variable
3. Interactive prompt

Single-file mode (--file, from CLI 0.49.0): encrypts a file without a full workspace tree. Ciphertext goes to --output / -o or stdout.

# With API (automatic)
polycrate workspace encrypt

# With environment variable
export WORKSPACE_ENCRYPTION_KEY="AGE-SECRET-KEY-..."
polycrate workspace encrypt

# Single file
polycrate workspace encrypt --file ./payload.yml -o ./payload.yml.age

polycrate workspace decrypt

Decrypts all encrypted workspace files (all .age files in secrets.poly.age and artifacts/secrets/**/*.age).

polycrate workspace decrypt

Single-file mode (--file, from CLI 0.49.0): decrypts an .age file; plaintext goes to --output / -o or stdout.

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

polycrate workspace decrypt --file ./payload.yml.age -o ./payload.yml

polycrate workspace status

Shows the comprehensive encryption status of the workspace, including key availability, file status, Git status, and recommendations.

polycrate workspace status

Shows:

• Key status and source (API, ENV, or unavailable)
• Encrypted and unencrypted files
• .gitignore protection status
• Git repository information (branch, commit, remote status)
• Security recommendations

Example:

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

polycrate workspace update

Updates workspace dependencies.

polycrate workspace update

polycrate workspace list

Lists workspaces from the Polycrate API (default) or from the local workspace directory.

# API workspaces (default, or fall back to local when there is no API)
polycrate workspace list

# Explicitly local workspaces
polycrate workspace list --local

# With pre-filter
polycrate workspace list --filter production

# Table output without TUI
polycrate workspace list --no-pager

# Detailed table output (local)
polycrate workspace list --local --no-pager -v

Options:

Mode decision:

• --local=true → Local workspaces from ~/.polycrate/workspaces/
• --local=false (default):
  • API configured → workspaces from the Polycrate API
  • API not configured → automatic fallback to local

TUI navigation:

Action menu (remote/API):

• open – Open the workspace in the Polycrate UI (browser)
• gitlab – Open the GitLab repository in the browser
• clone – Clone the repository locally (same as polycrate workspace clone)

Action menu (local):

• open – Show workspace details and path
• status – Fetch workspace status
• git-sync – Synchronize Git changes

polycrate workspace changelog

Shows the workspace changelog in an interactive TUI.

# Interactive TUI
polycrate workspace changelog

# Show changelog format (for LLMs)
polycrate workspace changelog --spec

# Without TUI
polycrate workspace changelog --no-tui

Options:

The changelog is read from CHANGELOG.poly in the workspace root.

Workspace Git aliases

These commands are aliases for the corresponding polycrate git * commands and provide a more intuitive UX where all workspace-related operations are available under polycrate workspace.

polycrate workspace pull

Pulls changes from the remote repository. Alias for polycrate git pull.

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

polycrate workspace push

Pushes commits to the remote repository. Alias for polycrate git push.

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

polycrate workspace sync

Automatic sync workflow: Stage → Commit → Pull → Push. Alias for polycrate git sync.

polycrate workspace sync

Flow:

1. Checks for uncommitted changes → auto-commit
2. Fetch from remote
3. Pull if there are remote changes
4. Push local commits

polycrate workspace add

Stages files for the next commit. Alias for polycrate git add.

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

polycrate workspace commit

Creates a commit. Alias for polycrate git commit.

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

Without the -m flag, you are prompted interactively for the commit message.

Block management

polycrate block

Manages blocks in the workspace.

polycrate block list

Lists all blocks in the workspace.

polycrate block list

Example:

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

polycrate block init

Initializes a new block of a specific type.

polycrate block init <block-name> [options]

Options:

• --kind <kind> - Kind of the block (e.g. ansible, script)

Example:

polycrate block init my-block --kind ansible

polycrate block inspect

Shows detailed information about a block.

polycrate block inspect <block-name>

Example:

polycrate block inspect ayedo/k8s/cluster

polycrate blocks pull / polycrate pull

Downloads a block from the registry.

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

Parameters:

• registry/path/block-name - Full registry path to the block (required)
• version - Block version (required, or latest)

Options:

• --workspace <path> - Workspace path for the block installation (default: current directory)

Examples:

# Pull from cargo.ayedo.cloud
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.2.0

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

# Pull from your own registry
polycrate blocks pull registry.my-org.com/infra/postgres:1.0.0

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

polycrate blocks push

Uploads a block as an OCI image to the registry. From CLI 0.51.0, template metadata is then optionally published to the Polycrate API (when API credentials are set and api.submit_template_blocks is not disabled).

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

Parameters:

• block-name - full registry path (no short name)

Options:

• --exclude <pattern> - Glob patterns to exclude from the OCI image (repeatable, e.g. --exclude .specs --exclude "*.log")
• -w, --workspace <path> - Workspace path; if set, an absolute path (Docker Native bind mounts)

Notes:

• The tag comes from block.poly version — no tag in the push argument.
• .specs/ is excluded by default.
• API publish (template blocks): on success after the OCI push. From 0.51.3 the API field display_name is the registry URL (not the human-readable title from block.poly). Hub presentation stays separate.
• Disable: api.submit_template_blocks: false or the flag --api-submit-template-blocks=false.

→ Registry – Exclude patterns · CLI 0.51.0 · CLI 0.51.3

Examples:

polycrate blocks push cargo.ayedo.cloud/ayedo/k8s/cluster

polycrate blocks push my.registry.com/my-org/my-block

polycrate blocks push cargo.ayedo.cloud/my-org/my-block --exclude .git --exclude "*.log"

# Short form
polycrate push cargo.ayedo.cloud/my-org/my-block

# Explicit workspace (absolute path)
polycrate blocks push cargo.ayedo.cloud/my-org/my-block \
  -w /home/you/.polycrate/workspaces/acme/prod

polycrate block readme

Shows the README file of a block.

polycrate block readme <block-name>

Example:

polycrate block readme ayedo/k8s/cluster

polycrate block validate

Validates the configuration of a block.

polycrate block validate <block-name>

Example:

polycrate block validate ayedo/k8s/cluster

polycrate block changelog

Shows the changelog of a block in an interactive TUI.

# Interactive TUI
polycrate block changelog <block-name>

# Show changelog format
polycrate block changelog <block-name> --spec

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

Options:

Example:

polycrate block changelog postgres-base

The changelog is read from CHANGELOG.poly in the block directory.

Action management

polycrate run

Runs an action or a workflow.

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

Options:

• -f, --force - Confirms all prompts automatically
• -K, --ask-become-pass - Prompts interactively for the Ansible become/sudo password
• -l, --local - Runs the action locally (without a container)
• -i, --interactive - Makes the container interactive
• -b, --build - Builds a custom image from the workspace Dockerfile.poly (default: true)
• -p, --pull - Pulls the workspace image before execution (default: true)
• -e, --env <KEY=value> - Additional environment variables
• -m, --mount <host:container> - Additional mounts for the container
• --set <key=value> - Override of action.config (Helm-style, repeatable, e.g. --set database.host=prod.local)
• --snapshot - Shows only the workspace snapshot, does not execute anything

→ Full --set documentation: Actions – Runtime Config Overrides

Examples:

# Run an action
polycrate run my-block install

# With force flag (no prompts)
polycrate run my-block install --force

# Run locally (without container)
polycrate run my-block install --local

# With Ansible become/sudo password (for playbooks with become: yes)
polycrate run my-block install --ask-become-pass

# With additional environment variables
polycrate run my-block install -e ENV=prod -e REGION=eu-west-1

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

# Show snapshot only
polycrate run my-block install --snapshot

polycrate action

Manages actions.

polycrate action list

Lists all available actions in the workspace.

polycrate action list

polycrate action inspect

Shows detailed information about an action.

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

Example:

polycrate action inspect my-block install

polycrate action run

Runs an action (identical to polycrate run).

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

Workflow management

polycrate workflow

Manages workflows.

polycrate workflow list

Lists all available workflows in the workspace.

polycrate workflow list

polycrate workflow inspect

Shows detailed information about a workflow.

polycrate workflow inspect <workflow-name>

Example:

polycrate workflow inspect deploy-all

polycrate workflow run

Runs a workflow.

polycrate workflow run <workflow-name> [options]

Options: Identical to polycrate run

Example:

polycrate workflow run deploy-all --force

PolyHub integration

polycrate hub

Interacts with the Polycrate Hub.

polycrate hub list

Lists all blocks in the hub with an interactive TUI.

# Interactive TUI (default)
polycrate hub list

# With filter
polycrate hub list --filter postgres

# Filter by kind
polycrate hub list --kind k8sapp

# Table output without TUI
polycrate hub list --no-tui

Options:

TUI navigation:

Action menu after selection:

• view-versions – Show all versions
• view-block – Show block.poly
• view-readme – Show README
• copy-name – Block name to copy

polycrate hub inspect

Shows information about a block in PolyHub.

polycrate hub inspect <block-name>

Options:

Examples:

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

API integration

polycrate api

Shows API information.

polycrate api

Options:

• --api-enabled - Enables API integration
• --api-url <url> - API URL (default: https://hub.polycrate.io)
• --api-api-key <key> - API key for authentication
• --api-submit-action-runs - Sends action results to the API (default: true)

Observability

From CLI 0.46.0 — logs and metrics directly from the terminal via the Polycrate API (VictoriaLogs / VictoriaMetrics).

→ Full guide: Observability — Logs & Metrics

polycrate logs

Queries platform logs for organization and workspace (optional block scope).

polycrate logs
polycrate logs --query '_msg:error' --start 1h
polycrate logs --block my-app --follow
polycrate logs list   # Alias

polycrate metrics

PromQL/MetricsQL against VictoriaMetrics — instant or range query.

polycrate metrics 'up'
polycrate metrics 'rate(http_requests_total[5m])' --block nginx
polycrate metrics 'up' --start -1h --end now --step 1m --format json

Container debugging

polycrate debug

Starts an interactive debug shell in the Polycrate container with the same configuration as an action run.

polycrate debug [options]

Description:

The debug command starts the Polycrate container with all mounts, environment variables, and network configuration of a normal action run, but opens an interactive Bash shell instead of executing an action.

Options:

Examples:

# Start a debug container in the current workspace
polycrate debug

# With an explicit workspace path
polycrate debug -w /path/to/workspace

# With additional mounts
polycrate debug -m /local/path:/container/path

# With additional environment variables
polycrate debug -e MY_VAR=value

# With Native Docker mode
polycrate -N debug

Output:

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

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

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

Use cases:

• Playbook debugging: Run and test Ansible playbooks manually
• Environment inspection: Check which variables are set in the container
• Path validation: Verify that mounts arrive correctly
• Tool availability: Test whether required tools are present in the image
• Network debugging: Test network connections from the container

Kubernetes

polycrate k8s debug

Starts a debug pod in the Kubernetes cluster with the Polycrate image and attaches automatically.

polycrate k8s debug [options]

Description:

The k8s debug command temporarily creates:

1. A ServiceAccount polycrate-admin (if it does not exist)
2. A ClusterRoleBinding with cluster-admin rights
3. A debug pod with the Polycrate image

After you leave the shell, the pod is deleted automatically.

Options:

Prerequisites:

• Valid workspace with a kubeconfig (kubeconfig.yml or artifacts/secrets/kubeconfig.yml)
• Cluster-admin permission to create ServiceAccounts and ClusterRoleBindings

Examples:

# Start a debug pod in kube-system
polycrate k8s debug

# Debug pod in another namespace
polycrate k8s debug -n default

# With an explicit workspace
polycrate k8s debug -w /path/to/workspace

Flow:

$ 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...

# Now in the interactive shell in the 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: Direct access to the cluster with all Polycrate tools
• Network tests: Test service connectivity inside the cluster
• Helm/Kubectl: Run Helm or kubectl commands in the cluster context
• Log analysis: Access logs and resources without a local kubeconfig

Git integration

Native Git integration without an external Git installation (based on go-git).

polycrate git status

Shows the Git status of the workspace repository.

polycrate git status

Color coding:

• new: (green) – New file
• modified: (yellow) – Modified file
• deleted: (red) – Deleted file
• renamed:/copied: (cyan) – Renamed/copied file

polycrate git add

Stages files for the next commit.

# Single file
polycrate git add <file>

# All changes
polycrate git add --all
polycrate git add -a

polycrate git commit

Creates a new commit.

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

polycrate git push

Pushes commits to the remote repository.

polycrate git push

polycrate git pull

Pulls changes from the remote repository. Checks for conflicts first.

polycrate git pull

polycrate git sync

Automatic sync workflow: Stage → Commit → Pull → Push.

polycrate git sync

Flow:

1. Stage all changes
2. Automatic commit
3. Pull remote changes
4. Push local commits

Operator

The Polycrate Operator enables automated multi-tenant management across Keycloak, GitLab, Harbor, ArgoCD, and Kubernetes clusters.

polycrate operator crds

Prints CRD definitions for installation.

# Print all CRDs
polycrate operator crds

# Print a specific CRD type
polycrate operator crds --kind Organization

# Save CRDs to files
polycrate operator crds --output-dir ./crds/

# List CRD names only
polycrate operator crds --list

Options:

polycrate operator install-crds

Installs all operator CRDs directly into the Kubernetes cluster.

# With the default kubeconfig
polycrate operator install-crds

# With a specific kubeconfig
polycrate operator install-crds --kubeconfig ~/.kube/admin.yaml

# Dry-run (shows what would be installed)
polycrate operator install-crds --dry-run

Options:

Output:

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

Starts the Polycrate Operator.

# Locally with kubeconfig
polycrate operator run --kubeconfig ~/.kube/config

# With leader election (for HA deployments)
polycrate operator run --leader-elect

# With metrics enabled
polycrate operator run --metrics-bind-address :8080

Options:

Endpoints:

polycrate operator health

Checks the health status of a running operator.

# Check the local operator (default: localhost:8081)
polycrate operator health

# Check a remote operator
polycrate operator health --url http://polycrate-operator.polycrate:8081

Options:

Output:

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

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

Status: HEALTHY

polycrate operator status

Shows the status of all operator custom resources in the cluster.

# Show status of all resources
polycrate operator status

# With a specific kubeconfig
polycrate operator status --kubeconfig ~/.kube/config

Options:

Output:

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

Other commands

polycrate checksum

Computes the MD5 checksum of a directory.

polycrate checksum <directory>

Example:

polycrate checksum ./blocks/my-block

polycrate completion

Generates autocompletion scripts for various shells. Polycrate supports dynamic completion, i.e. context-dependent suggestions such as available SSH hosts.

polycrate completion <shell>

Supported shells:

• bash
• zsh
• fish
• powershell

Setup:

=== "Zsh"

```bash
# Enable once
source <(polycrate completion zsh)

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

=== "Bash"

```bash
# Enable once
source <(polycrate completion bash)

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

# Or system-wide
polycrate completion bash > /etc/bash_completion.d/polycrate
```

=== "Fish"

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

=== "PowerShell"

```powershell
polycrate completion powershell | Out-String | Invoke-Expression

# Permanent (in profile)
polycrate completion powershell >> $PROFILE
```

Features:

• Command completion: All Polycrate commands and flags
• SSH host completion: polycrate ssh <TAB> shows available hosts from the inventory
• Block completion: Block names are suggested

Example:

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

Global flags

These flags can be used with every command:

Docker & container

• -N, --docker-native - Use the native Docker SDK instead of the Docker CLI (experimental)
• --no-pager - Disables the interactive TUI pager for output
• --non-interactive - Forces non-interactive mode (skips all prompts)

Workspace configuration

• -w, --workspace <path> - Path to the workspace (default: current directory). If set: absolute path — relative values such as . fail with Docker Native bind mounts (from CLI 0.51.0). Without the flag, CWD applies.
• --workspace-config <file> - Name of the workspace config file (default: workspace.poly)
• --workspace-dir <path> - Path to the workspaces directory (default: ~/.polycrate/workspaces)

Block configuration

• --blocks-root <path> - Blocks root directory (default: blocks)
• --blocks-config <file> - Name of the block config file (default: block.poly)
• --blocks-auto-pull - Automatically pull missing blocks (default: false)

Container configuration

• --image-ref <ref> - Workspace image reference (default: cargo.ayedo.cloud/library/polycrate)
• --image-version <version> - Workspace image version (default: latest)
• --dockerfile <file> - Workspace Dockerfile (default: Dockerfile.poly)
• --container-root <path> - Container root directory (default: /workspace)

Artifacts

• --artifacts-root <path> - Artifacts root directory (default: artifacts)
• --workflows-root <path> - Workflows root directory (default: workflows)

SSH configuration

• --ssh-private-key <file> - SSH private key (default: id_rsa)
• --ssh-public-key <file> - SSH public key (default: id_rsa.pub)
• --ssh-use-passphrase - Enables SSH key passphrase support Experimental

Registry configuration

• --registry-url <url> - URL of the OCI registry (default: cargo.ayedo.cloud)
• --registry-base-image <image> - Base image for block packaging (default: cargo.ayedo.cloud/library/scratch:latest)

PolyHub configuration

• --hub-url <url> - URL of PolyHub (default: https://hub.polycrate.io)
• --hub-username <username> - PolyHub username
• --hub-password <password> - PolyHub password
• --hub-api-key <key> - PolyHub API key

Development and debugging

• --loglevel <level> - Log level (default: 1)
• --logformat <format> - Log format (json/yaml/default)
• --merge-debug - Enable merge debugging
• --merge-v2 - Use merge v2
• --validate-block-config - Validate block configuration

Other flags

• -o, --output-format <format> - Output format (default: yaml)
• --auto-commit - Automatic commit of the workspace before/after action execution
• --check-updates - Checks for updates on start
• --check-block-updates - Checks for newer block versions after action runs
• --check-workspace-behind-remote - Warns when the workspace Git state is behind remote
• --check-maintenance-window - Checks the maintenance window before the run
• --sync-loopback-kubeconfig - Align the workspace-local kubeconfig with the API before the run (historical name; default: true). General sync: polycrate k8s sync-kubeconfigs
• --config-dir <path> - Path to the config directory (default: ~/.polycrate)
• --config-file <path> - Path to the config file (default: ~/.polycrate/polycrate.yml)
• --editor <editor> - Editor to open the workspace (default: code)
• --kubeconfig <path> - Path to the global kubeconfig (default: ~/.kube/config)
• --remote-root <path> - Remote root for remote hosts (default: /polycrate)
• --runtime-dir <path> - Base for temporary runtime files (default: ~/.polycrate/run) — see Runtime directory

Runtime directory

The --runtime-dir flag sets the base for all temporary files created per transaction (execution scripts, workspace snapshots, OCI intermediates, analysis scripts, etc.). The default is ~/.polycrate/run, i.e. run under the configuration directory selectable with --config-dir (see Configuration).

Structure: Each CLI invocation uses a transaction ID (TXID). Temporary files live under <runtime-dir>/<TXID>/. This directory is not created at the start of every transaction, but lazily, as soon as the first artifact is written. Commands that only read or write in the workspace (e.g. polycrate spec list without container artifacts) therefore create no empty run/<TXID>/.

Cleanup: After the transaction ends, <runtime-dir>/<TXID>/ is removed so that no orphaned folders remain.

Sandboxes, CI, and agent environments: If ~/.polycrate is not writable, set an explicit, writable path — often together with --config-dir:

polycrate spec list --config-dir /tmp/polycrate-config --runtime-dir /tmp/polycrate-run -w /path/to/workspace

Tools

The polycrate tools collection provides useful helpers for development and operations.

polycrate tools

Shows an interactive selector to pick a tool.

polycrate tools

Available tools

Examples

# Generate a password
polycrate tools pwgen
polycrate tools pwgen 32 -s           # 32 characters with special characters

# age keypair for workspace encryption (without an external age CLI)
polycrate tools pwgen -a age

# Wait for a database
polycrate tools wait tcp://db:5432 -t 60

# Inspect a certificate
polycrate tools cert google.com
polycrate tools cert cert.pem -k key.pem

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

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

# Verify a checksum
polycrate tools hash -v "abc123..." downloaded.tar.gz

For detailed help on each tool:

polycrate tools <tool> --help

polycrate tools pwgen

Generates secure passwords (configurable character set), hashes (e.g. bcrypt, SHA256), or an age X25519 keypair.

polycrate tools pwgen -a age

Set the AGE-SECRET-KEY-... line as WORKSPACE_ENCRYPTION_KEY when you are not using the Polycrate API. See Workspace Encryption — Encryption key without Polycrate API.

polycrate validate

Syntactic YAML validation without workspace load, block resolution, or network (from CLI 0.44.1). Input via file path or STDIN; --format json for machine-readable output.

polycrate validate workspace-poly ./workspace.poly
cat secrets.poly | polycrate validate secrets-poly
polycrate validate workspace-poly --format json ./workspace.poly

polycrate spec — Spec-Driven Development

Commands for spec lifecycle management. Specs live under .specs/ and are scanned live (no index.yml, from CLI 0.45.0).

The file .specs/ARCHITECTURE.md is not a spec and may be edited directly. Frontmatter and release files only via polycrate spec * / polycrate release *. Details: Spec-Driven Development.

Subcommands

Status lifecycle (from CLI 0.45.0)

draft ↔ done
any   → cancelled

Older status names are mapped on read (approved/implemented/… → draft/done).

Section schema

Section bodies may be edited directly; frontmatter only via the CLI. In bodies only H3+.

Examples

polycrate spec init
polycrate spec create --name "Login Timeout Fix" --type fix
polycrate spec note "S3 upload fails silently on 403" --type fix --label s3

polycrate spec update 0 --section context="..."
polycrate spec update 0 --section-file solution=/tmp/.polycrate/spec-sections/spec-0-solution.md
polycrate spec lint 0
polycrate spec update 0 --set status=done

polycrate spec list --open --format tsv
polycrate release list --format tsv --sort version:desc
polycrate spec manual --no-pager

polycrate release — Release management

Release lifecycle: optionally assign specs, write changelog/release notes, set the version, Git tag.

Subcommands

Release finalize guards

Examples

polycrate release diff 1.0.0
polycrate release create 1.0.0 --spec 0 --spec 1
# or without specs / by filter:
polycrate release create 1.0.1 --spec-status done

polycrate release update 1.0.0 \
  --set type=feat \
  --set message="Login timeout fix + new API integration" \
  --changelog-item "FIX: session timeout increased to 8h" \
  --set docs_url="https://docs.ayedo.de/polycrate/releases/cli/1.0.0/" \
  --note-section highlights="Session timeout fix, new API integration"

polycrate release status 1.0.0
polycrate release finalize 1.0.0
polycrate workspace sync

See also

• Getting started
• Observability — Logs & Metrics
• Workspaces
• Blocks
• Actions
• Workflows
• Registry