CLI

The Olyx CLI runs where your application and provider credentials already live. Olyx Cloud remains the control plane for project configuration, policy, usage, and replay coordination.

This means your provider secrets do not need to be stored by Olyx.

Distribution Model

The CLI is a stateless thin client. OLYX_BASE_URL is the only configuration difference between deployments — point it at Olyx Cloud for SaaS, or at an olyx-edge node for enterprise. Every CLI command works identically in both cases.

Across cloud and enterprise deployments, provider secrets remain customer-side. olyx-edge applies guardrails, rate limiting, and policy enforcement before forwarding to the model provider. olyx-core cryptographically verifies that the edge node is running a signed, unexpired policy pack.

For cloud deployments, Olyx Cloud may retain public or anonymized telemetry according to project policy. For Enterprise private deployments, Olyx Cloud does not store private payloads unless the deployment is explicitly configured to allow that boundary.

What The CLI Does

The CLI is a local client for Olyx projects. It can:

• discover your project’s distribution mode
• create traces
• attach local opaque trace references
• queue replays
• run inspect checks for API key and endpoint configuration

The CLI does not collect provider API keys, private model tokens, prompts, completions, or tool payload bodies unless your project mode explicitly allows cloud payload storage.

Install

CLI binaries are distributed through GitHub Releases or the access channel attached to your Olyx workspace. The command name is:

Package manager availability

olyx

Supported platforms

Linux binaries are compiled against musl libc and are fully static. They run on any Linux kernel 3.2 or later with no glibc, no OpenSSL, and no other packages required — including Alpine, distroless images, and minimal containers.

Verify the archive checksum before installing. Release artifacts also include a Sigstore bundle for provenance verification.

Recommended install on Linux:

version="v0.1.0"
asset="olyx-${version}-x86_64-unknown-linux-musl.tar.gz"
curl -fsSLO "https://github.com/Olyx-labs/Olyx-CLI/releases/download/${version}/${asset}"
curl -fsSLO "https://github.com/Olyx-labs/Olyx-CLI/releases/download/${version}/${asset}.sha256"
sha256sum -c "${asset}.sha256"
tar -xzf "${asset}"
sudo install -m 0755 "olyx-${version}-x86_64-unknown-linux-musl/olyx" /usr/local/bin/olyx
olyx --version

On Windows (PowerShell):

$version = "v0.1.0"
$asset = "olyx-$version-x86_64-pc-windows-msvc.zip"
Invoke-WebRequest -Uri "https://github.com/Olyx-labs/Olyx-CLI/releases/download/$version/$asset" -OutFile $asset
Invoke-WebRequest -Uri "https://github.com/Olyx-labs/Olyx-CLI/releases/download/$version/$asset.sha256" -OutFile "$asset.sha256"
(Get-FileHash $asset -Algorithm SHA256).Hash.ToLower() + "  " + $asset |
  Compare-Object (Get-Content "$asset.sha256")
Expand-Archive $asset -DestinationPath .
Move-Item "olyx-$version-x86_64-pc-windows-msvc\olyx.exe" "$env:LOCALAPPDATA\Microsoft\WindowsApps\olyx.exe"
olyx --version

If your deployment verifies release provenance, validate the Sigstore bundle before moving the binary into a production image.

On Windows, add the directory containing olyx.exe to your PATH so the olyx command is available in any terminal session.

Prerequisites

Before running the CLI against Olyx Cloud, have:

The CLI binary itself has no runtime dependencies. No additional packages, libraries, or runtimes are required on any supported platform before running olyx.

Use a separate Olyx key for each environment:

export OLYX_API_KEY=ak_staging_...   # macOS / Linux
olyx config

$env:OLYX_API_KEY = "ak_staging_..." # Windows PowerShell
olyx config

For production services, keep the API key in your secret manager and inject it as an environment variable at runtime.

Configure

Use a project-scoped Olyx API key.

macOS / Linux:

export OLYX_API_KEY=ak_...
export OLYX_BASE_URL=https://app.olyxai.io

Windows (PowerShell):

$env:OLYX_API_KEY = "ak_..."
$env:OLYX_BASE_URL = "https://app.olyxai.io"

For local development, point OLYX_BASE_URL at your local runtime:

export OLYX_BASE_URL=http://localhost:XXXX        # macOS / Linux
$env:OLYX_BASE_URL = "http://localhost:XXXX"      # Windows PowerShell

Provider keys stay in your own runtime environment:

export PROVIDER_API_KEY=your_key...   # macOS / Linux

$env:PROVIDER_API_KEY = "your_key..."  # Windows PowerShell

Olyx does not need those provider secrets.

Environment Variables

Configuration precedence is:

1. command flags
2. environment variables
3. CLI defaults

This keeps local tests explicit while allowing production services to use injected environment configuration.

Check Your Mode

olyx config

The response includes the active distribution contract:

{
  "offline_testing": false,
  "enterprise_compute": {
    "enabled": false,
    "mode": "standard",
    "compute_backend": "ruby",
    "accelerated_primitives": [],
    "runtime_boundary": "olyx_cloud"
  },
  "guardrails": {
    "max_input_length": 10000,
    "pii_threshold": 0.7,
    "injection_block": true,
    "secret_action": "alert"
  },
  "runtime_failover": {
    "preferred_runtime": "cloud",
    "fallback_order": ["cloud"],
    "edge_fallback": {
      "enabled": false,
      "targets": [],
      "fail_closed": false
    },
    "cloud_fallback": {
      "enabled": true,
      "mode": "cloud-primary",
      "requires_redaction": false,
      "require_customer_kms": false,
      "require_admin_approval": false,
      "raw_payloads_allowed": true,
      "provider_secrets_allowed": false
    },
    "data_boundary": "olyx_cloud",
    "fail_closed": false
  },
  "distribution": {
    "project_id": 123,
    "distribution_channel": "cli",
    "telemetry_mode": "anonymized",
    "payload_storage_mode": "cloud_anonymized",
    "payload_retained": true,
    "replay_execution_mode": "cloud",
    "secrets_boundary": "customer_environment",
    "cloud_payloads": true,
    "local_ref_required": false
  },
  "runtime_activation": {
    "url": "/api/v1/runtime/activation",
    "signature_algorithm": "EdDSA",
    "envelope_format": "jws_compact_json",
    "public_key_distribution": "response_keyring"
  }
}

Reading The Config Response

Treat the config response as the source of truth for public client behavior.

The CLI should fail closed if it receives an unknown mode:

Unknown telemetry mode: customer_side
Upgrade the CLI or contact Olyx support.

Create A Trace

olyx trace --metadata '{"source":"cli","feature":"support"}'

Use a trace to mark a unit of model work. A trace can represent a single prompt, a tool-using agent turn, a batch item, or a replayable application request. Keep the trace small and attach only metadata that is safe for Olyx Cloud under the current project policy.

Equivalent HTTP call:

curl "$OLYX_BASE_URL/api/v1/traces" \
  -H "Authorization: Bearer $OLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "source": "olyx-cli",
      "feature": "support"
    }
  }'

Example response:

{
  "id": "trace_01J6AF...",
  "status": "pending",
  "created_at": "2026-06-03T14:12:09Z",
  "metadata": {
    "source": "olyx-cli",
    "feature": "support"
  },
  "revenue": null,
  "distribution": {
    "distribution_channel": "cli",
    "telemetry_mode": "anonymized",
    "payload_storage_mode": "cloud_anonymized",
    "payload_retained": true,
    "replay_execution_mode": "cloud",
    "local_ref": null
  }
}

For modes that require customer-side storage, send an opaque local reference:

olyx trace \
  --metadata '{"source":"cli","feature":"support"}' \
  --local-ref opaque:trace_01HR7...

The local_ref should be meaningful only inside your environment. It can point to a local trace store, database row, or object-storage key, but Olyx Cloud should not need to understand it.

For production workloads, make the local reference stable enough for your own replay system:

postgres://ai_traces/01J2Z9F7
s3://customer-replay-store/prod/2026/06/trace_01J2Z9F7.json
internal-run:checkout-worker:01J2Z9F7

Do not include provider keys, raw prompts, completions, customer emails, or access tokens in local_ref.

Metadata Guidelines

Use metadata for routing, grouping, and later filtering. Avoid raw prompts, completions, provider keys, customer emails, access tokens, or large payload bodies.

Good metadata:

{
  "source": "checkout-worker",
  "environment": "staging",
  "feature": "refund-assistant",
  "request_type": "tool_call"
}

Metadata to avoid:

{
  "customer_email": "person@example.com",
  "prompt": "Full end-user prompt...",
  "provider_api_key": "your-key..."
}

Replay

olyx replay trace_01J6AF...

Replay queues comparison work for a completed trace. In public cloud modes, replay uses retained or anonymized trace data according to project policy. If the project does not retain enough payload data for cloud replay, the command should fail clearly instead of inventing a partial replay.

Equivalent HTTP call:

curl "$OLYX_BASE_URL/api/v1/replay" \
  -H "Authorization: Bearer $OLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "trace_id": "trace_01J6AF..." }'

Replay behavior depends on the project mode:

For Enterprise private deployments, replay runs inside the customer environment through olyx-edge (agent_local mode). Olyx Cloud may still coordinate replay state, but it does not need provider secrets or private payloads unless the deployment is explicitly configured to retain them in cloud.

Poll A Replay Job

curl "$OLYX_BASE_URL/api/v1/replay/job_01J6AG..." \
  -H "Authorization: Bearer $OLYX_API_KEY"

Replay jobs are asynchronous. A client should poll with backoff and stop after a terminal status:

Suggested shell pattern:

job_id=$(olyx replay trace_01J6AF... --json | jq -r '.job_id')

for delay in 1 1 2 2 5 5; do
  olyx replay "$job_id" --json
  sleep "$delay"
done

Inspect

olyx inspect

Use inspect to confirm the CLI sees a base URL, API key, and private-runtime environment variables. It does not inspect provider secrets.

Example output:

{
  "base_url": "https://app.olyxai.io",
  "api_key_present": true,
  "dry_run": false,
  "secrets_boundary": "customer_environment",
  "core_runtime": {
    "license_path_present": false,
    "policy_pack_path_present": false,
    "key_id_present": false,
    "public_key_present": false
  }
}

Common failures:

Command Reference

Exit Codes

Automation should treat non-zero exit codes as failed steps and capture stderr for troubleshooting.

Security Boundary

The CLI route is designed around one rule:

Provider secrets stay in your environment. Olyx receives only what your project policy allows.

For cloud deployments, Olyx Cloud may retain public or anonymized telemetry according to project policy. For enterprise deployments, olyx-edge runs inside your infrastructure — provider credentials, prompts, and model responses never leave your network unless your policy explicitly configures cloud sync via OLYX_CLOUD_SYNC_URL. The edge operates fully air-gapped by default.

What Not To Send

Avoid sending these values through metadata, local references, or error messages: