ork agent

Manage Orca managed agents and their sessions, memory stores, vaults, environments, files, skills, and triggers with the ork agent commands.

The ork agent commands manage managed agents and their related objects through the Workspace registry API. The group is organized by resource: the agent definition itself, plus sessions, memory stores, memory versions, vaults, environments, files, skills, providers, and triggers. The agents alias is equivalent to agent.

Commands read --registry-url / ORCA_REGISTRY_URL and exactly one credential: --access-token / ORCA_ACCESS_TOKEN or --api-key / ORCA_API_KEY. See ork CLI for setup.

Read commands accept -o / --output with values text, json, or yaml (default text). Most ork agent payloads are JSON or key=value pairs, and the create and update results render as JSON-or-text.

Command tree

ork agent
├── list | get | create | update | archive | versions   Manage the agent definition
├── sessions        (list | get | create | update | delete | archive | outcome)
│   ├── resources   (list | get | add | update | delete)
│   ├── files       (list | get | content | delete)
│   ├── events      (list | send | stream)
│   │   └── send    (message | outcome | tool-confirmation)
│   └── threads     (list | get | archive)
│       └── events  (list | stream)
├── memory-stores   (list | get | create | update | delete | archive)
│   └── memories    (list | get | create | update | delete)
├── memory-versions (list | get | redact)
├── vaults          (list | get | create | update | delete | archive)
│   └── credentials (list | get | create | update | delete | archive | validate)
├── environments    (list | get | create | update | delete | archive)
├── files           (list | get | create | delete | content)
├── skills          (list | get | create | delete)
│   └── versions    (list | get | content | create | delete)
├── providers       (list | get)
└── triggers        (list | get | create | update | delete | pause | unpause | sessions)

The list, get, create, update, delete, and archive operations behave consistently across resources. Identifiers are positional arguments named after the resource (agent-id, session-id, vault-id, and so on).

memory-versions is a top-level group under ork agent, not a subcommand of memory-stores. Every memory-versions command still requires --memory-store to name the parent store.

Agent definition

Manage the agent resource: model, system prompt, tools, MCP servers, and skills.

ork agent list

List the managed agents in the Workspace.

ork agent list [flags]

Flag	Shorthand	Default	Description
`--limit`		`0`	Maximum number of results to return.
`--page`			Pagination cursor.
`--include-archived`		`false`	Include archived objects.
`--metadata`			Metadata filter in `key=value` form. Repeatable.
`--provider`			Managed agent provider name.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

ork agent list --limit 20 -o json \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN"

ork agent get

Get one managed agent by ID. Pass --version to read a historical snapshot instead of the latest version.

ork agent get [agent-id] [flags]

Flag	Shorthand	Default	Description
`--version`		`0`	Agent version to get. Must be greater than 0 when set.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

ork agent get support-triage --version 3 -o json

ork agent create

Create a managed agent. Set the model with --model (a model name) or --model-json (a full model JSON value) - one of the two is required - and attach tools, MCP servers, and skills as needed.

ork agent create [flags]

Flag	Default	Description
`--model`		Agent model name. Required unless you pass `--model-json`.
`--model-json`		Agent model JSON value. Cannot be combined with `--model`.
`--name`		Agent name.
`--description`		Agent description.
`--system`		Agent system prompt.
`--mcp-server`		MCP server in `key=value` form: `name={name},type={type},url={url}`. Repeatable.
`--tool-json`		Agent tool JSON object. Repeatable.
`--skill`		Agent skill reference: `[anthropic:
`--multiagent-type`		Agent multiagent type.
`--multiagent-agent`		Multiagent roster entry: `{agent-id}`, `{agent-id}@{version}`, or `type={type},id={agent-id},version={version}`. Repeatable.
`--provider`		Managed agent provider name.
`--beta-version`		Provider beta version override.
`--metadata`		Metadata in `key=value` form. Repeatable.
`--output`	`-o` (`text`)	Output format: `text`, `json`, or `yaml`.

ork agent create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --name support-triage \
  --model claude-sonnet-4-5 \
  --system "You triage incoming support requests." \
  --skill pdf-reader@1.0.0

ork agent update

Update a managed agent. The agent ID is a positional argument. The update posts to the agent path and creates a new version, so pass the fields you want the new version to carry.

ork agent update [agent-id] [flags]

update accepts the same payload flags as create. --model is not required. Pass --version when you need optimistic concurrency.

Flag	Default	Description
`--version`	`0`	Optional agent version for optimistic concurrency. Must be greater than 0 when set.

ork agent update support-triage \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --version 3 \
  --system "You triage and prioritize incoming support requests."

ork agent archive

Archive a managed agent by ID.

ork agent archive [agent-id]

ork agent versions

List the versions of a managed agent.

ork agent versions [agent-id] [flags]

Flag	Shorthand	Default	Description
`--limit`		`0`	Maximum number of results to return.
`--page`			Pagination cursor.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

ork agent versions support-triage -o json

Sessions

Manage sessions - running instances of an agent inside an environment - and their resources, events, and threads.

Sessions are top-level registry objects addressed by session ID alone. Only sessions create requires --agent, which the CLI sends as the agent field on the request body. On sessions list, --agent is an optional filter sent as the agent_id query parameter. The get, update, delete, and archive commands take no --agent flag at all.

ork agent sessions list

ork agent sessions list [flags]

Flag	Shorthand	Default	Description
`--agent`			Filter by parent managed agent id. Optional.
`--limit`		`0`	Maximum number of results to return.
`--page`			Pagination cursor.
`--include-archived`		`false`	Include archived sessions.
`--metadata`			Metadata filter in `key=value` form. Repeatable.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

ork agent sessions get

ork agent sessions get [session-id] [flags]

Flag	Shorthand	Default	Description
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

ork agent sessions create

Create a session. Pass --agent or --agent-json to select its agent.

ork agent sessions create --environment-id <environment-id> (--agent <agent-id> | --agent-json <json>) [flags]

Flag	Default	Description
`--agent`		Parent managed agent id. Required unless you pass `--agent-json`.
`--agent-version`	`0`	Positive agent version to pin. Requires `--agent`.
`--agent-json`		Agent reference or agent-with-overrides JSON object. Cannot be combined with `--agent` or `--agent-version`.
`--environment-id`		Session environment id.
`--vault-id`		Session vault id. Repeatable.
`--title`		Session title.
`--resource-json`		Session resource JSON object. Repeatable.
`--initial-event-json`		Initial session event JSON object. Repeatable.
`--beta-version`		Provider beta version override.
`--metadata`		Metadata in `key=value` form. Repeatable.
`--output`	`-o` (`text`)	Output format: `text`, `json`, or `yaml`.

ork agent sessions create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --agent support-triage \
  --environment-id env-prod \
  --vault-id vault-github \
  --title "Triage run 2026-06-15"

ork agent sessions update, delete, archive

Update, delete, or archive a session by ID. None of these take --agent. update accepts the same payload flags as create except --agent, and repeating --vault-id replaces the session's vault_ids array.

ork agent sessions update [session-id] [flags]
ork agent sessions delete [session-id]
ork agent sessions archive [session-id]

ork agent sessions update sess-123 --vault-id vault-github --vault-id vault-jira

Session outcome

Get evaluated outcome for a session.

ork agent sessions outcome [session-id] [flags]

outcome accepts -o / --output with text, json, or yaml.

Session resources

Manage the resources mounted into a session - files, memory stores, or GitHub repositories. Every command requires --session.

ork agent sessions resources list --session <session-id> [flags]
ork agent sessions resources get [resource-id] --session <session-id> [flags]
ork agent sessions resources add --session <session-id> --type <type> [flags]
ork agent sessions resources update [resource-id] --session <session-id> [flags]
ork agent sessions resources delete [resource-id] --session <session-id>

The add command requires --type; update accepts the same flags without requiring --type.

Flag	Default	Description
`--session`		Parent managed agent session id. Required.
`--type`		Resource type: `file`, `memory-store`, or `github-repository`. Required on `add`.
`--file-id`		File resource id.
`--memory-store-id`		Memory store resource id.
`--access`		File or memory store access.
`--instructions`		Resource instructions.
`--url`		GitHub repository URL.
`--authorization-token`		GitHub repository authorization token.
`--checkout-type`		GitHub checkout type: `branch` or `commit`.
`--branch`		GitHub branch checkout name.
`--commit`		GitHub commit checkout SHA.
`--mount-path`		Resource mount path.
`--property`		Additional resource property in `key=value` form. Repeatable.
`--beta-version`		Provider beta version override.
`--mount-strategy`		File mount strategy: `tarball_prefetch`.
`--output`	`-o` (`text`)	Output format: `text`, `json`, or `yaml`.

ork agent sessions resources add \
  --session sess-123 \
  --type file \
  --file-id file-abc \
  --mount-path /data/input.csv

Session events

Manage events and streaming for a session. Every command requires --session.

ork agent sessions events list --session <session-id> [flags]
ork agent sessions events send --session <session-id> --event-json <json> [flags]
ork agent sessions events send message --session <session-id> --text <text> [flags]
ork agent sessions events send outcome --session <session-id> --description <text> --rubric <text> [flags]
ork agent sessions events send tool-confirmation --session <session-id> --tool-use-id <id> --decision <allow|deny> [flags]
ork agent sessions events stream --session <session-id> [flags]

events list accepts pagination, ordering, timestamp, type, and subpath filters. Bare events send requires at least one --event-json and accepts --output; the typed subcommands below build the event body for you. events stream opens a long-lived stream and can resume from a cursor or filter a subpath and event deltas.

Flag	Default	Description
`--session`		Parent managed agent session id. Required.
`--event-json`		Raw session event JSON object (bare `send` only). Repeatable. Required when you call `send` without a typed subcommand.
`--limit`	`0`	Maximum number of results to return (`list`).
`--page`		Pagination cursor (`list`).
`--order`		Sort order (`list`).
`--created-at-gt`		Return events created after this timestamp (`list`).
`--created-at-gte`		Return events created at or after this timestamp (`list`).
`--created-at-lt`		Return events created before this timestamp (`list`).
`--created-at-lte`		Return events created at or before this timestamp (`list`).
`--event-type`		Event type filter. Repeatable (`list`).
`--subpath`		Filter or stream events from this subpath (`list` and `stream`).
`--from-cursor`		Resume streaming after this event cursor (`stream`).
`--event-delta`		Stream delta type: `agent.message` or `agent.thinking`. Repeatable (`stream`).
`--timeout`		Maximum time to keep the stream open, for example `30s` or `2m` (`stream`). Defaults to no CLI timeout.
`--output`	`-o` (`text`)	Output format: `text`, `json`, or `yaml` (`list` and `send`).

ork agent sessions events send \
  --session sess-123 \
  --event-json '{"type":"user.message","content":[{"type":"text","text":"Summarize the latest report."}]}'

ork agent sessions events stream --session sess-123 --timeout 2m

Typed event subcommands

Rather than hand-writing --event-json, use a typed subcommand. Each one sends a single event of a fixed type and validates its flags before the request. --session is inherited from the parent send command and is required.

Subcommand	Event type	Required flags	Optional flags
`send message`	`user.message`	`--text`	`--output` / `-o`
`send outcome`	`user.define_outcome`	`--description`, `--rubric`	`--max-iterations` (default `3`, must be 1 - 20), `--output` / `-o`
`send tool-confirmation`	`user.tool_confirmation`	`--tool-use-id`, `--decision` (`allow` or `deny`)	`--deny-message`, `--output` / `-o`

ork agent sessions events send message \
  --session sess-123 \
  --text "Summarize the latest report."

send message wraps --text in a single text content block. send tool-confirmation sends --decision as the event's result field and includes deny_message only when you pass --deny-message.

Session threads

Manage the threads within a session. Every command requires --session.

ork agent sessions threads list --session <session-id> [flags]
ork agent sessions threads get [thread-id] --session <session-id> [flags]
ork agent sessions threads archive [thread-id] --session <session-id>

list accepts --limit, --page, and --output. get accepts --output. archive renders text only.

Session thread events

List or stream the events of a thread. Both require --session and --thread.

ork agent sessions threads events list --session <session-id> --thread <thread-id> [flags]
ork agent sessions threads events stream --session <session-id> --thread <thread-id> [flags]

Flag	Default	Description
`--session`		Parent managed agent session id. Required.
`--thread`		Parent managed agent session thread id. Required.
`--limit`	`0`	Maximum number of results to return (`list`).
`--page`		Pagination cursor (`list`).
`--order`		Sort order (`list`).
`--from-cursor`		Resume streaming after this event cursor (`stream`).
`--event-delta`		Stream delta type: `agent.message` or `agent.thinking`. Repeatable (`stream`).
`--timeout`		Maximum time to keep the stream open (`stream`). Defaults to no CLI timeout.
`--output`	`-o` (`text`)	Output format (`list`).

Memory stores

Manage memory store resources.

ork agent memory-stores list [flags]
ork agent memory-stores get [memory-store-id] [flags]
ork agent memory-stores create [flags]
ork agent memory-stores update [memory-store-id] [flags]
ork agent memory-stores delete [memory-store-id]
ork agent memory-stores archive [memory-store-id]

The create and update commands accept:

Flag	Default	Description
`--name`		Memory store name.
`--description`		Memory store description.
`--metadata`		Metadata in `key=value` form. Repeatable.
`--provider`		Managed agent provider name (create only).
`--beta-version`		Provider beta version override.
`--output`	`-o` (`text`)	Output format: `text`, `json`, or `yaml`.

The list command also accepts --limit, --page, --include-archived, --metadata, and --provider. The aliases memory_stores, memory-store, and memory_store are equivalent to memory-stores.

ork agent memory-stores create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --name shared-notes \
  --description "Notes shared across triage sessions"

Memory entries

Manage the individual memory entries inside a store. Every command requires --memory-store. The memory alias is equivalent to memories.

ork agent memory-stores memories list --memory-store <memory-store-id> [flags]
ork agent memory-stores memories get [memory-id] --memory-store <memory-store-id> [flags]
ork agent memory-stores memories create --memory-store <memory-store-id> --path <path> [flags]
ork agent memory-stores memories update [memory-id] --memory-store <memory-store-id> [flags]
ork agent memory-stores memories delete [memory-id] --memory-store <memory-store-id> [flags]

Flag	Shorthand	Default	Description
`--memory-store`			Parent memory store id. Required.
`--path`			Absolute memory path. Required on `create` unless `--content-json` includes it; optional on `update` to rename the entry.
`--content`			Memory entry content. Required on `create` unless `--content-json` includes it; optional on `update`.
`--content-json`			Raw memory entry JSON payload. On `create`, it must include non-empty `path` and `content`. Cannot be combined with `--content`, `--path`, or `--precondition-content-sha256`.
`--precondition-content-sha256`			Update only when current content SHA-256 matches (`update` only).
`--view`			Memory view query value (`get`, `create`, and `update`).
`--expected-content-sha256`			Expected memory content SHA-256 precondition (`delete` only).
`--limit`		`0`	Maximum number of results to return (`list`).
`--page`			Pagination cursor (`list`).
`--depth`			Memory hierarchy depth: `0` or `1` (`list` only).
`--path-prefix`			Filter by an absolute memory path prefix ending in `/` (`list` only).
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

create requires --path and --content, or --content-json with both values. update requires at least one of --path, --content, --precondition-content-sha256, or --content-json. Memory content is limited to 100 KiB.

ork agent memory-stores memories create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --memory-store mems-123 \
  --path /preferences/contact.md \
  --content "The customer prefers email over phone."

Pass --expected-content-sha256 on delete to make the deletion conditional on the entry's current content:

ork agent memory-stores memories delete mem-abc \
  --memory-store mems-123 \
  --expected-content-sha256 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Memory versions

Manage the version history of memory entries. memory-versions is a top-level group under ork agent, not a subcommand of memory-stores, but every command requires --memory-store to name the parent store. The aliases memory_versions, memory-version, and memory_version are equivalent to memory-versions.

ork agent memory-versions list --memory-store <memory-store-id> [flags]
ork agent memory-versions get [version-id] --memory-store <memory-store-id> [flags]
ork agent memory-versions redact [version-id] --memory-store <memory-store-id> [flags]

Flag	Shorthand	Default	Description
`--memory-store`			Parent memory store id. Required.
`--memory-id`			Filter versions by memory id (`list` only).
`--api-key-id`			Filter versions by API key id (`list` only).
`--operation`			Filter by operation: `created`, `modified`, or `deleted` (`list` only).
`--created-at-gte`			Filter versions created at or after this timestamp (`list` only).
`--created-at-lte`			Filter versions created at or before this timestamp (`list` only).
`--view`			Memory view: `basic` or `full` (`list` and `get`).
`--limit`		`0`	Maximum number of results to return (`list`).
`--page`			Pagination cursor (`list`).
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

redact removes the stored content of a single version while leaving the version record in place. It is not reversible.

ork agent memory-versions list \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --memory-store mems-123 \
  --memory-id mem-abc \
  -o json

ork agent memory-versions redact memv-456 --memory-store mems-123

Vaults

Manage vaults - per-Workspace credential storage - and the credentials inside them.

ork agent vaults list [flags]
ork agent vaults get [vault-id] [flags]
ork agent vaults create [flags]
ork agent vaults update [vault-id] [flags]
ork agent vaults delete [vault-id]
ork agent vaults archive [vault-id]

The create and update commands accept:

Flag	Default	Description
`--display-name`		Vault display name.
`--metadata`		Metadata in `key=value` form. Repeatable.
`--provider`		Managed agent provider name (create only).
`--beta-version`		Provider beta version override.
`--output`	`-o` (`text`)	Output format: `text`, `json`, or `yaml`.

ork agent vaults create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --display-name "GitHub credentials"

Vault credentials

Manage the credentials stored in a vault. Every command requires --vault.

ork agent vaults credentials list --vault <vault-id> [flags]
ork agent vaults credentials get [credential-id] --vault <vault-id> [flags]
ork agent vaults credentials create --vault <vault-id> (--auth-json <json> | --mcp-server-url <url>) [flags]
ork agent vaults credentials update [credential-id] --vault <vault-id> [flags]
ork agent vaults credentials delete [credential-id] --vault <vault-id>
ork agent vaults credentials archive [credential-id] --vault <vault-id>
ork agent vaults credentials validate [credential-id] --vault <vault-id> [flags]

The create command requires exactly one of --auth-json and --mcp-server-url. The latter discovers the MCP server's OAuth authorization server, opens a browser for a public-client PKCE flow, and registers the resulting credential in the vault. update accepts --auth-json without requiring it.

Flag	Default	Description
`--vault`		Parent vault id. Required.
`--display-name`		Credential display name.
`--auth-json`		Credential auth JSON, for example `{"type":"static_bearer","mcp_server_url":"https://example.com/mcp","token":"token"}`. One of two choices on `create`.
`--mcp-server-url`		MCP HTTP endpoint to authorize with OAuth and register. Alternative to `--auth-json` on `create`.
`--oauth-issuer`, `--oauth-client-id`, `--oauth-scope`		Optional issuer, pre-registered public client ID, and scopes for the OAuth flow. Scope is repeatable.
`--callback-address`, `--no-browser`	`127.0.0.1:0`, `false`	Loopback callback listener and browser control. For SSH, forward a fixed callback port and use `--no-browser`.
`--oauth-timeout`, `--no-refresh`	`5m`, `false`	Flow timeout and whether to skip offline access.
`--metadata`		Credential metadata in `key=value` form. Repeatable.
`--output`	`-o` (`text`)	Output format: `text`, `json`, or `yaml`.

The list command also accepts --limit, --page, --include-archived, and --metadata. The validate command runs an MCP OAuth validation against the credential.

ork agent vaults credentials create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --vault vault-github \
  --auth-json '{"type":"static_bearer","mcp_server_url":"https://example.com/mcp","token":"ghp_..."}'

Environments

Manage environments - reusable container templates shared across sessions.

ork agent environments list [flags]
ork agent environments get [environment-id] [flags]
ork agent environments create [flags]
ork agent environments update [environment-id] [flags]
ork agent environments delete [environment-id]
ork agent environments archive [environment-id]

The create and update commands accept:

Flag	Default	Description
`--name`		Environment name.
`--description`		Environment description.
`--scope`		Environment scope: `organization` or `account`. Valid only with `--config-type self_hosted`.
`--config-type`	`cloud`	Environment config type.
`--networking-type`	`unrestricted`	Environment networking type.
`--config`		Additional environment config in `key=value` form. Repeatable.
`--config-json`		Environment config JSON object.
`--package-apt`		apt package to preinstall. Repeatable.
`--package-cargo`		cargo package to preinstall. Repeatable.
`--package-gem`		gem package to preinstall. Repeatable.
`--package-go`		Go package to preinstall. Repeatable.
`--package-npm`		npm package to preinstall. Repeatable.
`--package-pip`		pip package to preinstall. Repeatable.
`--metadata`		Metadata in `key=value` form. Repeatable.
`--provider`		Managed agent provider name (create only).
`--beta-version`		Provider beta version override.
`--output`	`-o` (`text`)	Output format: `text`, `json`, or `yaml`.

self_hosted environments do not accept the --package-* flags.

The --package-* flags declare packages for the environment's container image. The CLI sends them as config.packages.<manager> on the environment payload - they are not StreamNative Cloud artifact packages, and the CLI does not install anything locally. Manage artifact packages with ork packages instead.

ork agent environments create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --name env-prod \
  --config-type cloud \
  --networking-type unrestricted \
  --package-apt git \
  --package-npm typescript \
  --package-pip pytest

Files

Manage files - uploaded assets that sessions can mount as resources. Files are created by uploading a local file with --file.

ork agent files list [flags]
ork agent files get [file-id] [flags]
ork agent files create --file <path> [flags]
ork agent files content [file-id] [flags]
ork agent files delete [file-id]

The create command uploads exactly one regular file:

Flag	Shorthand	Default	Description
`--file`	`-f`		File to upload. Required.
`--provider`			Managed agent provider name.
`--beta-version`			Provider beta version override.
`--content-type`			Uploaded file content type.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

The list command accepts --limit, --page, --include-archived, --metadata, and --provider.

ork agent files create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --file ./report.pdf \
  --content-type application/pdf

Regular uploads are limited to 500 MiB and are not downloadable through ork agent files content; the server returns 403. They remain available to an agent as session resources. Use session files to retrieve agent output files.

ork agent files content

Download raw bytes from a file the server marks downloadable. ork agent files get returns metadata; content returns file bytes. The download alias is equivalent to content.

ork agent files content [file-id] [flags]

Flag	Default	Description
`--output-file`		Write content to a file instead of stdout.

Without --output-file the command streams bytes to stdout, so redirect or pipe binary content rather than printing it to a terminal.

Session output files

Agent outputs are scoped to their session. List, inspect, download, or delete them with the session files group:

ork agent sessions files list --session <session-id> [flags]
ork agent sessions files get [file-id] --session <session-id> [flags]
ork agent sessions files content [file-id] --session <session-id> [flags]
ork agent sessions files delete [file-id] --session <session-id>

list accepts --limit, --after-id, --before-id, and --output; its ID cursors are mutually exclusive. content also accepts --output-file.

ork agent sessions files content file-abc \
  --session sess-123 \
  --output-file ./report.pdf

Skills

Manage skills - filesystem-shaped capability bundles agents load on demand. Create a skill from one .zip bundle, or repeat --file for files under one skill directory that includes SKILL.md.

ork agent skills list [flags]
ork agent skills get [skill-id] [flags]
ork agent skills create --file <path> [flags]
ork agent skills delete [skill-id]

The create command accepts:

Flag	Shorthand	Default	Description
`--file`	`-f`		Skill file to upload. Repeatable for files under one skill directory; otherwise provide one `.zip` bundle.
`--provider`			Managed agent provider name.
`--beta-version`			Provider beta version override.
`--display-title`			Skill display title.
`--content-type`			Uploaded file content type.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

The list command accepts --limit, --page, --include-archived, --metadata, and --provider.

ork agent skills create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --file ./pdf-reader/SKILL.md \
  --file ./pdf-reader/scripts/run.py \
  --display-title "PDF reader"

Skill versions

Manage the versions of a skill.

ork agent skills versions list [skill-id] [flags]
ork agent skills versions get [skill-id] [version-number] [flags]
ork agent skills versions content [skill-id] [version] [flags]
ork agent skills versions create [skill-id] --file <path> [flags]
ork agent skills versions delete [skill-id] [version]

versions list accepts --limit, --page, and --output. versions get accepts --output and requires version-number to be a positive integer. versions content downloads a version bundle and accepts --output-file. versions create accepts a repeatable --file / -f, --beta-version, and --output.

ork agent skills versions create skill-abc \
  --file ./pdf-reader/SKILL.md

Providers

List the managed agent providers registered in the Workspace. Provider names are what you pass to --provider on the create and list commands for agents, memory stores, vaults, environments, files, and skills. The provider alias is equivalent to providers.

ork agent providers list [flags]
ork agent providers get [provider-name] [flags]

Flag	Shorthand	Default	Description
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

Both commands are read-only; providers are registered by a Workspace administrator, not by the CLI.

ork agent providers list \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  -o json

ork agent providers get anthropic

Triggers

Manage agent triggers through the core /v1/triggers API. The trigger alias is equivalent to triggers. Every deployment supports cron; StreamNative Cloud also supports Pulsar and Kafka sources.

ork agent triggers list [flags]
ork agent triggers get [trigger-id] [flags]
ork agent triggers create [flags]
ork agent triggers update [trigger-id] [flags]
ork agent triggers delete [trigger-id]
ork agent triggers pause [trigger-id]
ork agent triggers unpause [trigger-id]
ork agent triggers sessions [trigger-id] [flags]

ork agent triggers list

ork agent triggers list [flags]

Flag	Shorthand	Default	Description
`--limit`		`0`	Maximum number of results to return.
`--page`			Pagination cursor.
`--agent`			Filter by agent ID.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

ork agent triggers create

Create a trigger. You can supply the request body with --config-json or --file, or build it from individual flags. --config-json and --file are mutually exclusive, and either one replaces the individual flags.

ork agent triggers create [flags]

Flag	Shorthand	Default	Description
`--config-json`			Full agent trigger config JSON object.
`--file`	`-f`		Path to a JSON file containing the full agent trigger config.
`--name`			Agent trigger display name.
`--agent`			Agent ID. Required on create. Sent as `agent.id`.
`--agent-version`		`0`	Positive agent version to pin. Omit it to pin the current version.
`--connection`			Workspace connection name. Required for Pulsar and Kafka.
`--source-type`		`pulsar`	Trigger source type: `pulsar`, `kafka`, or `cron`.
`--session-mode`		`SESSION_PER_TOPIC`	`SESSION_PER_EVENT`, `SESSION_PER_TOPIC`, `SESSION_PER_KEY`, or `SHARED`.
`--topic`			Source topic. Repeatable.
`--topic-pattern`			Source topic pattern.
`--subscription-name`			Source subscription name.
`--type-class-name`			Source schema type class name.
`--type-class-definition`			Source schema type class Python definition.
`--type-class-definition-file`			Path to a Python file containing source schema type class definitions.
`--schema-type`			Source schema type, for example `string`, `json`, or `avro`.
`--consumer-config`			Kafka consumer additional config in `key=value` form. Repeatable.
`--input-schema-config`			Kafka input schema config in `topic={json-object}` form. Repeatable.
`--schedule`			Five-field cron schedule. Required for cron.
`--timezone`			IANA cron time zone.
`--payload`			Cron payload. Required for cron.
`--environment-id`			Session environment ID. Required on create.
`--title-template`			Session title template.
`--metadata`			Session metadata in `key=value` form. Repeatable.
`--vault-id`			Session vault id. Repeatable.
`--replicas`		`0`	Agent trigger replicas.
`--paused`		`false`	Create the trigger as paused.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

ork agent triggers create \
  --registry-url "$ORCA_REGISTRY_URL" \
  --access-token "$ORCA_ACCESS_TOKEN" \
  --name nightly-digest \
  --agent "$AGENT_ID" \
  --source-type cron \
  --session-mode SESSION_PER_EVENT \
  --schedule "0 2 * * *" \
  --timezone Etc/UTC \
  --payload "Summarize unresolved tickets." \
  --environment-id "$ENVIRONMENT_ID" \
  -o json

The open-source engine accepts only --source-type cron, --session-mode SESSION_PER_EVENT, and one replica. StreamNative Cloud also accepts Pulsar and Kafka sources, additional session modes, and multiple replicas. The selected deployment validates the combination.

ork agent triggers update

Partially update a trigger by ID. The command sends POST /v1/triggers/{id}; omitted fields keep their current values. The pinned agent cannot be changed, and --paused is create-only. When updating source fields, include --source-type.

ork agent triggers update [trigger-id] [flags]

ork agent triggers update "$TRIGGER_ID" \
  --source-type cron \
  --schedule "30 2 * * *" \
  -o json

ork agent triggers pause, unpause, and delete

Pause future processing, resume it, or delete a trigger. Each takes the trigger ID as a positional argument and renders text output.

ork agent triggers pause [trigger-id]
ork agent triggers unpause [trigger-id]
ork agent triggers delete [trigger-id]

ork agent triggers pause "$TRIGGER_ID"
ork agent triggers unpause "$TRIGGER_ID"

ork agent triggers sessions

List the sessions created by a trigger.

ork agent triggers sessions [trigger-id] [flags]

Flag	Shorthand	Default	Description
`--limit`		`0`	Maximum number of results to return.
`--page`			Pagination cursor.
`--include-archived`		`false`	Include archived sessions.
`--output`	`-o`	`text`	Output format: `text`, `json`, or `yaml`.

ork agent triggers sessions "$TRIGGER_ID" -o json

Agents

Sessions

Agent triggers

ork connections

On this page