Schema-driven CLI + TUI + MCP runtime
npm install oatty
!Rust
!License
!Status
A vendor-agnostic operations surface for teams that are tired of juggling near-identical CLIs, partial API coverage,
and separate MCP servers with different constraints.
Oatty turns OpenAPI documents into runnable commands and surfaces them in a searchable, keyboard-first TUI. The same
command model is available through a secondary CLI interface and can be extended with MCP tools and reusable workflows.
Modern developer tooling has a strange paradox:
the APIs are powerful and well-documented, but the tools built on top of them are fragmented, incomplete, and
inconsistent.
Most vendor CLIs are thin wrappers around an API with a small set of hand-crafted workflows.
When you work across vendors, the experience converges into the same problems:
- Nearly identical commands with different naming conventions
- Partial API coverage that forces you back to curl or custom scripts
- Separate MCP servers that expose even less functionality than the CLI
- Automation that lives in brittle scripts instead of reusable, inspectable workflows
Oatty was built to collapse this complexity into one coherent operational surface.
---
Oatty is not just a CLI replacement — it is a carefully designed terminal experience built around four core
principles.
You should never need to memorize commands.
- Every command, workflow, and option is searchable and browsable.
- The TUI acts as a living catalog derived directly from schemas and plugins.
- If the API supports it, you can find it — even if you’ve never used it before.
This makes Oatty approachable for new users and powerful for experts.
---
Each screen does one thing, clearly.
- Search commands
- Inspect details
- Run an action
- Monitor progress or results
There is no clutter, no overloaded views, and no hidden modes.
Familiar interaction patterns (lists, tables, forms, logs) keep cognitive load low, even when the underlying task is
complex.
---
Oatty is designed for real work, not demos.
- Fast startup and low-latency interactions
- Keyboard-first navigation with the mouse interactions you'd expect from a beautiful terminal UI
- Reliable execution paths for long-running workflows and streaming output
Power users can move as fast as they can type — without sacrificing safety or clarity.
---
Once you learn Oatty, you’ve learned every vendor's CLI, workflow, and MCP server.
- The same command model powers the CLI, the TUI, workflows, and MCP tools
- Flags, arguments, outputs, and behaviors follow consistent patterns
- Vendor-specific quirks are normalized behind a shared execution model
This consistency dramatically reduces context switching and relearning.
---
Treat vendor APIs and MCP servers as inputs, not product boundaries.
Oatty ingests OpenAPI schemas to build a runtime command catalog, exposes that catalog through a unified CLI and TUI,
and allows vendors or teams to extend it via MCP — all while enabling first-class, filesystem-backed workflows.
Instead of maintaining:
- N vendor CLIs
- N MCP servers
- N incompatible automation approaches
You get one interface, one mental model, and one place to operate.
---
- Full API coverage without waiting for vendors to implement it their CLI
- Workflows that span multiple vendors and MCP servers
- A single MCP surface instead of fragmented plugin ecosystems
- Shareable, reviewable workflows instead of opaque scripts
- A terminal UX that scales from quick commands to complex operations
Launch Oatty with no arguments to enter interactive mode:
``bash`
cargo run -p oatty
If you have no catalogs configured yet, import one from the Library view:
1. Run cargo run -p oatty.schemas/samples/render-public-api.json
2. In the Library view, import a local OpenAPI document (for example, ) or a URL.~/.config/oatty/registry.json
3. Accept the default command prefix (or enter your own).
4. Registry configuration is saved to and manifests are stored under ~/.config/oatty/catalogs/.
Once imported, browse commands, inspect arguments, execute actions, and monitor logs directly in the TUI.
The CLI uses the same runtime command catalog as the TUI and is optimized for scripting and automation.
Build and run:
- Build: cargo build --workspacecargo run -p oatty
- TUI mode: cargo run -p oatty --
- CLI mode:
Examples:
- cargo run -p oatty -- github advisories:listcargo run -p oatty -- render services:list --limit 10
- cargo run -p oatty -- workflow list
- cargo run -p oatty -- workflow preview --file workflows/create_app_and_db.yaml
-
Use oatty --help to view available groups and command spec canonical IDs.
Note: available commands depend on which registry catalogs and MCP plugins are configured/enabled.
Oatty can be installed via npm and downloads the matching prebuilt binary for your platform during postinstall.
`bash`
npm i -g oatty
oatty --help
How it works:
- npm installs a small Node launcher package (oatty).SHA256SUMS
- The installer detects your OS/arch and fetches the matching GitHub release asset for the npm package version.
- The download is verified against the release before extraction.
Currently mapped platforms:
- macOS x64 -> x86_64-apple-darwinarm64
- macOS -> aarch64-apple-darwinx64
- Linux -> x86_64-unknown-linux-gnux64
- Windows -> x86_64-pc-windows-msvc
If your platform is not currently mapped, install from source (cargo build --release) or use a directly downloaded binary.
Maintainers:
- GitHub release assets are built/published via .github/workflows/release.yml..github/workflows/release.yml
- npm publication is handled by using Trusted Publishing.RELEASE.md
- End-to-end operator steps: .
- TUI (crates/tui): interactive Ratatui/Crossterm interface for discovery, execution, help, and logs.crates/registry
- Registry (): loads registry catalogs from ~/.config/oatty/registry.json and reads per-catalog~/.config/oatty/catalogs/*.bin
manifest files (typically ).crates/mcp
- MCP (): loads ~/.config/oatty/mcp.json, manages plugin lifecycles, and can inject MCP tool commandscrates/cli
into the registry at runtime.
- CLI (): builds a Clap tree from the registry, routes workflow commands, and executes HTTP/MCPcrates/engine
commands.
- Engine (): workflow parsing and execution utilities used by oatty workflow ....
- OATTY_LOG: tracing level for stderr logs in CLI mode (error, warn, info [default], debug, trace).TUI_THEME
- : theme override for the TUI (dracula, dracula_hc, nord, nord_hc, cyberpunk, cyberpunk_hc,ansi256
, ansi256_hc).MCP_CONFIG_PATH
- : overrides MCP config path (default: ~/.config/oatty/mcp.json).REGISTRY_CONFIG_PATH
- : overrides registry config path (default: ~/.config/oatty/registry.json).REGISTRY_CATALOGS_PATH
- : overrides the directory where catalog manifest files are stored (default:~/.config/oatty/catalogs
).REGISTRY_WORKFLOWS_PATH
- : overrides workflow manifest storage (default: ~/.config/oatty/workflows).
Authentication headers/tokens are configured per catalog in the Library view (or persisted catalog configuration), not
via a global API token environment variable.
- TUI mode silences tracing output to stderr while the UI is active to prevent overlaying the terminal UI; logs are
routed into in-app panes where applicable.
- CLI mode writes logs to stderr as usual.
- Toolchain: rust-toolchain.toml pins the project to Rust stable.cli
- Workspace crates: , tui, registry, registry-gen, engine, api, util, types, mcp.cargo build --workspace
- Common commands:
- Build: cargo test --workspace
- Test: cargo clippy --workspace -- -D warnings
- Lint: cargo fmt --all
- Format:
- Generator crate: crates/registry-gen (oatty-registry-gen) can derive a manifest from OpenAPI documents.~/.config/oatty/registry.json
- At runtime, the registry reads catalog manifests from paths referenced in .
The registry is derived from OpenAPI documents using the registry-gen crate.
Add a dependency on the generator crate from within the workspace:
`toml`
[dependencies]
oatty-registry-gen = { path = "crates/registry-gen" }
Generate a manifest file (postcard):
`rust
use std::path::PathBuf;
use oatty_registry_gen::{io::ManifestInput, write_manifest};
fn main() -> anyhow::Result<()> {
let schema = PathBuf::from("schemas/samples/render-public-api.json");
let output = PathBuf::from("target/manifest.bin");
write_manifest(ManifestInput::new(Some(schema), None, None), output)?;
Ok(())
}
`
Generate a manifest file (JSON):
`rust
use std::path::PathBuf;
use oatty_registry_gen::{io::ManifestInput, write_manifest_json};
fn main() -> anyhow::Result<()> {
let schema = PathBuf::from("schemas/samples/render-public-api.json");
let output = PathBuf::from("target/manifest.json");
write_manifest_json(ManifestInput::new(Some(schema), None, None), output)?;
Ok(())
}
`
Derive commands in-memory from an OpenAPI document:
`rust
use oatty_registry_gen::openapi::{derive_commands_from_openapi, derive_vendor_from_document};
fn load_commands(openapi_json: &str) -> anyhow::Result
let document: serde_json::Value = serde_json::from_str(openapi_json)?;
let vendor = derive_vendor_from_document(&document);
let cmds = derive_commands_from_openapi(&document, &vendor)?;
Ok(cmds)
}
`
`mermaid
flowchart LR
subgraph Runtime
A[oatty no args] -->|Launch| TUI[TUI]
A2["oatty
end
subgraph Registry
S[OpenAPI Document] --> D["Derive Manifest (registry-gen)"]
D --> M["Catalog Manifest (.bin)"]
M --> RC[Registry Catalogs]
RC --> C[Clap Tree]
end
TUI -->|Search/Select| C
TUI -->|Compose| RUN[Execute]
CLI -->|Match| C
CLI -->|Execute| RUN
RUN -->|HTTP| HTTP[Oatty API]
RUN -->|MCP| MCP[MCP Tool]
HTTP --> OUT2[Status + Body]
MCP --> OUT2
subgraph Policy
REDACT[Redact secrets in output]
end
OUT2 --> REDACT
RUN --> LOGS[Logs Panel / stdout]
`
- Secrets are redacted from output by default (headers/payload in output and logs).
- Network calls go through reqwest with default timeouts.
- Release artifact verification steps: RELEASE.md.RELEASE.md
- Release and publish runbook: .
- Schema-driven registry, CLI router, TUI, MCP plugin engine, and workflow support are implemented. Some HTTP client
behaviors (retries/backoff) are minimal.
- Location: crates/tui/src/ui/theme (roles, helpers, Dracula/Nord themes)specs/THEME.md
- Docs: (theme mapping, usage, and guidelines)TUI_THEME
- Select theme via env var :dracula
- (default), dracula_hcnord
- , nord_hccyberpunk
- , cyberpunk_hcansi256
- , ansi256_hcTUI_THEME=dracula cargo run -p oatty
- Example:
- Release and publish runbook: RELEASE.md`