# UXC
**Universal X-Protocol CLI**
A stable execution surface for agents.
[](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 gives agents one stable way to discover, authenticate, and call remote tools across
OpenAPI, gRPC, GraphQL, MCP, and JSON-RPC.
Instead of writing separate glue for each protocol, SDK, or local MCP setup, UXC turns
remote interfaces into one predictable command contract with help-first discovery,
structured execution, and deterministic JSON output.
## Why UXC Exists
Agent tool use usually breaks down in the same places:
- auth scattered across prompts, scripts, and local setup
- different invocation models for each protocol
- local MCP server names and config that are not portable across machines
- large tool manifests or schemas pushed into prompt context
- one-off wrappers that drift from upstream interfaces
UXC exists to make remote capabilities feel like one stable execution surface for agents
and automation.
## What UXC Does
- Discover operations from an endpoint on demand
- Inspect input and output shape before execution
- Execute operations with structured arguments
- Return deterministic JSON envelopes by default
- Reuse auth bindings, signer profiles, and linked shortcuts
If a target can describe itself, UXC can usually call it.
## Why It Works Well With Agents and Skills
- Progressive discovery keeps context small: `<host> -h`, `<host> <operation_id> -h`, then execute
- URL-first usage avoids dependency on machine-specific MCP aliases or local wrapper names
- Auth bindings externalize credential matching instead of burying it in prompts
- Linked shortcuts (`uxc link`) turn remote endpoints into stable local commands
- The same command contract can be reused across many skills and workflows
## 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, bindings, and signer profiles
- App-credential bootstrap for short-lived bearer tokens (for example, Feishu/Lark and DingTalk)
- Host shortcut commands via `uxc link`
- Link-level default OpenAPI schema persistence via `uxc link --schema-url`
- Daemon-backed background subscriptions via `uxc subscribe`
- Provider-aware event transports for Slack Socket Mode, Discord Gateway, and Feishu long connection
- Stdio child-process auth injection via `--inject-env NAME={{secret}}`
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:
This design keeps discovery, auth, and execution 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 a stable execution surface for remote capabilities that can describe themselves.
## 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.
### Start Here
- [`uxc`](skills/uxc/SKILL.md): canonical schema discovery and multi-protocol execution layer
- [`playwright-mcp-skill`](skills/playwright-mcp-skill/SKILL.md): browser automation over MCP stdio through `uxc`
- [`context7-mcp-skill`](skills/context7-mcp-skill/SKILL.md): current library documentation and examples over MCP
### Core
- [`uxc`](skills/uxc/SKILL.md): canonical schema discovery and multi-protocol execution layer
- [`uxc-skill-creator`](skills/uxc-skill-creator/SKILL.md): templates and workflow guidance for building new UXC-based skills
### Browser Automation
- [`playwright-mcp-skill`](skills/playwright-mcp-skill/SKILL.md): run `@playwright/mcp` over MCP stdio through `uxc`
### Knowledge and Docs
- [`context7-mcp-skill`](skills/context7-mcp-skill/SKILL.md): query up-to-date library documentation and examples
- [`deepwiki-mcp-skill`](skills/deepwiki-mcp-skill/SKILL.md): query repository documentation and ask codebase questions
### Workspace and Collaboration
- [`notion-mcp-skill`](skills/notion-mcp-skill/SKILL.md): operate Notion MCP workflows with OAuth-aware guidance
- [`linear-graphql-skill`](skills/linear-graphql-skill/SKILL.md): operate Linear issues, projects, and teams through GraphQL
- [`slack-openapi-skill`](skills/slack-openapi-skill/SKILL.md): operate Slack Web API and receive inbound Socket Mode events through `uxc subscribe`
- [`discord-openapi-skill`](skills/discord-openapi-skill/SKILL.md): operate Discord REST API and receive Gateway events through `uxc subscribe`
- [`feishu-openapi-skill`](skills/feishu-openapi-skill/SKILL.md): operate Feishu/Lark IM APIs with bootstrap-managed auth and long-connection event intake
- [`telegram-openapi-skill`](skills/telegram-openapi-skill/SKILL.md): operate Telegram Bot API and receive updates through polling-based `uxc subscribe`
- [`matrix-openapi-skill`](skills/matrix-openapi-skill/SKILL.md): operate Matrix Client-Server API and follow room timelines through `/sync` polling
### Crypto and Onchain Data
- [`bitquery-graphql-skill`](skills/bitquery-graphql-skill/SKILL.md): query Bitquery GraphQL for onchain trades, transfers, holders, balances, and market structure with OAuth client credentials
- [`binance-web3-openapi-skill`](skills/binance-web3-openapi-skill/SKILL.md): query Binance Web3 token discovery, rankings, smart money, audits, and address positions through OpenAPI
- [`binance-spot-openapi-skill`](skills/binance-spot-openapi-skill/SKILL.md): operate Binance Spot public market data and signed account/order flows through OpenAPI
- [`binance-spot-websocket-skill`](skills/binance-spot-websocket-skill/SKILL.md): subscribe to Binance Spot public trade, ticker, depth, and book-ticker streams via raw WebSocket
- [`okx-exchange-websocket-skill`](skills/okx-exchange-websocket-skill/SKILL.md): subscribe to OKX public exchange ticker, trade, book, and candle channels via raw WebSocket
- [`okx-mcp-skill`](skills/okx-mcp-skill/SKILL.md): query OKX MCP for token, market, wallet, and swap workflows
- [`dune-mcp-skill`](skills/dune-mcp-skill/SKILL.md): discover blockchain tables, run SQL, fetch results, and build charts via Dune MCP
- [`thegraph-mcp-skill`](skills/thegraph-mcp-skill/SKILL.md): discover subgraphs, inspect schemas, and execute GraphQL via The Graph Subgraph MCP bridge
- [`thegraph-token-mcp-skill`](skills/thegraph-token-mcp-skill/SKILL.md): query token, wallet, transfer, holder, and market data via The Graph Token API MCP
- [`etherscan-mcp-skill`](skills/etherscan-mcp-skill/SKILL.md): investigate addresses, token holders, and contracts via Etherscan MCP
### Install Skills
Install from this repository using `npx skills`:
```bash
# Start with the shared execution layer
npx -y skills@latest add holon-run/uxc --skill uxc --agent codex -y
# Add browser and knowledge skills
npx -y skills@latest add holon-run/uxc --skill playwright-mcp-skill --skill context7-mcp-skill --skill deepwiki-mcp-skill --agent codex -y
# Add workspace skills
npx -y skills@latest add holon-run/uxc --skill notion-mcp-skill --skill linear-graphql-skill --skill slack-openapi-skill --skill discord-openapi-skill --skill feishu-openapi-skill --skill telegram-openapi-skill --skill matrix-openapi-skill --agent codex -y
# Add crypto and onchain skills
npx -y skills@latest add holon-run/uxc --skill bitquery-graphql-skill --skill binance-web3-openapi-skill --skill binance-spot-openapi-skill --skill binance-spot-websocket-skill --skill okx-exchange-websocket-skill --skill okx-mcp-skill --skill dune-mcp-skill --skill thegraph-mcp-skill --skill thegraph-token-mcp-skill --skill etherscan-mcp-skill --agent codex -y
```
Install published skills from ClawHub:
```bash
# Start with the shared execution layer
clawhub --workdir ~/.openclaw --dir skills install uxc
# Add browser and knowledge skills
clawhub --workdir ~/.openclaw --dir skills install playwright-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install context7-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install deepwiki-mcp-skill
# Add workspace skills
clawhub --workdir ~/.openclaw --dir skills install notion-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install linear-graphql-skill
clawhub --workdir ~/.openclaw --dir skills install slack-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install discord-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install feishu-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install telegram-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install matrix-openapi-skill
# Add crypto and onchain skills
clawhub --workdir ~/.openclaw --dir skills install bitquery-graphql-skill
clawhub --workdir ~/.openclaw --dir skills install binance-web3-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install binance-spot-openapi-skill
clawhub --workdir ~/.openclaw --dir skills install binance-spot-websocket-skill
clawhub --workdir ~/.openclaw --dir skills install okx-exchange-websocket-skill
clawhub --workdir ~/.openclaw --dir skills install okx-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install dune-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install thegraph-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install thegraph-token-mcp-skill
clawhub --workdir ~/.openclaw --dir skills install etherscan-mcp-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
For non-OAuth credentials, use two auth tracks:
- simple auth: keep using `--secret`, `--secret-env`, or `--secret-op`
- complex auth: use repeatable `--field <name>=<source>` plus optional binding-level `--signer-json`
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}}"
# multi-field auth for signed APIs
uxc auth credential set binance --auth-type api_key --field api_key=env:BINANCE_API_KEY --field secret_key=env:BINANCE_SECRET_KEY
uxc auth binding add --id binance-account --host api.binance.com --path-prefix /api/v3 --scheme https --credential binance --signer-json '{"kind":"hmac_query_v1","algorithm":"hmac_sha256","signing_field":"secret_key","key_field":"api_key","key_placement":"header","key_name":"X-MBX-APIKEY","signature_param":"signature","signature_encoding":"hex","timestamp_param":"timestamp","timestamp_unit":"milliseconds","canonicalization":{"mode":"preserve_order"}}' --priority 100
```
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).