CLI Reference — orqestractl

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

orqestractl is the Orqestra CLI for core control-plane workflows. It covers workloads, assets, flows, releases, executions, templates, namespaces, triggers, plugins, and model catalog browsing. It does not yet replace every portal surface, so use the API or portal where a workflow is not exposed in the CLI.

Installation

In this repository, the fastest local path is:

cd packages/orqestra-cli
uv sync
uv run orqestractl --help

If you install the package into another environment, the command name is still orqestractl.

Authentication

Configure the API endpoint and credentials:

# Via flags
orqestractl --api-url http://localhost:8000 --api-key $ORQESTRA_API_KEY workload list
 
# Via environment variables
export ORQESTRA_API_URL=http://localhost:8000
export ORQESTRA_API_KEY=your-api-key
orqestractl workload list

Output Formats

The global --format flag must appear before the command group:

orqestractl workload list
orqestractl --format json workload list
orqestractl --format yaml release get <release_id>

Command Groups

workload — Manage workloads

asset — Manage governed assets

flow — Manage orchestration flows

release — Manage releases

review_ready -> approved requires at least one approval record, and approved -> active requires a policy_bundle binding plus an approved model_policy binding when the release’s flow uses provider-routed steps such as llm_call, agent, or embedding.

audit — Verify governance audit integrity

orqestractl audit verify reads Postgres directly through ORQESTRA_POSTGRES_DSN_DIRECT when configured. It is an integrity verifier, not an audit search interface.

Capability approval uses the authenticated control-plane API, not the direct database connection. It requires the platform governance.worm_export.manage permission, four explicit inputs (--jurisdiction, --mapping-version, --source-ref, and --authority-ref), and an interactive confirmation. Repeat --jurisdiction once per organization jurisdiction one destination serves. The returned bucket, region, retention, approver, and observation timestamps come from the server’s provider observation.

orqestractl audit worm-capability approve \
  --jurisdiction EU \
  --jurisdiction CH \
  --mapping-version region-map-v4 \
  --source-ref contract:approved-region-map \
  --authority-ref approval:platform-change-42

model policy — Manage governed model policies

orqestractl model policy create and orqestractl model policy create-version print an advisory supplier-assurance report after the API body. The report is not certification. For json and yaml, the API body stays on stdout and the report is on stderr.

evaluation — Manage advisory evaluation sessions

evaluation sessions are not release-gate evidence. Returned outcomes keep gate_eligible=false; the command group does not publish winners, create asset versions, bind releases, approve releases, or activate releases. Use release evaluate for release-gate evidence.

--judge-mode llm_judge and assistant-generated candidates are Enterprise-gated by the control plane. Deterministic manual or imported candidate runs are the Community path.

A --candidate-json with "source":"assistant_generated" requires an idempotency key. Omit --idempotency-key and the CLI mints one and prints it to stderr (idempotency-key: <key>) before dispatching — never stdout. If the command times out or reports the submission is still resolving, re-run the identical command with --idempotency-key <that printed key> to safely replay the outcome; minting a new key instead submits a new request and can create a duplicate candidate. See Worked Examples below.

identity-tenant — Manage trusted Entra tenants

Per organization. Registering a tenant binds its issuer permanently; a tenant can be disabled and re-enabled but never deleted, because historical actors, audit records and group mappings reference it.

organization — Create organizations and administer policy

Organization creation and bootstrap require a JSON file containing an explicit initial policy commitment. Policy updates require the version currently shown by policy get; a stale version returns a conflict and is never retried automatically. History is newest-first and uses the exclusive --before-version cursor.

orqestractl organization create --slug acme --display-name "Acme Corp" \
  --initial-policy-file initial-policy.json
orqestractl organization bootstrap --org-name "Acme Corp" --org-slug acme \
  --initial-policy-file initial-policy.json
orqestractl organization policy get <org_id>
orqestractl organization policy history <org_id> --limit 25 --before-version 8
orqestractl organization policy update <org_id> --expected-version 8 \
  --policy-file approved-replacement.json

The policy file must include all four retention durations, jurisdiction, retention mode and backend, backend maximum, source kind/reference, and authority reference. COMPLIANCE mode additionally requires the exact irreversible acknowledgement in compliance_acknowledgement. The CLI has no policy defaults.

namespace settings — Manage tenant settings

Per organization, addressed through any of its namespaces. These are the audited runtime switches for notifications, advanced notifications and SCIM; they replace the deploy-time ORQESTRA_EXPERIMENTAL_FEATURES keys, so a change applies to the next request with no redeploy. Notifications default on; advanced notifications and SCIM default off. Changing them needs namespace.manage; in a single-issuer deployment SCIM is platform-wide and needs platform administration.

The same switches are in the portal under Administer › Access & org › Tenant settings. A feature that is off answers 403 enterprise_capability_required, and its capability_slug names the setting to turn on.

scim-credential — Manage SCIM provisioning credentials

Scoped to one organization and one registered tenant, and confined to /scim/v2. The plaintext secret is printed once, on issue, and cannot be retrieved afterwards. At most two credentials are active per tenant, so rotation is: issue the replacement, update the customer’s SCIM app, then revoke the old one.

execution — Inspect governed runs

The CLI exposes pause, resume, and snapshot operations. Rerun, replay, and trigger backfill are currently API surfaces; see Execution Recovery & Control.

execution hermes-evidence is read-only. It lists hermes_execution_normalization artifacts from launched Hermes runs and keeps the claim language bounded to controlled launch: governance_claim=launched_through_orqestra and capability_mediation=not_claimed.

hermes-runtime — Register Hermes runtimes

Hermes runtime registration is inventory/passive-evidence only. Launched Hermes runs are surfaced through execution evidence; the CLI does not claim tool-call mediation or certified runtime governance for Hermes.

external-runtime-certification — Inspect and manage runtime certification posture

This surface is separate from plugin package installs. Connector/tool posture and external-runtime certification are different governance domains; package install commands manage workspace availability for cataloged plugin assets.

The list and state-history commands need EXTERNAL_AI_READ; revoke, revoke-by-runtime, and revoke-by-signing-key are governed mutations that need EXTERNAL_AI_MANAGE and each transition emits a canonical governance audit row. Revocation is terminal and idempotent — revoking an already-revoked certification returns it unchanged.

external-runtime-run-evidence-summary — Inspect run-evidence posture

Read-only, EXTERNAL_AI_READ-gated. This is the run-summary half of the external-runtime read surface (the certification axes are exposed by external-runtime-certification above); the current (latest-reconciliation) row per execution is returned. The governance_claim_label / gap_reasons projection is resolved server-side from the caller’s workspace permissions — holding EXTERNAL_AI_MANAGE additionally promotes the view to the exact gap detail, otherwise the safe posture summary only. The same projection covers the response’s sovereignty_gap and capability_evidence fields (sovereignty_closure_status is coarse posture and always visible). --gap-reason, --capability-kind, --capability-reconciliation-status, --capability-evidence-completeness, and --capability-proof-strength are operator-only filters: a consumer-tier caller (EXTERNAL_AI_READ without EXTERNAL_AI_MANAGE) supplying any of them is denied (403), never a silently narrowed result — they would otherwise let a consumer reconstruct withheld gap/evidence detail one filter value at a time.

external-runtime-profile — Inspect external-runtime profile posture

Read-only, EXTERNAL_AI_READ-gated. Returns profile identity + posture only (engine, conformance_level, mediated_capabilities, …); internal contract detail (workflow digest contract, capability gateways, declared config, …) is never included. A profile record carries no governance-claim label, so there is no role-based projection here.

mcp-tool-schema — Inspect MCP tool-schema governance

Read-only, asset.view-gated. There is deliberately no approve or revoke here: authorizing a tool inventory is an operator decision that the portal presents with a confirmation restating target, version, snapshot, tool count and reason, and that carries a fresh idempotency key per action. A one-line CLI approve would have neither.

snapshots, approvals, and observations all accept --limit/--offset to page through a long history rather than always returning the server’s default first page.

observations --execution-id <id> reads a different, execution-scoped route than --asset-id/--state (the workspace-wide list); combining --execution-id with either of those is rejected rather than silently dropping the asset/state filter.

Approval history is returned unfiltered — revoked and superseded entries are what the history exists to show. Observations carry identifiers, closed reasons, digests and timestamps only; never provider content, arguments, headers, credentials or authority subjects.

template — Preview and apply templates

asset — Manage governed assets (extended)

The asset group now includes a blast-radius command:

All previously documented asset commands remain unchanged.

policy — Governance policy operations

Runtime permission grants are created through policy exceptions create with --profile-ref, --capability-kind, and repeatable --authorized-target. Approved active grants are still expiry-bound policy exception records.

runtime-permission-profile — Inspect runtime grant profiles

permission-evidence — Read permission decision records

Each page contains at most 100 records. The command reports recorded outcomes, reason codes, revisions, freshness, lineage, and acknowledgement state. An empty page means no evidence was recorded; it does not establish that an operation was never attempted.

guardrail, plugin, model, tenant, and trigger

plugin install materializes package-local assets into a workspace scope; plugin update adopts a newer package version into the same scope without mutating the already-installed version. plugin disable, plugin enable, and plugin remove change an install by install id, not by global slug — disable/enable toggle plugin_install.state, remove permanently supersedes the install. plugin resolve reads whether a package ref is installed and runtime-available without raising; plugin bind re-resolves the ref fail-closed and then binds it to a release role in one step. plugin validate checks an author’s orqestra.plugin.yaml manifest locally with no API calls. tool-permission set grants a workload access to a connector and takes a --justification that the API requires when the connector is restricted or destructive. See the Plugins & Connectors guide for the posture model, and Resolving And Binding Installed Assets for the package-ref grammar.

capability — Query capability status

sync — GitOps directory sync

For apply and reconcile, the CLI preflights the complete ordered mutation plan exactly once before its first write. A denied, unavailable, or malformed preflight stops the run with no domain changes. There is no automatic retry or fallback to an older server. An allow is advisory; each writer authorizes again against current state.

orqestractl sync is a command group: validate (local parse/validate, no API calls — full schema for the package layout, structural checks for the split-file layout), preview (dry-run diff against live state), apply, and reconcile (idempotent convergence for CI/CD loops):

orqestractl sync validate --dir ./orqestra-resources
orqestractl sync preview --dir ./orqestra-resources
orqestractl sync apply --dir ./orqestra-resources
orqestractl sync reconcile --dir ./orqestra-resources

The sync directory is a workload bundle with workload.yaml, release.<env>.yaml, one-file resources under resources/, and one-file flows under flows/. Connection definition and local instance settings live in the same kind: connector_definition resource file.

Source manifests do not carry version labels. Sync compares resource and flow content by canonical JSON hash, reuses an identical live version when one exists, and creates a new immutable version when content changes. Release manifests bind by slug only; sync resolves those slugs to the versions created or reused in the same run.

Release approvals are explicit CLI actions. After moving a release to review_ready, use orqestractl release approve <release-id> from a different authorized actor before transitioning to approved. Sync itself never approves or activates. Preview, apply, and reconcile report the observed serving identity separately from package reconciliation, so a matching inactive candidate cannot be read as “already serving”.

run — Execute a released workload

run executes a workload you have released, addressing it by slug and passing a single query input. Add --interactive to stream execution events instead of waiting for the completed result; both modes execute the same workload.

orqestractl run playground-knowledge-assistant --query "What is Orqestra?"

It does not yet provide a generic “run any flow with arbitrary inputs” surface.

This is not the workspace’s built-in knowledge assistant, which resolves its own managed workload server-side and is reached with:

orqestractl knowledge query "What is Orqestra?" --workspace-id <workspace-id>

Worked Examples

Generate and validate a flow

orqestractl flow generate \
  --description "Summarize uploaded documents and email the summary every Monday" \
  --output generated-flow.yaml
 
orqestractl flow validate --file generated-flow.yaml
orqestractl flow create --slug weekly-summary --owner team:ops --file generated-flow.yaml

Preview a GitOps sync

orqestractl sync validate --dir ./orqestra-resources
orqestractl sync preview --dir ./orqestra-resources
orqestractl sync apply --dir ./orqestra-resources

Query a seeded knowledge workload

orqestractl run playground-knowledge-assistant --query "How does Orqestra handle approvals?"

Generate an evaluation candidate with the assistant

Enterprise-gated; requires the evaluation-assistant-candidates runtime capability. The CLI mints an idempotency key and prints it to stderr:

orqestractl evaluation create \
  --subject-kind asset_candidate \
  --subject-ref summarizer-prompt \
  --candidate-json '{"source":"assistant_generated","asset_kind":"prompt_template","generation_brief":"Draft a concise, neutral-tone summarizer prompt."}'
# stderr: idempotency-key: 3f9a2c1e8b7d4a6f9c0e1d2b3a4f5c6d
# stdout: {"session_id": "...", "candidates": [{"candidate_id": "...", "content": {...}, ...}]}

If that command fails with a timeout or a “still resolving” error, it names the same key in its error message — re-run the identical command with that key to safely resolve it, rather than retrying with a new one:

orqestractl evaluation create \
  --subject-kind asset_candidate \
  --subject-ref summarizer-prompt \
  --candidate-json '{"source":"assistant_generated","asset_kind":"prompt_template","generation_brief":"Draft a concise, neutral-tone summarizer prompt."}' \
  --idempotency-key 3f9a2c1e8b7d4a6f9c0e1d2b3a4f5c6d

setup — owner-run demo convergence and readiness

orqestractl setup accepts a non-secret, pinned owner input and a locally available workload bundle. It validates the complete input and source/profile hashes before reading protected descriptors or contacting the API. It then reuses exact public readbacks or advances through the owner, approver, pricing, provider, install, lane, policy, release, assistant, and journey phases. A partial phase is reported without destructive rollback; rerun only after reviewing the reported IDs and correcting the cause.

The input is strict JSON with exactly these fields. Values below are synthetic examples, not reusable credentials or live estate identifiers:

{
  "target_url": "https://control.example.invalid",
  "tenancy": {
    "org_slug": "demo-org",
    "org_name": "Demo Organization",
    "namespace_slug": "demo-namespace",
    "namespace_name": "Demo Namespace",
    "workspace_slug": "demo-workspace",
    "workspace_name": "Demo Workspace"
  },
  "identities": {
    "owner_ref": "user:demo-owner",
    "approver_ref": "user:demo-approver",
    "idp_user_refs": []
  },
  "auth_fds": { "owner": 3, "approver": 4, "pricing_admin": 5 },
  "environment": "dev",
  "provider": {
    "type": "your-configured-provider",
    "slug": "demo-provider",
    "endpoint": "https://provider.example.invalid/v1",
    "credential_ref": "demo-provider-key"
  },
  "models": [
    {
      "canonical_id": "provider/model",
      "role": "assistant",
      "display_name": "Example model",
      "context_window": 8192,
      "max_output_tokens": 2048,
      "input_usd_per_token": "0.000001",
      "output_usd_per_token": "0.000002"
    }
  ],
  "pricing_change_reason": "Owner-approved demo setup",
  "app": {
    "bundle_dir": "./demo-bundle",
    "source_bundle_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "resolution_profile": "resolution.json",
    "resolution_profile_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "workload_slug": "demo-workload",
    "release_slug": "demo-release",
    "model_policy_slug": "demo-policy"
  },
  "installs": [],
  "lane": { "name": "standard", "reason": "Owner-approved demo lane" },
  "secrets": [{ "name": "provider-key", "keychain_item": "demo-provider-key" }],
  "assistant_enabled": true,
  "content_inputs": [],
  "exclusive_setup": true,
  "timeout_seconds": 300,
  "journey_proof": {
    "evidence_ids": ["11111111-1111-4111-8111-111111111111"],
    "max_age_seconds": 900
  }
}

Protected role values are read from the listed file descriptors; secret values may instead use an explicit keychain item. Never place bearer tokens, provider keys, callback tokens, or secret values in the JSON, command line, environment, bundle, or logs. For a read-only check, provide only the owner descriptor in auth_fds and run:

orqestractl setup --input ./owner-setup.json --check

The check path is GET-only and does not read approver, pricing, provider-secret, or IdP credentials. A successful resource/readiness readback still does not prove app-owned authenticated callback continuity: until the running app supplies that proof, callback continuity stays unverified. Exit codes: 0 ready (the supplied journey evidence verified), 3 converged (everything converged, journey_proof.evidence_ids empty so end-user journey proof is pending; rerun with the execution IDs), 2 blocked or failed. This workflow is not certification.

Practical Notes

• The CLI uses workload IDs (workload_id) and asset version IDs directly. For non-trivial release wiring, --format json plus jq, or the portal/API, is often the fastest way to collect IDs.
• The release lifecycle states are draft -> review_ready -> approved -> active with automatic active -> superseded behavior when a new release is activated.
• Use the GitOps guide for declarative sync patterns and the AI Flow Generation guide for generation details.