OpenClaw EnterpriseDOCSGitHub

OCC CLI command reference

Install occ with CLI setup; use occ --help for usage.

Global options

Flags override environment variables. Empty values (--file=, --revision=) fail before execution; omit a flag to use its default. --ca-bundle= clears its environment variable; --namespace= does so for Installation-scoped service-key create.

Flag Environment variable What it controls
--url OCC_URL Required for resource commands. An HTTP or HTTPS origin, without embedded credentials, a base path, query, or fragment.
--service-key-file OCC_SERVICE_KEY_FILE Required for resource commands. Path to the complete bootstrap or issued service-key JSON response.
--namespace OCC_NAMESPACE Required for configuration, secret, preset, credential-source, iam, and agent commands. Supply the Namespace ID, not its name.
--ca-bundle OCC_CA_BUNDLE Adds a PEM certificate-authority bundle to the system trust roots for HTTPS. TLS verification cannot be disabled.
--timeout-seconds OCC_TIMEOUT_SECONDS Positive whole seconds for an OCC request or installation handoff check. Default: 30.
--output, -o — Command-specific formats and defaults appear in --help. Unsupported explicit values fail before requests.
--help, -h — Prints help for the command.
--version, -v — Prints the CLI version. Source builds report dev; published binaries report their OCE release version.

The service-key JSON must contain a nonempty data.key with no line breaks. The client sends it as x-api-key and does not follow redirects. Host letter case does not change same-origin redirect advice. Use a trusted HTTPS endpoint unless connecting to a local loopback development Installation. See Service API Keys for issuing or rotating keys.

Ctrl-C or SIGTERM cancels requests and exits nonzero. If I/O or cleanup blocks, a second interrupt terminates immediately; cleanup may remain incomplete.

Resource commands

Replace ID with the resource ID, NAME with a Namespace name, and FILE with a JSON file path. --file requires local JSON, not stdin or YAML. The server validates document fields against the HTTP API contract. --help on configuration, secret, agent, iam role, and iam access-binding create shows a minimal sample document.

Command What it does
occ installation get Reads the singleton Installation.
occ installation deployment-inventory Reads the complete Agent deployment inventory for a coordinated fleet operation.
occ namespace list Lists authorized Namespaces. ADOPTED NAMESPACE is set only for adopted Kubernetes namespaces.
occ namespace get ID Reads one Namespace and its status.
occ namespace create NAME Creates a Namespace. --existing-namespace K8S_NAME requests adoption of an operator-prepared Kubernetes namespace and also requires Installation administer. The CLI refuses a name that is not a DNS-1123 label of at most 63 characters, the same rule as the API, before it sends the request. Explicitly supplying an empty value is refused; omit the flag to request managed placement.
occ namespace delete ID Begins deleting an empty Namespace. Use namespace get to inspect the resulting state. Its name stays reserved and cannot be reused.
occ configuration create --file FILE Creates a Configuration. The body contains kind and values.
occ configuration get ID Reads a Configuration.
occ configuration update ID --file FILE Updates a Configuration; the body must replace values. Omit the create-only kind.
occ configuration delete ID Deletes an unreferenced Configuration.
occ secret create --file FILE Stores a Namespace Secret from a protected JSON document.
occ secret list Lists Namespace Secret metadata, never values.
occ secret get ID Reads Secret metadata, never its value, and the readable resources that reference it (CONSUMERS).
occ secret update ID --file FILE Replaces the Secret value; consumers require explicit redeployment.
occ secret delete ID Deletes an unreferenced Namespace Secret.
occ preset list Lists the Namespace's Presets the caller can read: ID, name, and creation time.
occ preset get ID Reads a Preset; -o json or -o yaml includes its template.
occ preset delete ID Deletes a Preset and its exact-resource AccessBindings. Agents and Configurations created from it are unchanged.
occ credential-source create --file FILE Registers a Secret with the selected Credential Gateway. See credential sources.
occ credential-source list Lists credential sources without live gateway status.
occ credential-source get ID Reads a credential source and its live gateway status, never its value.
occ credential-source delete ID Deletes an unreferenced credential source and the gateway's copy.
occ credential-source update ID [--file FILE] Pushes current Secret values, or the replacement secrets in FILE, to the gateway copy. Running Agents use them after a redeploy. An oauth2-refresh-token source needs FILE naming a new refresh_token Secret.
occ credential-source rotate ID Mints a new token for a refresh-type source now; running Agents need no redeploy. See rotate a refresh source.
occ service-account list Lists the Namespace's ServiceAccounts: ID and name.
occ service-account delete ID [--force] Deletes an unreferenced ServiceAccount and revokes its access token. --force also deletes one whose ChatGPT Backend is gone; a ChatGPT workspace administrator then revokes the token at the provider. See service accounts.
occ iam role list Lists Namespace Roles.
occ iam role get ID Reads a Namespace Role.
occ iam role create --file FILE Creates a Namespace Role with explicit permissions.
occ iam role delete ID Deletes an unreferenced Namespace Role.
occ iam access-binding list Lists Namespace AccessBindings. The SUBJECT KIND column distinguishes identity and group subjects in list, get, and create tables.
occ iam access-binding get ID Reads a Namespace AccessBinding.
occ iam access-binding create --file FILE Grants a Role to a principal for an exact resource.
occ iam access-binding delete ID Deletes a Namespace AccessBinding.
occ iam service-principal create Creates a Namespace ServicePrincipal with no grant, for automation or a member's CLI key.
occ iam service-principal list Lists the Namespace's non-Agent ServicePrincipals.
occ iam service-principal get ID Reads a Namespace ServicePrincipal.
occ service-key create With --service-principal ID --name NAME --out FILE, issues a service key into a new 0600 file; never prints the key.
occ service-key revoke ID Revokes a service key.
occ agent delete ID Begins asynchronous Agent deletion, including its owned runtime state.
occ agent list Lists authorized Agents in the selected Namespace.
occ agent get ID Reads an Agent's desired state, selected version and Harness Sandbox status.
occ agent create --file FILE Creates an Agent draft.
occ agent update ID --file FILE Updates editable Agent fields; the body must include configurationId.
occ agent deploy ID [--harness-overrides FILE] [--retain-harness-overrides REVISION_ID] Requests deployment once and creates an immutable version. With neither override flag, uses current Installation defaults. See Harness destinations.
occ agent deploy-first ID --configuration ID --generation N --key KEY Admits the reviewed first deployment and returns its receipt. On an uncertain reply, prints a read-only recovery command without resending. See first deployment.
occ agent recover-first-deployment ID --configuration ID --generation N --key KEY Reads the original receipt without deploying. A missing receipt does not authorize a retry.
occ agent revision AGENT_ID REVISION_ID Reads an exact revision and its Harness settings with agent_revision:read. Structured output preserves the API response, including saved-configuration read errors.
occ agent revisions ID Lists version summaries newest first, with generation, deployment status, and * on the active version. Ended work shows superseded or stopped. --limit accepts 1–100 (default 50); --cursor reads older versions. A failed continuation notice makes the command unsuccessful.
occ agent deployment-status ID [DEPLOYMENT_ID] Shows recorded deployment status, errors, warnings, and redeployment notices. Defaults to the latest readable revision and explains the selection on stderr. With Agent read access, shows desired state and active revision. JSON and YAML include currentAgent, with activeRevisionId: null when no revision is active.
occ agent runtime-credentials get ID Reads whether generated runtime credentials are configured for the Agent.
occ agent runtime-credentials provision ID Creates the initial generated runtime credential bundle (empty request body).
occ agent credential-withdrawal request ID SOURCE_ID Revokes a credential source from the Agent's selected version; see withdrawal.
occ agent credential-withdrawal get ID SOURCE_ID Shows whether that withdrawal is pending or revoked, who requested it, and the reason code of the latest attempt.
occ agent stop ID Requests a stop while retaining versions and persistent state; occ agent deploy ID starts it again.
occ agent runtime ID Reads Pod status, restarts, last termination, log sources and Events for a version. See runtime logs.
occ agent logs ID --source SOURCE Prints one redacted page of container output, or follows it. See runtime logs.

Use the HTTP API for configured Backends, ServiceAccount operations outside this inventory and Preset writes. Configuration listing is unavailable. After deployment, agent get reports desired state, lifecycle and selected version. Use agent deployment-status ID for the latest status and error. Verify model execution separately.

For unreadable saved settings, Agent reads retain metadata and identify the field in CONFIGURATION ERROR or structured configurationReadError. History leaves unreadable versions' status null and reports them on stderr. An unreadable Agent skips all status reads. See the CLI browsing flow.

service-key create --out FILE creates a new 0600 file before issuance, including under a restrictive umask. Existing files and symlinks fail. --expires-in-days accepts 1–365 and defaults to 30. Explicit zero fails before creating the file.

Resource IDs require the correct prefix and UUID. Errors identify the resource kind and list command.

installation get, installation deployment-inventory and namespace list require an Installation-scoped service key. A Namespace-scoped key can read its Namespace with namespace get ID. Inventory requires Installation administer, read on every Namespace, Agent and selected revision, and deploy on each running Agent eligible for coordinated deployment. Any missing grant fails the inventory. JSON and YAML include desired runtime state, execution mode, selected version and queued or claimed deployment work.

Installation handoff

All three commands require --kubeconfig, --context, --kube-namespace and --release. Use the CLI matching the chart. Output is text.

Runtime status and logs

occ agent runtime AGENT_ID and occ agent logs AGENT_ID read the Agent logs routes. Without --revision ID, a candidate with Pods is read unless exact active metadata proves it older. Unreadable or invalid active metadata does not exclude that Pod candidate. A candidate with only provider Harness status (running, starting, or lost) needs to be proven newer; unknown alone is not runtime evidence. Otherwise both read the selected version, else the latest version you can read. They print the revision ID they read to stderr; a reader without Agent operate cannot probe runtime status, so the notice names the other readable version to pass. Notices call any other version newer or older only when the selected version's metadata proves it. runtime accepts -o table|json|yaml and needs Agent operate and read plus read on the Agent revision. Its table output ends with each Pod's Events (POD, CONTAINER, TYPE, REASON, COUNT, LAST SEEN, MESSAGE); CONTAINER is - for Pod-level Events. logs needs Agent read_logs (or administer) and read, which cover every version, and each view is audited. Default selection lists only revisions you can read: without Agent revision grants, logs reads the selected version and says it skipped the newer-version check; with none selected, its error names the grant and --revision ID.

occ agent logs flag Meaning
--source SOURCE Required: gateway, agent (dedicated Harness container) or sandbox (OpenShell policy decisions; no --pod or --previous).
--revision ID Version to read; defaults as described above.
--pod NAME Pod to read when the source has more than one.
--previous Read the container instance before the last restart.
--tail N Lines from the end of the stream, 1 to 1000 (default 200).
--since DURATION Only lines newer than a Go duration such as 10m, at least 1s, up to 24h. Omit the flag for no time filter.
--follow Poll every 2 seconds with the view's cursor until Ctrl-C.
--level LEVEL Only error, warn, info or debug lines and above, filtered by OCC after --tail (the last N lines are read, then filtered, so fewer may print); lines of unknown level stay. Default: every level.
-o text or -o json Text lines (default) or NDJSON, one API record per line.

Text output prints TIME LEVEL KIND [SUBSYSTEM] MESSAGE key=value per line. Gap and withheld records are printed to stderr as notice: lines; in JSON mode they are also records on stdout. In text mode, the CLI exits with a nonzero status if it cannot write a no-running-Pod, gap, or withheld notice to stderr. Text lines and notices show an invisible or control character, such as a bidirectional override, as an escape like \u202e; a field value holding one is quoted. JSON records are unchanged. With --follow, the CLI waits for Retry-After after a 429, retries after a 504, starts a new audited view when the cursor is rejected, and exits cleanly on Ctrl-C. 501, 503 and permission errors end the command with a nonzero exit. --follow cannot be combined with --previous.

sh
occ agent runtime agt_...occ agent logs agt_... --source gateway --since 10mocc agent logs agt_... --source gateway --follow -o json | jq -r .message

Output and errors

Table output is meant for people; it prints - for unset fields and No resources found. for an empty list. A cell holding an invisible or control character, such as a bidirectional override in a name, is printed quoted with that character escaped; so is a value that starts with ". JSON and YAML print the exact resource or array without the HTTP envelope. Deleting a Configuration prints Deleted configuration ID. in table mode; structured output contains deleted, kind, and id.

Failures go to stderr and the CLI exits nonzero. For HTTP errors, the CLI prints the status and, when present, the API error code and message, and the Retry-After delay. Delay-seconds and HTTP-date values (HTTP semantics) up to one hour are accepted and rounded up to whole seconds for notices and waits; an expired or invalid date keeps the normal follow interval. It does not print the server's request ID. To capture that ID for a failed request, use the HTTP API directly.

OCC's 403 names the grant you lack. A generic 403 from an older OCC gets a hint: line naming the grants the command needs, and a Namespace-scoped key used elsewhere gets one naming its Namespace. A create's hint says only an Installation administrator can create that resource. OCC refuses a missing ID the same way as one you cannot read.

Local development

Local development commands covers occ dev up, occ dev check and occ dev down.

Agent policy commands default to --facet networking. Editing admission is temporary pending Guardrails.

Search documentation