# UXC
**Universal X-Protocol CLI**
[](https://github.com/holon-run/uxc/actions)
[](https://github.com/holon-run/uxc/actions/workflows/coverage.yml)
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org)
UXC is a universal X-protocol CLI that lets you discover and invoke OpenAPI, gRPC, GraphQL,
MCP, and JSON-RPC interfaces directly from a URL.
It turns remote schema-exposed interfaces into executable command-line operations without SDKs,
code generation, or endpoint pre-registration.
## What Is UXC
Modern services increasingly expose machine-readable interface metadata.
UXC treats those schemas as runtime execution contracts:
- Discover operations from a host
- Inspect operation inputs/outputs
- Execute operations with structured input
- Return deterministic JSON envelopes by default
If a target can describe itself, UXC can usually call it.
## Why It Exists
Teams and agents often need to interact with many protocol styles:
OpenAPI, GraphQL, gRPC, MCP, and JSON-RPC.
Traditional workflows create repeated overhead:
- language-specific SDK setup
- generated clients that drift from server reality
- one-off wrappers for each endpoint
- large embedded tool schemas in agent prompts
UXC provides one URL-first CLI contract across protocols.
## Why UXC Works Well With Skills
UXC is a practical fit for skill-based agents:
- On-demand discovery and invocation, without preloading large MCP tool definitions into prompt context
- Portable by endpoint URL and auth binding, not tied to per-user local MCP server names
- Reusable as one shared calling interface across many skills
## Core Capabilities
- URL-first usage: call endpoints directly, no server alias required
- Multi-protocol detection and adapter routing
- Schema-driven operation discovery (`<host> -h`, `<host> <operation_id> -h`)
- Structured invocation (positional JSON, key-value args)
- Deterministic JSON envelopes for automation and agents
- Auth model with reusable credentials and endpoint bindings
- Host shortcut commands via `uxc link`
- Link-level default OpenAPI schema persistence via `uxc link --schema-url`
Supported protocols:
- OpenAPI / Swagger
- gRPC (server reflection)
- GraphQL (introspection)
- MCP (HTTP and stdio)
- JSON-RPC (OpenRPC-based discovery)
## Architecture Snapshot
UXC keeps protocol diversity behind one execution contract:
```mermaid
flowchart LR
A[User / Skill / Agent] --> B[UXC CLI]
B --> C[Command Router]
C --> D[Protocol Detector]
D --> E[Adapter Layer]
E --> E1[OpenAPI Adapter]
E --> E2[gRPC Adapter]
E --> E3[GraphQL Adapter]
E --> E4[MCP Adapter]
E --> E5[JSON-RPC Adapter]
C --> F[Auth Resolver]
F --> F1[Credential Sources<br/>literal / env / 1Password]
C --> G[Schema + Response Cache]
C --> H[JSON Envelope Output]
E1 --> R[Remote Endpoints]
E2 --> R
E3 --> R
E5 --> R
E4 --> M1[MCP HTTP Endpoint]
E4 --> M2[MCP stdio via Daemon]
M2 --> D1[Daemon Process Registry]
D1 --> D2[Reused stdio MCP Process]
```
This design keeps invocation UX stable while allowing protocol-specific internals.
## Target Use Cases
- AI agents and skills that need deterministic remote tool execution
- CI/CD and automation jobs that need schema-driven calls without SDK setup
- Cross-protocol integration testing with one command contract
- Controlled runtime environments where JSON envelopes and predictable errors matter
## Non-Goals
UXC is not:
- a code generator
- an SDK framework
- an API gateway or reverse proxy
UXC is an execution interface for schema-exposed remote capabilities.
## Install
### Homebrew (macOS/Linux)
```bash
brew tap holon-run/homebrew-tap
brew install uxc
```
### Install Script (macOS/Linux)
```bash
Review before running:
```bash
curl -fsSL https://raw.githubusercontent.com/holon-run/uxc/main/scripts/install.sh -o install-uxc.sh
less install-uxc.sh
bash install-uxc.sh
```
Install a specific version:
```bash
Windows note: native Windows is no longer supported; run UXC through WSL.
### Cargo
```bash
cargo install uxc
```
### From Source
```bash
git clone https://github.com/holon-run/uxc.git
cd uxc
cargo install --path .
```
## Quickstart (3 Minutes)
Most HTTP examples omit the scheme for brevity.
For public hosts, UXC infers `https://` when omitted.
1. Discover operations:
```bash
uxc petstore3.swagger.io/api/v3 -h
```
2. Inspect operation schema:
```bash
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} -h
```
3. Execute with structured input:
```bash
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} petId=1
```
Use only these endpoint forms:
- `uxc <host> -h`
- `uxc <host> <operation_id> -h`
- `uxc <host> <operation_id> key=value` or `uxc <host> <operation_id> '{...}'`
## Protocol Examples (One Each)
Operation ID conventions:
- OpenAPI: `method:/path` (example: `get:/users/{id}`)
- gRPC: `Service/Method`
- GraphQL: `query/viewer`, `mutation/createUser`
- MCP: tool name (example: `ask_question`)
- JSON-RPC: method name (example: `eth_getBalance`)
### OpenAPI
```bash
uxc petstore3.swagger.io/api/v3 -h
uxc petstore3.swagger.io/api/v3 get:/pet/{petId} petId=1
```
For schema-separated services, you can override schema source:
```bash
uxc api.github.com -h \
--schema-url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
```
### gRPC
```bash
uxc grpcb.in:9000 -h
uxc grpcb.in:9000 addsvc.Add/Sum a=1 b=2
```
Note: gRPC unary runtime invocation requires `grpcurl` on `PATH`.
### GraphQL
```bash
uxc countries.trevorblades.com -h
uxc countries.trevorblades.com query/country code=US
# Prefer positional JSON for non-string object arguments
uxc api.linear.app/graphql mutation/issueCreate '{"input":{"teamId":"TEAM_ID","title":"Test"}}'
# Optional: control GraphQL return fields via reserved _select argument
uxc api.linear.app/graphql query/issues '{"first":5,"_select":"nodes { identifier title url state { name } }"}'
```
### MCP
```bash
uxc mcp.deepwiki.com/mcp -h
uxc mcp.deepwiki.com/mcp ask_question repoName=holon-run/uxc question='What does this project do?'
```
### MCP (stdio)
UXC can also invoke MCP servers started as local processes over stdio.
For stdio endpoints, the "URL" is a quoted command line.
Playwright MCP (stdio) example:
```bash
# One-off discovery
uxc "npx -y @playwright/mcp@latest --headless --isolated" -h
# Create a stable command name for repeated use (recommended)
uxc link playwright-mcp-cli "npx -y @playwright/mcp@latest --headless --isolated"
playwright-mcp-cli -h
# Inspect an operation before calling it
playwright-mcp-cli browser_navigate -h
# Call operations with key=value args
playwright-mcp-cli browser_navigate url=https://example.com
playwright-mcp-cli browser_snapshot
```
### JSON-RPC
```bash
uxc fullnode.mainnet.sui.io -h
uxc fullnode.mainnet.sui.io sui_getLatestCheckpointSequenceNumber
```
## Skills
UXC provides one canonical skill plus scenario-specific official wrappers.
Use `uxc` skill as the shared execution layer, and add wrappers when they fit your workflow.
| `uxc` | Canonical schema discovery and multi-protocol execution layer | [`skills/uxc/SKILL.md`](skills/uxc/SKILL.md) |
| `deepwiki-mcp-skill` | Query repository documentation and ask codebase questions | [`skills/deepwiki-mcp-skill/SKILL.md`](skills/deepwiki-mcp-skill/SKILL.md) |
| `context7-mcp-skill` | Query up-to-date library documentation/examples over MCP | [`skills/context7-mcp-skill/SKILL.md`](skills/context7-mcp-skill/SKILL.md) |
| `okx-mcp-skill` | Query OKX MCP for token, market, wallet, and swap workflows | [`skills/okx-mcp-skill/SKILL.md`](skills/okx-mcp-skill/SKILL.md) |
| `notion-mcp-skill` | Operate Notion MCP workflows with OAuth-aware guidance | [`skills/notion-mcp-skill/SKILL.md`](skills/notion-mcp-skill/SKILL.md) |
| `discord-openapi-skill` | Operate Discord REST API via UXC + OpenAPI schema mapping | [`skills/discord-openapi-skill/SKILL.md`](skills/discord-openapi-skill/SKILL.md) |
| `playwright-mcp-skill` | Run `@playwright/mcp` over MCP stdio through `uxc` (browser automation) | [`skills/playwright-mcp-skill/SKILL.md`](skills/playwright-mcp-skill/SKILL.md) |
### Install Skills
Install from this repository using `npx skills`:
```bash
# Install canonical base skill for Codex
npx -y skills@latest add holon-run/uxc --skill uxc --agent codex -y
# Install wrappers as needed
npx -y skills@latest add holon-run/uxc --skill playwright-mcp-skill --skill okx-mcp-skill --skill discord-openapi-skill --agent codex -y
```
Install published skills from ClawHub:
```bash
# Install into ~/.openclaw/skills/<slug>
clawhub --workdir ~/.openclaw --dir skills install uxc
clawhub --workdir ~/.openclaw --dir skills install playwright-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install okx-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install discord-openapi-skill
```
See [`docs/skills.md`](docs/skills.md) for install methods and maintenance rules.
## Output and Help Conventions
UXC is JSON-first by default.
Use `--text` (or `--format text`) when you want human-readable CLI output.
Examples:
```bash
uxc
uxc help
uxc <host> -h
uxc <host> <operation_id> -h
uxc --text help
```
Note: In endpoint routing, `help` is treated as a literal operation name, not a help alias.
Success envelope shape:
```json
{
"ok": true,
"kind": "call_result",
"protocol": "openapi",
"endpoint": "https://petstore3.swagger.io/api/v3",
"operation": "get:/pet/{petId}",
"data": {},
"meta": {
"version": "v1",
"duration_ms": 128
}
}
```
For MCP `tools/call`, `data` may include `content`, optional `structuredContent`, and optional `isError`.
Failure envelope shape:
```json
{
"ok": false,
"error": {
"code": "INVALID_ARGUMENT",
"message": "Field 'id' must be an integer"
},
"meta": {
"version": "v1"
}
}
```
## Auth (Credentials + Bindings)
UXC authentication has two resources:
- Credentials: secret material and auth type
- Bindings: endpoint matching rules that select a credential
Example:
```bash
uxc auth credential set deepwiki --auth-type bearer --secret-env DEEPWIKI_TOKEN
uxc auth credential set deepwiki --secret-op op://Engineering/deepwiki/token
uxc auth binding add --id deepwiki-mcp --host mcp.deepwiki.com --path-prefix /mcp --scheme https --credential deepwiki --priority 100
# api_key supports configurable header names and templates
uxc auth credential set okx --auth-type api_key --secret-env OKX_ACCESS_KEY --api-key-header OK-ACCESS-KEY
uxc auth credential set okx-advanced --auth-type api_key --header "OK-ACCESS-KEY={{secret}}" --header "OK-ACCESS-PASSPHRASE={{env:OKX_PASSPHRASE}}"
```
For `--secret-op`, secret resolution happens at request runtime through daemon execution.
Ensure daemon has usable 1Password auth context (for example `OP_SERVICE_ACCOUNT_TOKEN`), and restart daemon after env changes.
OAuth for MCP HTTP is supported (device code, client credentials, authorization code + PKCE).
See [`docs/oauth-mcp-http.md`](docs/oauth-mcp-http.md) for full workflows.
## Docs Map
- Extended quickstart and protocol walkthroughs: [`docs/quickstart.md`](docs/quickstart.md)
- Public no-key endpoints for protocol checks: [`docs/public-endpoints.md`](docs/public-endpoints.md)
- Logging and troubleshooting with `RUST_LOG`: [`docs/logging.md`](docs/logging.md)
- Auth credential secret sources (`literal/env/op`): [`docs/auth-secret-sources.md`](docs/auth-secret-sources.md)
- Run daemon with service managers (`systemd`/`launchd`): [`docs/daemon-service.md`](docs/daemon-service.md)
- OpenAPI schema mapping and `--schema-url`: [`docs/schema-mapping.md`](docs/schema-mapping.md)
- Skills overview and install/maintenance guidance: [`docs/skills.md`](docs/skills.md)
- Release process: [`docs/release.md`](docs/release.md)
## Contributing
Contributions are welcome.
- Development workflow and quality bar: [`CONTRIBUTING.md`](CONTRIBUTING.md)
- CI and release flows: [GitHub Actions](https://github.com/holon-run/uxc/actions)
## License
MIT License - see [`LICENSE`](LICENSE).