CLI
Install and use the Xybrid command-line interface
The xybrid CLI runs models and pipelines from the terminal — the fastest way to try a model before integrating an SDK.
Installation
Install script (recommended)
# macOS / Linux
curl -sSL https://raw.githubusercontent.com/xybrid-ai/xybrid/master/install.sh | sh# Windows (PowerShell)
irm https://raw.githubusercontent.com/xybrid-ai/xybrid/master/install.ps1 | iexThe script detects your platform and installs the latest release binary.
Pre-built binaries
Download binaries for macOS (arm64), Linux (x86_64), and Windows (x86_64) from GitHub Releases.
From source
cargo install --git https://github.com/xybrid-ai/xybrid xybrid-cli --features platform-macosReplace platform-macos with platform-desktop on Linux/Windows.
Verify
xybrid --help
xybrid models listCommands
| Command | Purpose |
|---|---|
xybrid run | Run a model or pipeline (text, audio, LLM) |
xybrid repl | Interactive chat that keeps the model loaded, with tool calling (--stream, --system, --tools-file) |
xybrid models | Browse the registry: list, search <query>, info <id>, voices <id> |
xybrid fetch | Pre-download models to the local cache |
xybrid cache | Manage the local cache: list, status, clear [id] |
xybrid prepare | Parse and validate a pipeline YAML |
xybrid plan | Show the execution plan: models, targets, download status |
xybrid trace | Analyze an explicitly exported OTLP/JSON trace |
xybrid init | Generate model_metadata.json for a model directory |
xybrid pack | Create a .xyb bundle from a model directory |
xybrid bundle | Fetch a registry model and produce a .xyb bundle |
xybrid telemetry | Manage registry telemetry settings |
xybrid connect | Connect a project to a claimable Xybrid workspace and save its key, with no sign-up |
xybrid auth | Inspect, recover or forget the project's saved credentials: status, claim, logout |
Common workflows
# Text-to-speech
xybrid run --model kokoro-82m --input-text "Hello from Xybrid!" -o hello.wav
# Speech-to-text
xybrid run --model whisper-tiny-ggml --input-audio recording.wav
# Chat with a local LLM (streaming)
xybrid repl --model qwen2.5-0.5b-instruct --stream
# Run a GGUF straight from HuggingFace
xybrid run --huggingface bartowski/google_gemma-3-1b-it-GGUF --input-text "Hi!"
# Pre-download for offline use
xybrid fetch --model kokoro-82mGlobal flags
| Flag | Environment variable | Description |
|---|---|---|
--api-key | XYBRID_API_KEY | Cloud API key; does not enable observability by itself. When neither is set, the key saved by xybrid connect is used |
--platform-url | XYBRID_PLATFORM_URL | Cloud gateway URL (default https://api.xybrid.dev) |
--observability | — | Opt into Xybrid trace export; requires an API key |
--traces-endpoint | — | Full trace URL for --observability (default https://ingest.xybrid.dev/v1/traces) |
--device-id | XYBRID_DEVICE_ID | Stable device identifier for telemetry |
-v, -vv | — | Verbose output (-vv includes library logs) |
-q | — | Quiet mode (errors only) |
For a Collector, configure OTEL_EXPORTER_OTLP_ENDPOINT or per-signal
OTEL_EXPORTER_OTLP_*_ENDPOINT variables. This enables export independently of
cloud authentication. OTEL_SDK_DISABLED=true disables export in either mode.
The CLI flushes and shuts down its exporter when the command ends.
Enabled observability captures prompts and outputs by default. Set
OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT=no_content for metadata only.
See API keys for key scopes and what gets exported.