The command-line interface and MCP server for Orion — manage workflows, channels, connectors, and data pipelines from your terminal or AI assistant.
Create, test, and deploy workflows. Define channels as service endpoints. Send data through channels. Monitor engine health and metrics. Use as a CLI or as an MCP server for Claude Desktop, Cursor, and other AI tools.
1. Install the CLI:
brew install GoPlasmatic/tap/orion-cli # or: curl installer, cargo install (see Install)2. Point it at your Orion server:
orion-cli config set-server http://localhost:80803. Check the server is running:
orion-cli healthOrion Server v0.1.0
Status: OK
Uptime: 2h 30m
Components:
database OK
engine OK
4. Create a workflow and channel, test it, send data:
# Create a workflow from a JSON file
orion-cli workflows create -f high-value-order.json
# Activate it
orion-cli workflows activate <WORKFLOW_ID>
# Create a channel that links to the workflow
orion-cli channels create -d '{"name":"orders","channel_type":"sync","protocol":"http","workflow_id":"<WORKFLOW_ID>"}'
orion-cli channels activate <CHANNEL_ID>
# Reload the engine to pick up changes
orion-cli engine reload
# Dry-run test with sample data
orion-cli workflows test <WORKFLOW_ID> -d '{"data":{"order_id":"ORD-9182","total":25000}}' --trace
# Send real data through the channel
orion-cli send orders -d '{"order_id":"ORD-9182","total":25000}'| Command | Description |
|---|---|
health |
Check server health and component status |
workflows |
Manage workflows — create, update, delete, test, import/export, diff |
channels |
Manage channels — create, update, delete, activate/archive, versioning |
connectors |
Manage connectors — create, update, delete, enable/disable, circuit breakers |
send |
Send data through channels (sync or async) |
traces |
View and monitor execution traces |
engine |
View engine status and trigger reloads |
metrics |
Retrieve Prometheus metrics |
config |
Configure server URL and defaults |
completions |
Generate shell completions (bash, zsh, fish, powershell) |
mcp |
Start MCP server for AI tool integration |
--server <URL> Orion server URL (overrides config; env: ORION_SERVER_URL)
--output <FORMAT> Output format: table, json, yaml (default: table)
--quiet Suppress output, print only IDs or minimal info
--verbose Show full response bodies and extra details
--no-color Disable colored output (env: NO_COLOR)
--yes Skip confirmation prompts
Full lifecycle management for Orion workflows:
# List workflows with filters
orion-cli workflows list --status active --tag fraud
# Get full workflow details
orion-cli workflows get <ID>
# Create from file or inline JSON
orion-cli workflows create -f workflow.json
orion-cli workflows create -d '{"name":"My Workflow",...}'
# Create with a custom ID
orion-cli workflows create --id my-custom-id -f workflow.json
# Update a workflow (version auto-increments)
orion-cli workflows update <ID> -f updated-workflow.json
# Change workflow status
orion-cli workflows activate <ID>
orion-cli workflows archive <ID>
# Control rollout percentage
orion-cli workflows rollout <ID> -p 50
# Delete (with confirmation prompt)
orion-cli workflows delete <ID>Test any workflow against sample data before activating — with a full execution trace:
orion-cli workflows test <ID> -d '{"data":{"order_id":"ORD-9182","total":25000}}' --traceResult: MATCHED
Trace:
parse executed
flag executed
Output:
{
"order": {
"order_id": "ORD-9182",
"total": 25000,
"flagged": true,
"alert": "High-value order: $25000"
}
}
Supports input from file (-f), inline JSON (-d), or stdin (--stdin).
GitOps-ready workflows for CI/CD pipelines:
# Export workflows (with optional filters)
orion-cli workflows export --status active > workflows.json
# Import workflows from file
orion-cli workflows import -f workflows.json
# Preview import without applying
orion-cli workflows import -f workflows.json --dry-run
# Compare local file against server state
orion-cli workflows diff -f workflows.jsonThe diff command shows color-coded changes: + new, ~ modified, = unchanged, - deleted.
Channels are service endpoints that receive data and route it to workflows:
# List channels
orion-cli channels list --status active --protocol rest
# Create a channel
orion-cli channels create -d '{"name":"orders","channel_type":"sync","protocol":"rest","route_pattern":"/orders/{id}","workflow_id":"process-orders"}'
# Activate / Archive
orion-cli channels activate <ID>
orion-cli channels archive <ID>
# Version management
orion-cli channels versions <ID>
orion-cli channels new-version <ID>Manage named external service configurations with auth and retry policies:
orion-cli connectors list
orion-cli connectors get <ID>
orion-cli connectors create -f connector.json
orion-cli connectors update <ID> -f connector.json
orion-cli connectors delete <ID>
orion-cli connectors enable <ID>
orion-cli connectors disable <ID>
# Circuit breaker management
orion-cli connectors circuit-breakers
orion-cli connectors reset-breaker <KEY>Processing modes for any workload:
orion-cli send orders -d '{"order_id":"ORD-001","amount":150}'# Fire and forget — returns trace_id
orion-cli send orders --async-mode -d '{"amount":100}'
# Submit and wait for completion
orion-cli send orders --async-mode --wait --timeout 30 -d '{"amount":100}'View and monitor execution traces:
# Check trace status
orion-cli traces get <TRACE_ID>
# Poll until complete (with timeout)
orion-cli traces wait <TRACE_ID> --interval 2 --timeout 60Exit codes: 0 completed, 1 failed, 2 timeout.
# View engine status — version, uptime, workflow counts, channels
orion-cli engine status
# Hot-reload workflows and channels (zero downtime)
orion-cli engine reloadOrion includes a built-in MCP (Model Context Protocol) server, enabling AI assistants like Claude Desktop and Cursor to manage your Orion instance directly.
orion-cli mcp serve --server http://localhost:8080orion-cli mcp serve --http --server http://localhost:8080
orion-cli mcp serve --http --bind 0.0.0.0:9090 --server http://localhost:8080Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"orion": {
"command": "orion-cli",
"args": ["mcp", "serve"],
"env": {
"ORION_SERVER_URL": "http://localhost:8080"
}
}
}
}Add to Cursor MCP settings (Settings > MCP Servers):
{
"orion": {
"command": "orion-cli",
"args": ["mcp", "serve"],
"env": {
"ORION_SERVER_URL": "http://localhost:8080"
}
}
}The MCP server exposes 40 tools covering the full Orion API:
| Category | Tools |
|---|---|
| Health | health_check |
| Engine | engine_status, engine_reload |
| Workflows | workflows_list, workflows_get, workflows_create, workflows_update, workflows_delete, workflows_activate, workflows_archive, workflows_test, workflows_validate, workflows_rollout, workflows_versions, workflows_create_version, workflows_export, workflows_import |
| Channels | channels_list, channels_get, channels_create, channels_update, channels_delete, channels_activate, channels_archive, channels_versions, channels_create_version |
| Connectors | connectors_list, connectors_get, connectors_create, connectors_update, connectors_delete, connectors_enable, connectors_disable |
| Circuit Breakers | circuit_breakers_list, circuit_breaker_reset |
| Data | data_send_sync, data_send_async |
| Traces | traces_list, traces_get |
| Metrics | get_metrics |
All commands support three output formats:
orion-cli --output table workflows list # Pretty tables (default)
orion-cli --output json workflows list # JSON for scripting
orion-cli --output yaml workflows list # YAML for config filesUse --quiet for minimal output (just IDs) — ideal for shell scripts:
WF_ID=$(orion-cli --quiet workflows create -f workflow.json)
orion-cli workflows test "$WF_ID" -d '{"data":{"amount":100}}'Configuration is stored in ~/.orion/config.toml:
server_url = "http://localhost:8080"
default_output = "table"orion-cli config set-server http://localhost:8080
orion-cli config set default_output json
orion-cli config showPrecedence (highest to lowest):
- Command-line flags (
--server,--output) - Environment variables (
ORION_SERVER_URL,NO_COLOR) - Config file (
~/.orion/config.toml)
# Bash
orion-cli completions bash > ~/.bash_completions/orion-cli
# Zsh
orion-cli completions zsh > ~/.zfunctions/_orion-cli
# Fish
orion-cli completions fish > ~/.config/fish/completions/orion-cli.fish# Docker (MCP server mode)
docker run -p 8081:8081 ghcr.io/goplasmatic/orion-cli:latest mcp serve --http
# macOS (Homebrew)
brew install GoPlasmatic/tap/orion-cli
# macOS / Linux (shell installer)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/GoPlasmatic/Orion-cli/releases/latest/download/orion-cli-installer.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://github.com/GoPlasmatic/Orion-cli/releases/latest/download/orion-cli-installer.ps1 | iex"
# From crates.io
cargo install orion-cli
# From source
cargo install --git https://github.com/GoPlasmatic/Orion-cli.gitVerify with orion-cli --version. Requires Rust 1.85+ for source builds.
- Orion Server — The services runtime platform
- API Reference — Full REST API documentation
- Connectors Guide — Auth schemes, retry policies, and secrets
- Production Features — Custom IDs, versioning, fault tolerance
- Use Cases & Patterns — Real-world examples and AI prompt templates
- Observability — Prometheus metrics, health checks, logging
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
cargo build # Build
cargo test # Run tests
cargo clippy # Lint
cargo fmt # FormatApache-2.0 — see LICENSE for details.