ork CLI
Install and configure the ork command-line interface, and navigate its command tree for managing registry resources in Orca Agent Engine.
The ork command-line interface (CLI) manages the registry resources that Orca Agent Engine exposes for a Workspace: managed agents and their related objects, policy guardrails, connections, functions, Kafka Connect connectors, packages, sources, and sinks. The CLI talks directly to the per-Workspace registry endpoint, so every command operates on a single Workspace.
ork is a Go program built with Cobra. It is distributed from the public orca-ae/orca-cli repository.
Install
Install ork with Homebrew on macOS or Linux:
brew install orca-ae/tap/orkYou can also download a v0.5.0 release archive for macOS, Linux, or Windows. With Go 1.25 or later, install the same version from the module:
go install github.com/orca-ae/orca-cli/cmd/ork@v0.5.0For a Go install, add $(go env GOPATH)/bin to your PATH if needed, or use your configured GOBIN. Confirm the installation with ork --version.
Configure
Every command needs the Workspace registry base URL. Except for the core healthz and readyz probes, commands also need one credential: a registry bearer token or a Workspace API key. Provide values with global flags or environment variables.
| Flag | Environment variable | Description |
|---|---|---|
--registry-url | ORCA_REGISTRY_URL | Deployment host root URL, with no path. A value ending in /v1/registry, /v1, or /api/v1 is stripped with a deprecation warning. |
--access-token | ORCA_ACCESS_TOKEN | Workspace registry bearer token (a Workspace service-account token). |
--api-key | ORCA_API_KEY | Workspace API key, sent as x-api-key. |
These flags are persistent: they apply to every subcommand. When a flag is omitted, the CLI falls back to its matching environment variable. --access-token and --api-key are mutually exclusive; regular commands fail unless exactly one is set. ork healthz and ork readyz need only --registry-url and send no credentials.
The CLI environment variables differ from the SDK's. The ork CLI reads ORCA_REGISTRY_URL plus ORCA_ACCESS_TOKEN or ORCA_API_KEY. The TypeScript SDK reads ORCA_BASE_URL and ORCA_API_KEY. Configure each URL for its client rather than substituting one variable for the other.
Get your registry endpoint
Registry endpoint
Examples on this page target your registry endpoint - the deployment host root, with no path
suffix. For CLI, set ORCA_REGISTRY_URL and exactly one of ORCA_ACCESS_TOKEN (Bearer) or
ORCA_API_KEY (x-api-key). For TypeScript SDK, set ORCA_BASE_URL / ORCA_API_KEY (Bearer).
To find the endpoint, see Connect to the registry.
Export your environment
Set the environment variables once and reuse them across commands:
export ORCA_REGISTRY_URL="https://workspace.example.streamnative.cloud"
export ORCA_ACCESS_TOKEN="<your-service-account-token>"To authenticate with a Workspace API key, use ORCA_API_KEY instead of ORCA_ACCESS_TOKEN. Do not set both. The examples throughout this reference use ORCA_ACCESS_TOKEN; replace its flag or environment variable with --api-key or ORCA_API_KEY when appropriate.
Output formats
Most read commands accept an -o / --output flag that selects the rendering format. The default is text, a human-readable table or field list. Use json or yaml for scripting and automation:
ork connections list -o json
ork agent get my-agent-id -o yamlValid values are text, json, and yaml. An unsupported value fails with --output must be one of: text, json, yaml.
Your first command
With your environment configured, list the connections in your Workspace:
ork connections listTo target a Workspace without exporting environment variables, pass the global flags directly:
ork connections list \
--registry-url "https://workspace.example.streamnative.cloud" \
--access-token "<your-service-account-token>"Command tree
ork groups commands by registry resource. Commands that require the cloud.sn.io extension are unavailable on a self-hosted engine. Run ork api-groups to discover extensions, then ork api-resources to list Cloud resources.
| Command group | What it manages |
|---|---|
ork agent | Managed agents and their sessions, memory stores, vaults, environments, files, skills, and triggers. |
ork guardrails | Guardrails and the builtin type catalog, exposed through the policy.runorca.ai extension. |
ork connections | Cloud extension: Pulsar, Kafka, and generic connections, including health tests. |
ork functions | Cloud extension: functions over Pulsar or Kafka, including lifecycle, status, stats, state, and Pulsar-only trigger commands. |
ork kafka-connect | Cloud extension: Kafka Connect connectors, plugins, offsets, worker health, and cluster info. |
ork packages | Cloud extension: versioned function, source, and sink package artifacts. |
ork sources and ork sinks | Cloud extension: Pulsar IO sources and sinks, plus connector catalogs. |
ork api-versions | Authenticated core API version discovery. |
ork healthz, ork readyz | Unauthenticated core liveness and readiness probes. |
ork health live, ork health ready | Cloud extension registry liveness and readiness probes. |
ork api-groups, ork api-resources | Authenticated extension and Cloud resource discovery. |
Run any command with --help to see its subcommands, flags, and usage:
ork agent --help
ork agent sessions --help