Version v1.5 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

CLI Reference

Command-line reference for porchctl

Overview

porchctl is the command-line interface for interacting with Porch. It communicates with a Kubernetes API server that has Porch installed as an aggregated API server, allowing you to manage repository registrations and packages within those repositories.

Installation

See Installing porchctl for installation instructions.

Global Flags

These flags are available for all porchctl commands:

Flag	Description	Default
`--kubeconfig string`	Path to kubeconfig file. Only required if out-of-cluster. Can also be set via `KUBECONFIG` environment variable.
`--log-flush-frequency duration`	Maximum seconds between log flushes	`5s`
`--truncate-output`	Enable output truncation	`true`
`-v, --v Level`	Log level verbosity
`-h, --help`	Help for porchctl

Commands

repo - Manage package repositories
rpkg - Manage packages
completion - Generate shell autocompletion
version - Print version information

repo

Manage package repositories.

Aliases: repo, repository

Subcommands

repo reg - Register a package repository
repo get - List registered repositories
repo sync - Schedule one-time repository sync
repo unreg - Unregister a repository

Common Flags

These flags are available for all repo subcommands:

Flag	Description
`--as-uid string`	UID to impersonate for the operation
`--cluster string`	Name of the kubeconfig cluster to use
`--context string`	Name of the kubeconfig context to use
`--disable-compression`	Opt-out of response compression
`-n, --namespace string`	Namespace scope for this request
`-s, --server string`	Address and port of Kubernetes API server
`--tls-server-name string`	Server name for certificate validation
`--user string`	Name of the kubeconfig user to use

repo reg

Aliases: reg, register

Usage:

porchctl repo reg REPOSITORY [flags]

Arguments:

REPOSITORY - URI for the repository. Can be a Git repository URL.

Flags:

Flag	Description	Default
`--name string`	Repository name. If unspecified, uses last segment of URL
`--description string`	Brief description of the repository
`--branch string`	Git branch where finalized packages are committed	`main`
`--create-branch`	Create the package branch if it doesn’t exist	`false`
`--directory string`	Directory within repository containing packages	`/`
`--deployment`	Mark as deployment repository (packages are deployment-ready)	`false`
`--sync-schedule string`	Cron expression for periodic sync (e.g., `/10 * * *`)
`--repo-basic-username string`	Username for basic authentication
`--repo-basic-password string`	Password/token for basic authentication
`--repo-workload-identity`	Use workload identity for authentication	`false`

Examples:

# Register a Git repository with auto-generated name
porchctl repo register https://github.com/platkrm/demo-blueprints.git --namespace=default

# Register a deployment repository with custom name
porchctl repo register https://github.com/platkrm/blueprints-deployment.git \
  --name=foo --deployment --namespace=bar

# Register with sync schedule (every 10 minutes)
porchctl repo register https://github.com/platkrm/blueprints-deployment.git \
  --name=foo --deployment --namespace=bar --sync-schedule="*/10 * * * *"

repo get

List registered repositories.

Aliases: get, ls, list

Usage:

porchctl repo get [REPOSITORY_NAME] [flags]

Arguments:

REPOSITORY_NAME - (Optional) Name of specific repository to show. If omitted, shows all repositories.

Flags:

Flag	Description
`-A, --all-namespaces`	List repositories across all namespaces
`--allow-missing-template-keys`	Ignore template errors for missing fields
`-L, --label-columns strings`	Labels to display as columns
`--no-headers`	Don’t print headers in output
`-o, --output string`	Output format: json, yaml, wide, custom-columns, etc.
`--show-kind`	Show resource type
`--show-labels`	Show all labels
`--show-managed-fields`	Keep managedFields in JSON/YAML output
`--sort-by string`	Sort by field (JSONPath expression)
`--template string`	Template for go-template output

Examples:

# List all repositories in default namespace
porchctl repo get --namespace default

# Show specific repository
porchctl repo get foo --namespace bar

# List repositories across all namespaces
porchctl repo get -A

repo sync

Schedule a one-time sync for registered repositories.

Aliases: sync, reconcile

Usage:

porchctl repo sync [REPOSITORY_NAME] [flags]

Arguments:

REPOSITORY_NAME - (Optional) Name(s) of repositories to sync. Use --all to sync all repositories.

Flags:

Flag	Description
`--all`	Sync all repositories in the namespace
`-A, --all-namespaces`	List repositories across all namespaces
`--run-once string`	Schedule sync using duration (e.g., `10m`, `2h30m`) or RFC3339 timestamp. Minimum: 1 minute
`-o, --output string`	Output format

Examples:

# Sync all repositories after 1 minute (default)
porchctl repo sync --all --namespace default

# Sync specific repository after 1 minute
porchctl repo sync foo --namespace default

# Sync after 10 minutes
porchctl repo sync foo --namespace bar --run-once=10m

# Sync at specific time
porchctl repo sync foo1 foo2 --namespace bar --run-once=2025-09-16T14:00:00Z

repo unreg

Unregister a repository.

Aliases: unreg, unregister

Usage:

porchctl repo unreg REPOSITORY [flags]

Arguments:

REPOSITORY - Name of the repository to unregister.

Flags:

Flag	Description	Default
`--keep-auth-secret`	Keep the auth secret when unregistering	`false`

Examples:

# Unregister repository and delete auth secret
porchctl repo unreg registered-repository --namespace=default

# Unregister but keep auth secret
porchctl repo unreg registered-repository --namespace=default --keep-auth-secret

rpkg

Manage packages and package revisions.

Aliases: rpkg, rpackage

Subcommands

rpkg init - Initialize new package
rpkg clone - Clone existing package
rpkg copy - Create new revision from existing package
rpkg get - List package revisions
rpkg pull - Pull package content locally
rpkg push - Push local content to package
rpkg propose - Propose package for publication
rpkg approve - Approve proposed package
rpkg reject - Reject proposed package
rpkg del - Delete package revision
rpkg propose-delete - Propose deletion of published package
rpkg upgrade - Upgrade downstream package to newer upstream

Common Flags

These flags are available for all rpkg subcommands:

Flag	Description
`--as-uid string`	UID to impersonate for the operation
`--cluster string`	Name of the kubeconfig cluster to use
`--context string`	Name of the kubeconfig context to use
`--disable-compression`	Opt-out of response compression
`--kubeconfig string`	Path to kubeconfig file
`-n, --namespace string`	Namespace scope for this request
`-s, --server string`	Address and port of Kubernetes API server
`--tls-server-name string`	Server name for certificate validation
`--user string`	Name of the kubeconfig user to use
`-v, --v Level`	Log level verbosity

rpkg init

Initialize a new package revision in a repository.

Usage:

porchctl rpkg init PACKAGE_NAME [flags]

Arguments:

PACKAGE_NAME - Name of the new package.

Flags:

Flag	Description	Default
`--repository string`	Repository where package will be created	(required)
`--workspace string`	Workspace name for the package	(required)
`--description string`	Short description of the package	`"sample description"`
`--keywords strings`	List of keywords for the package
`--site string`	Link to page with package information

Examples:

# Create new package
porchctl rpkg init example-package-name \
  --repository=example-repository \
  --workspace=example-workspace \
  --namespace=example-namespace

rpkg clone

Create a clone of an existing package revision.

Usage:

porchctl rpkg clone SOURCE_PACKAGE NAME [flags]

Arguments:

SOURCE_PACKAGE - Source package to clone. Can be:
- Git: https://git-repository.git/package-name
- Package: example-repo.example-package-name.example-workspace
NAME - Name of the new package.

Flags:

Flag	Description	Default
`--repository string`	Downstream repository for cloned package	(required)
`--workspace string`	Workspace name for new package	`v1`
`--directory string`	Directory within upstream repository (Git only)
`--ref string`	Branch, tag, or SHA in upstream repository (Git only)
`--strategy string`	Update strategy: `resource-merge`, `fast-forward`, `force-delete-replace`, `copy-merge`	`resource-merge`
`--secret-ref string`	Secret name for basic auth (Git only)

Examples:

# Clone from existing package
porchctl rpkg clone example-repo.example-package-name.example-workspace example-package-name-2 \
  --repository=example-repo-2 \
  --workspace=example-workspace-2 \
  --strategy=force-delete-replace

# Clone from Git repository
porchctl rpkg clone https://github.com/repo/blueprint.git example-downstream-package \
  --repository=blueprint \
  --ref=base/v0 \
  --namespace=default \
  --directory=base

rpkg copy

Create a new package revision from an existing one.

Aliases: copy, edit

Usage:

porchctl rpkg copy SOURCE_PACKAGE [flags]

Arguments:

SOURCE_PACKAGE - Kubernetes name of the source package revision.

Flags:

Flag	Description
`--workspace string`	Workspace name for the copy

Examples:

# Create new revision with different workspace
porchctl rpkg copy example-repo.example-package-name.example-workspace \
  --workspace=example-workspace-2 \
  --namespace=example-namespace

rpkg get

List package revisions in registered repositories.

Aliases: get, list

Usage:

porchctl rpkg get [PACKAGE] [flags]

Arguments:

PACKAGE - (Optional) Kubernetes name of specific package revision. If omitted, shows all package revisions.

Flags:

Flag	Description	Default
`--name string`	Filter by package name (substring match)
`--revision int`	Filter by revision number	`-2` (all)
`--workspace string`	Filter by workspace name
`-A, --all-namespaces`	List across all namespaces
`-o, --output string`	Output format
`--no-headers`	Don’t print headers
`--show-labels`	Show all labels

Examples:

# Get specific package revision
porchctl rpkg get example-repo.example-package-name.example-workspace --namespace=example-namespace

# Get by package name
porchctl rpkg get --name=example-package-name --namespace=example-namespace

# Get all package revisions
porchctl rpkg get --namespace=example-namespace

# Get all with revision 0 (Draft/Proposed)
porchctl rpkg get --revision=0

rpkg pull

Pull package revision content to local filesystem.

Aliases: pull, source, read

Usage:

porchctl rpkg pull PACKAGE [DIR] [flags]

Arguments:

PACKAGE - Kubernetes name of the package revision.
DIR - (Optional) Local directory for package content. If omitted, writes to stdout.

Examples:

# Pull to directory
porchctl rpkg pull example-repo.example-package-name.example-workspace \
  --namespace=example-namespace

# Pull to specific directory
porchctl rpkg pull example-repo.example-package-name.example-workspace ./my-package \
  --namespace=example-namespace

rpkg push

Push local resources to a package revision.

Aliases: push, sink, write

Usage:

porchctl rpkg push PACKAGE [DIR] [flags]

Arguments:

PACKAGE - Kubernetes name of the package revision.
DIR - Local directory with package content, or - to read from stdin.

Examples:

# Push from directory
porchctl rpkg push example-repo.example-package-name.example-workspace ./example-package-dir \
  --namespace=example-namespace

# Push from stdin
porchctl rpkg push example-repo.example-package-name.example-workspace - <stdin> \
  --namespace=example-namespace

rpkg propose

Propose that a package revision should be published.

Usage:

porchctl rpkg propose PACKAGE [...] [flags]

Arguments:

PACKAGE - Kubernetes name(s) of package revision(s). Multiple packages can be space-separated.

Examples:

# Propose single package
porchctl rpkg propose example-repo.example-package-name.example-workspace \
  --namespace=example-namespace

# Propose multiple packages
porchctl rpkg propose pkg1 pkg2 pkg3 --namespace=example-namespace

rpkg approve

Approve a proposal to publish a package revision.

Usage:

porchctl rpkg approve PACKAGE [...] [flags]

Arguments:

PACKAGE - Kubernetes name(s) of package revision(s). Multiple packages can be space-separated.

Examples:

# Approve single package
porchctl rpkg approve example-repo.example-package-name.example-workspace \
  --namespace=example-namespace

# Approve multiple packages
porchctl rpkg approve pkg1 pkg2 --namespace=example-namespace

rpkg reject

Reject a proposal to publish or delete a package revision.

Usage:

porchctl rpkg reject PACKAGE [...] [flags]

Arguments:

PACKAGE - Kubernetes name(s) of package revision(s). Multiple packages can be space-separated.

Examples:

# Reject proposal
porchctl rpkg reject example-repo.example-package-name.example-workspace \
  --namespace=example-namespace

rpkg upgrade

Create a new revision upgrading a downstream package to a newer upstream version.

Usage:

porchctl rpkg upgrade SOURCE_PACKAGE_REVISION [flags]

Arguments:

SOURCE_PACKAGE_REVISION - Target downstream package revision to upgrade. Must be published and have an upstream package.

Flags:

Flag	Description	Default
`--revision int`	Upstream revision number to upgrade to. If omitted, upgrades to latest
`--workspace string`	Workspace name for new package revision	(required)
`--strategy string`	Update strategy: `resource-merge`, `fast-forward`, `force-delete-replace`, `copy-merge`	`resource-merge`
`--discover string`	Discover available updates instead of upgrading. Options: `upstream`, `downstream`

Examples:

# Discover available upstream updates
porchctl rpkg upgrade --discover=upstream

# Upgrade to specific upstream revision
porchctl rpkg upgrade deployment.some-package.v1 --revision=3 --workspace=v2

# Upgrade to latest upstream
porchctl rpkg upgrade deployment.some-package.v1 --workspace=v2

# Upgrade with specific strategy
porchctl rpkg upgrade deployment.some-package.v1 \
  --revision=3 \
  --workspace=v2 \
  --strategy=copy-merge

rpkg propose-delete

Propose deletion of a published package revision.

Aliases: propose-delete, propose-del

Usage:

porchctl rpkg propose-delete PACKAGE [...] [flags]

Arguments:

PACKAGE - Kubernetes name(s) of package revision(s). Multiple packages can be space-separated.

Examples:

# Propose deletion of published package
porchctl rpkg propose-delete example-repo.example-package-name.example-workspace \
  --namespace=example-namespace

rpkg del

Delete a package revision.

Note

To delete a published package revision, it must first be in the DeletionProposed lifecycle state.

Draft and Proposed package revisions can be deleted directly without approval.

Aliases: del, delete

Usage:

porchctl rpkg del PACKAGE [...] [flags]

Arguments:

PACKAGE - Kubernetes name(s) of package revision(s). Multiple packages can be space-separated.

Examples:

# Delete package revision
porchctl rpkg del example-repo.example-package-name.example-workspace \
  -n example-namespace

completion

Generate shell autocompletion scripts.

Usage:

porchctl completion [command]

Available Shells:

bash - Generate bash autocompletion
fish - Generate fish autocompletion
powershell - Generate PowerShell autocompletion
zsh - Generate zsh autocompletion

Examples:

# Generate bash completion
porchctl completion bash > ~/.local/share/bash-completion/completions/porchctl

# Generate zsh completion
porchctl completion zsh > "${fpath[1]}/_porchctl"

See each subcommand’s help for shell-specific installation instructions.

version

Print the version number of porchctl.

Usage:

porchctl version [flags]

Examples:

# Show version
porchctl version