CLI / API Reference

Overview

This section provides reference documentation for interacting with Porch through its command-line interface (CLI) or through the Kubernetes API.

CLI Reference

The porchctl command-line tool provides commands for managing Porch repositories and packages. It communicates with the Porch API server to perform operations like:

• Registering and managing Git repositories
• Creating, cloning, and copying packages
• Managing package lifecycle from creation to deletion (Draft → Proposed → Published -> Deletion-Proposed)
• Pulling and pushing package content
• Upgrading downstream packages

Quick Links:

• Installation
• repo commands - Repository management
• rpkg commands - Package management

API Reference

Generate OpenAPI Specification

You can generate an OpenAPI specification for Porch’s APIs and explore them interactively:

1. Extract OpenAPI specs from your cluster:

# Get config.porch.kpt.dev API spec
kubectl get --raw /openapi/v3/apis/config.porch.kpt.dev/v1alpha1 | jq '.' > config-porch-openapi.json

# Get porch.kpt.dev API spec
kubectl get --raw /openapi/v3/apis/porch.kpt.dev/v1alpha1 | jq '.' > porch-openapi.json

# Combine both specs into single file
jq -s '.[0] * .[1]' config-porch-openapi.json porch-openapi.json > combined-porch-openapi.json

2. Explore the API interactively:

Open Swagger Editor in your browser and import the combined-porch-openapi.json file to:

• Browse all API endpoints and operations
• View request/response schemas
• Test API calls directly from the browser
• Generate client code in various languages

API Reference Guide

The complete field-level reference for Porch’s Aggregated API Resources and Kubernetes Custom Resource Definitions (CRDs):

The following lists provide a summary of the resources documented in the generated API and CRD guide:

porch.kpt.dev/v1alpha1:

• PackageRevision - Represents a specific revision of a package with metadata and lifecycle state
• PackageRevisionResources - Contains a list of the files in a package revision, there is one PackageRevisionResources resource for each PackageRevision resource
• PorchPackage - Represents a package in a repository, with one or more PackageRevision resources in each package

config.porch.kpt.dev/v1alpha1:

• Repository - Connects Porch to Git repositories
• PackageVariant - Automates package cloning and updates
• PackageVariantSet - Manages sets of package variants

The API reference provides detailed information about:

• Field names, types, and descriptions
• Validation rules and constraints
• Nested object structures
• Enum values and options

Quick Links:

• Aggregated API Resources
• Custom Resources

When to Use CLI vs API

Use porchctl CLI when:

• Performing interactive operations
• Quick one-off tasks
• Learning Porch workflows
• Debugging package issues
• Manual package management

Use Kubernetes API (kubectl) when:

• Automating operations in scripts
• Integrating with CI/CD pipelines
• Building custom controllers
• Managing resources declaratively
• Applying GitOps patterns

Using Either:

Most Porch operations can be performed with either porchctl or kubectl. For example:

With porchctl:

porchctl rpkg get --namespace default

With kubectl:

kubectl get packagerevisions -n default

Choose the tool that best fits your workflow and automation needs.