Skip to main content
Version: v0.11.x

CLI Reference

The occ (OpenChoreo CLI) is a command-line interface tool for interacting with OpenChoreo. It provides commands to manage organizations, projects, components, deployments, and other OpenChoreo resources.

Global Options​

All commands support the following global options through context configuration:

  • --organization - Organization name
  • --project - Project name
  • --component - Component name
  • --environment - Environment name
  • --dataplane - Data plane name

These can be set in a configuration context to avoid repeating them in every command. See the config command for details.

Commands​

login​

Login to OpenChoreo CLI.

Usage:

occ login [flags]

Flags:

  • --client-credentials - Use OAuth2 client credentials flow for authentication
  • --client-id - OAuth2 client ID for service account authentication
  • --client-secret - OAuth2 client secret for service account authentication
  • --credential - Name to save the credential as in config
  • --url - Control plane URL to update

Examples:

# Interactive login (default PKCE flow)
occ login

# Service account login with client credentials
occ login --client-credentials --client-id <client-id> --client-secret <client-secret>

# Login to a specific control plane URL
occ login --url https://api.openchoreo.example.com

logout​

Logout from OpenChoreo CLI.

Usage:

occ logout

Examples:

occ logout

version​

Print version information for both the CLI client and the OpenChoreo server.

Usage:

occ version

Examples:

occ version

apply​

Apply a configuration file to create or update OpenChoreo resources.

Usage:

occ apply -f <file>

Flags:

  • -f, --file - Path to the YAML file containing resource definitions

Examples:

# Apply a single resource file
occ apply -f organization.yaml

# Apply a component configuration
occ apply -f my-component.yaml

create​

Create OpenChoreo resources like projects, components, and workloads.

Usage:

occ create <resource-type> [flags]

create workload​

Create a workload from a workload descriptor file.

Usage:

occ create workload [flags]

Flags:

  • --name - Name of the workload
  • --organization - Organization name
  • --project - Project name
  • --component - Component name
  • --descriptor - Path to the workload descriptor file
  • --image - Docker image URL
  • -o, --output - Output file path for the generated workload resource

Examples:

# Create workload from descriptor
occ create workload --descriptor workload.yaml --organization acme-corp \
  --project online-store --component product-catalog --image myimage:latest

# Create workload and save to file
occ create workload --descriptor workload.yaml --organization acme-corp \
  --project online-store --component product-catalog --image myimage:latest \
  --output workload-cr.yaml

delete​

Delete OpenChoreo resources by file names.

Usage:

occ delete -f <file> [flags]

Flags:

  • -f, --file - Path to the YAML file containing resources to delete
  • -w, --wait - Wait for the deletion to complete

Examples:

# Delete resources from a file
occ delete -f resources.yaml

# Delete and wait for completion
occ delete -f resources.yaml --wait

scaffold​

Generate scaffolded resource YAML files from existing CRDs.

Usage:

occ scaffold <resource-type> [flags]

scaffold component​

Scaffold a Component YAML from ComponentType and Traits.

Usage:

occ scaffold component [flags]

Flags:

  • --name - Component name
  • --type - Component type in format workloadType/componentTypeName (e.g., deployment/web-app)
  • --traits - Comma-separated list of trait names to include
  • --workflow - ComponentWorkflow name to include in the scaffold
  • --organization - Organization name (can be omitted if set in context)
  • --project - Project name (can be omitted if set in context)
  • -o, --output-file - Write output to specified file instead of stdout
  • --skip-comments - Skip section headers and field description comments for minimal output
  • --skip-optional - Skip fields with defaults

Examples:

# Scaffold a basic component
occ scaffold component --name my-app --type deployment/web-app

# Scaffold with traits
occ scaffold component --name my-app --type deployment/web-app --traits storage,ingress

# Scaffold with workflow
occ scaffold component --name my-app --type deployment/web-app --workflow docker-build

# Output to file
occ scaffold component --name my-app --type deployment/web-app -o my-app.yaml

# Minimal output without comments
occ scaffold component --name my-app --type deployment/web-app --skip-comments --skip-optional

config​

Manage configuration contexts that store default values (e.g., organization, project, component) for occ commands.

Usage:

occ config <subcommand> [flags]

config get-contexts​

List all available configuration contexts.

Usage:

occ config get-contexts

Examples:

# Show all configuration contexts
occ config get-contexts

config set-context​

Create or update a configuration context.

Usage:

occ config set-context <context-name> [flags]

Flags:

  • --organization - Organization name stored in this configuration context
  • --project - Project name stored in this configuration context
  • --component - Component name stored in this configuration context
  • --dataplane - Data plane reference stored in this configuration context
  • --environment - Environment name stored in this configuration context
  • --mode - Context mode: api-server (default) or file-system
  • --root-directory-path - Root directory path for file-system mode (defaults to current directory)

Examples:

# Set a configuration context named acme-corp-context
occ config set-context acme-corp-context --organization acme-corp \
  --project online-store --environment dev

# Set a file-system mode context
occ config set-context local-dev --mode file-system --root-directory-path /path/to/resources

config use-context​

Switch to a specified configuration context.

Usage:

occ config use-context <context-name>

Examples:

# Switch to the configuration context named acme-corp-context
occ config use-context acme-corp-context

config current-context​

Display the currently active configuration context.

Usage:

occ config current-context

Examples:

# Display the currently active configuration context
occ config current-context

config set-control-plane​

Configure OpenChoreo API server connection.

Usage:

occ config set-control-plane [flags]

Flags:

  • --name - Name of the control plane configuration
  • --url - OpenChoreo API server endpoint URL

Examples:

# Set remote control plane endpoint
occ config set-control-plane --name production --url https://api.openchoreo.example.com

# Set local control plane (for development)
occ config set-control-plane --name local --url http://localhost:8080

component-release​

note

This command only works in file-system mode. Set your context mode to file-system before using this command.

Usage:

occ component-release <subcommand> [flags]

component-release generate​

Generate ComponentRelease resources from Component, Workload, ComponentType, and Trait definitions.

Usage:

occ component-release generate [flags]

Flags:

  • --all - Process all resources
  • --project - Project name
  • --component - Component name (requires --project)
  • --output-path - Custom output directory path
  • --dry-run - Preview changes without writing files

Examples:

# Generate releases for all components
occ component-release generate --all

# Generate releases for all components in a specific project
occ component-release generate --project demo-project

# Generate release for a specific component (requires --project and --output-path)
occ component-release generate --project demo-project --component greeter-service \
  --output-path ./releases

# Dry run (preview without writing)
occ component-release generate --all --dry-run

# Custom output path
occ component-release generate --all --output-path /custom/path

release-binding​

note

This command only works in file-system mode. Set your context mode to file-system before using this command.

Usage:

occ release-binding <subcommand> [flags]

release-binding generate​

Generate ReleaseBinding resources that bind component releases to environments.

Usage:

occ release-binding generate [flags]

Flags:

  • -e, --target-env - Target environment for the release binding (required)
  • --use-pipeline - Deployment pipeline name for environment validation (required)
  • --all - Process all resources
  • --project - Project name
  • --component - Component name (requires --project)
  • --component-release - Explicit component release name (only valid with --project and --component)
  • --output-path - Custom output directory path
  • --dry-run - Preview changes without writing files

Examples:

# Generate bindings for all components in development environment
occ release-binding generate --target-env development --use-pipeline default-pipeline --all

# Generate bindings for all components in a specific project
occ release-binding generate --target-env staging --use-pipeline default-pipeline \
  --project demo-project

# Generate binding for a specific component
occ release-binding generate --target-env production --use-pipeline default-pipeline \
  --project demo-project --component greeter-service

# Generate binding with explicit component release
occ release-binding generate --target-env production --use-pipeline default-pipeline \
  --project demo-project --component greeter-service \
  --component-release greeter-service-20251222-3

# Dry run (preview without writing)
occ release-binding generate --target-env development --use-pipeline default-pipeline \
  --all --dry-run

# Custom output path
occ release-binding generate --target-env development --use-pipeline default-pipeline \
  --all --output-path /custom/path

Configuration​

The CLI stores its configuration in ~/.occ/config.yaml. This file contains:

  • Control planes: API server endpoints and connection details
  • Credentials: Authentication tokens and client credentials
  • Contexts: Named sets of default values for commands

Configuration File Structure​

currentContext: my-context
controlplanes:
  - name: production
    url: https://api.openchoreo.example.com
credentials:
  - name: my-creds
    clientId: <client-id>
    clientSecret: <client-secret>
    token: <access-token>
    refreshToken: <refresh-token>
    authMethod: pkce  # or "client_credentials"
contexts:
  - name: my-context
    controlplane: production
    credentials: my-creds
    organization: acme-corp
    project: online-store
    component: product-catalog
    environment: development
    mode: api-server  # or "file-system"
    rootDirectoryPath: /path/to/resources  # for file-system mode

Modes​

The CLI supports two modes:

  1. API Server Mode (api-server): Connects to an OpenChoreo API server to manage resources remotely. This is the default mode.

  2. File System Mode (file-system): Works with resources stored as YAML files in a directory structure. Useful for GitOps workflows and local development.