Skip to main content

CLI Reference

This is the developer's working subset of occ, grouped by the task you're trying to do. It is intentionally not exhaustive — for every command, flag, and the platform-engineering surface, see the full upstream CLI reference.

note

DevsPortal is built on the Control Plane Operator engine. occ is that engine's CLI — the same binary on every DevsPortal instance — and the commands here are unchanged. Every example targets the Fedshi instance (https://api.idp.fedshi.com); the examples use the fedshi namespace and checkout project, which you'd swap for your own.

A note on context​

Most commands take -n/--namespace and -p/--project. Set them once in a context and you can drop the flags:

occ config context use fedshi-checkout
occ component list          # uses the context's namespace + project

See Getting access for the full setup.

Config and login​

Order matters: occ login authenticates against the active context's control plane, so register the control plane, create a context for it, and use it before logging in. Skipping the context step leaves the default localhost:8080 active and login fails with connection refused. Full walkthrough in Getting access.

occ config controlplane add fedshi --url https://api.idp.fedshi.com        # register the control plane
occ config context add fedshi-checkout \
--controlplane fedshi --credentials fedshi \
--namespace fedshi --project checkout                       # bind controlplane + creds (+ optional defaults)
occ config context use fedshi-checkout                        # make it active — before login
occ login                                                     # browser (PKCE) login against the active context
occ version                                                   # client + server versions
occ logout

For unattended automation:

occ login --client-credentials --client-id <id> --client-secret <secret>

Discovering what's available​

Before you create anything, see which templates the platform offers:

occ clustercomponenttype list      # ComponentTypes available everywhere
occ clustertrait list              # Traits you can attach
occ clusterworkflow list           # build/CI workflows
occ environment list -n fedshi     # environments in the pipeline
occ deploymentpipeline get default -n fedshi

Projects​

occ project list -n fedshi
occ project get checkout -n fedshi
occ apply -f project.yaml          # create/update from YAML
occ project delete checkout -n fedshi   # also deletes its components

Components​

occ component list -n fedshi -p checkout
occ component get cart-api -n fedshi

# Scaffold a starting YAML from a ComponentType (pre-fills defaults + docs)
occ component scaffold cart-api \
  --clustercomponenttype deployment/service \
  -n fedshi -p checkout -o cart-api.yaml

occ apply -f cart-api.yaml
occ component delete cart-api -n fedshi

Workloads​

occ workload list -n fedshi
occ workload get cart-api -n fedshi
occ apply -f cart-api-workload.yaml

Builds and CI​

occ component workflow run cart-api -n fedshi -p checkout   # trigger a build
occ component workflowrun list cart-api -n fedshi           # runs for this component
occ workflowrun get <run-name> -n fedshi                    # one run's status
occ component workflow logs cart-api -n fedshi -f           # follow build logs

Deploy and promote​

# Deploy latest release to the first environment
occ component deploy cart-api -n fedshi -p checkout

# Deploy a specific release
occ component deploy cart-api --release cart-api-5d7f658d9c

# Promote to the next environment
occ component deploy cart-api --to staging

# Deploy/promote with per-environment overrides
occ component deploy cart-api --to production \
  --set spec.componentTypeEnvironmentConfigs.replicas=3 \
  --set spec.workloadOverrides.env.LOG_LEVEL=warn

# Inspect releases and bindings
occ componentrelease list -n fedshi -p checkout --component cart-api
occ releasebinding list   -n fedshi -p checkout --component cart-api

Rollback is just deploying an older release by name:

occ component deploy cart-api --release cart-api-a1b2c3d4e5

Logs, exec, and troubleshooting​

occ component logs cart-api -n fedshi -p checkout --env development
occ component logs cart-api --env production -f --since 15m
occ component logs cart-api --env development --tail 100

# Shell into the running pod
occ component exec cart-api --env development -it
occ component exec cart-api --env development -- curl -s localhost:8080/health

Secrets​

For private-repo git credentials and other secrets pushed to a target plane:

occ secret list -n fedshi
occ secret create generic github-pat \
  --namespace fedshi --target-plane ClusterWorkflowPlane/default \
  --category git-credentials \
  --from-literal=username=git --from-literal=password=ghp_xxx

Tips​

  • Add -o yaml to get commands when you want the full resource.
  • occ apply -f <file> is the universal create/update; many of the per-resource commands are conveniences around the same API.
  • Generate shell completion once: source <(occ completion zsh).

Full reference​

This page covers the developer happy path. For the complete command set — including authorization (authzrole, authzrolebinding), planes, deployment pipelines, and file-system/GitOps mode — see the upstream CLI reference.