y-cli 🚀
- other
A Tiny Terminal Chat App for AI Models with MCP Client Support
About
What is y-cli?
y-cli is a command-line interface chat application that brings AI conversations to your terminal. It runs on any system with Python and uv, and is designed for developers and power users who want to interact with multiple AI models and MCP tools from a terminal environment.
How to use y-cli?
Install y-cli with uvx y-cli or uv tool install y-cli. After installation, run y-cli init to configure your OpenRouter API key and default settings. Start a chat with y-cli chat. Use commands like y-cli bot add, y-cli mcp add, and y-cli prompt add to configure bots, MCP servers, and prompts.
Key features of y-cli
- Flexible storage: local JSONL files or Cloudflare KV/R2 for cloud backup
- Interactive chat interface with tool execution visualization
- Supports multiple bot configurations (any base_url/api_key/model)
- Works with OpenAI and Dify chat completion streaming APIs
- Supports reasoning models like Deepseek-r1 and OpenAI o3-mini
- MCP integration: multiple server configs (stdio/SSE) and persistent daemon
Use cases of y-cli
- Chat with various AI models (OpenAI, Anthropic, OpenRouter, etc.) from the terminal
- Integrate external tools via MCP servers (e.g., web search, file access)
- Switch between different bot configurations without leaving the CLI
- Store and share chat conversations using local JSONL or cloud storage
- Run a persistent MCP daemon for long‑running tool integrations
FAQ from y-cli
What are the prerequisites for y-cli?
You need uv (Python package manager) and an OpenRouter API key. Follow the official uv installation guide and create an API key at openrouter.ai/settings/keys.
How do I install y-cli?
Run uvx y-cli to use without installation, or uv tool install y-cli to install globally. Then run y-cli init and y-cli chat to start.
Does y-cli support MCP (Model Context Protocol)?
Yes, y-cli has fully integrated MCP client support. You can add multiple MCP server configurations (stdio or SSE protocols), manage them with y-cli mcp commands, and run a persistent daemon with y-cli daemon.
What AI providers and model types does y-cli support?
y-cli supports any base_url/api_key/model combination that uses OpenAI‑compatible chat completion streaming or Dify chat‑messages streaming. It also supports reasoning models like Deepseek‑r1 and OpenAI o3‑mini.
What storage options are available for chat history?
Chat history can be stored locally as JSONL files (easy to sync) or in the cloud using Cloudflare KV and R2 for backup and sharing.
Details
- Author
- luohy15
- GitHub stars
- 149
- Category
- other
- Repository
- luohy15/y-cli
y-cli 🚀
A tiny command-line interface chat application that brings AI conversations to your terminal.
Check out y-gui for a web-based version of y-cli.
✨ Features
- 📝 Flexible storage options:
- Local JSONL files for easy access and sync
- Cloudflare KV and R2 for cloud storage and backup
- 💬 Interactive chat interface with tool execution visualization
- 🤖 Support for multiple bot configurations (any base_url/api_key/model combination). Supported api format type:
- OpenAI chat completion streaming format
- Dify chat-messages streaming format
- 🤔 Support for reasoning model
- Deepseek-r1 reasoning_content output print
- OpenAI o3-mini reasoning_effort configuration
- 🔗 MCP (Model Context Protocol) integration:
- Client support with multiple server configurations (stdio/SSE)
- Persistent daemon
- Custom prompt configurations
- 🧐 Simple "Deep Research" mode by prompt configuration
- Demo
Demo
Multiple bot configurations
➜ ~ y-cli bot list
Name API Key API Type Base URL Model Print Speed Description OpenRouter Config MCP Servers Reasoning Effort
----------- ----------- ---------- ----------------------------------- ----------------------------------- ------------- ------------- ------------------- ------------- ------------------
default sk-or-v1... N/A https://gateway.ai.cloudflare.co... google/gemini-2.0-flash-001 None N/A Yes No N/A
claude sk-or-v1... N/A https://gateway.ai.cloudflare.co... anthropic/claude-3.7-sonnet:beta None N/A Yes todo N/A
o3-mini sk-or-v1... N/A https://gateway.ai.cloudflare.co... openai/o3-mini None N/A Yes No low
ds-chat sk-or-v1... N/A https://gateway.ai.cloudflare.co... deepseek/deepseek-chat-v3-0324:free None N/A Yes tavily N/A
dify-bot app-2drF... dify https://api.dify.ai/v1 None N/A No No N/A
Multiple MCP servers
➜ ~ y-cli mcp list
Name Type Command/URL Arguments/Token Environment Auto-Confirm
-------------- ------ ------------------- ----------------- -------------- --------------
brave-search sse https://router.m... brave_web_s...
todo stdio uvx mcp-todo
exa-mcp-server stdio npx exa-mcp-server EXA_API_KEY...
⚡ Quick Start
Prerequisites
Required:
1. uv
2. OpenRouter API key
Setup Instructions:
1. uv
- Follow the official installation guide
- uv will automatically manage Python installation
2. OpenRouter API key
- Visit OpenRouter Settings
- Create a new API key
- Save it for the initialization step
Run without Installation
uvx y-cli
Install with uv tool
uv tool install y-cli
Initialize
y-cli init
Start Chat
y-cli chat
🛠️ Usage
y-cli [OPTIONS] COMMAND [ARGS]...
Commands
-chat Start a new chat conversation or continue an existing one
- list List chat conversations with optional filtering
- share Share a chat conversation by generating a shareable link
- bot Manage bot configurations:
- add Add a new bot configuration
- list List all configured bots
- delete Delete a bot configuration
- mcp Manage MCP server configurations:
- add Add a new MCP server configuration
- list List all configured MCP servers
- delete Delete an MCP server configuration
- daemon Manage the MCP daemon:
- start Start the MCP daemon
- stop Stop the MCP daemon
- status Check daemon status
- log View daemon logs
- restart Restart the daemon
- prompt Manage prompt configurations:
- add Add a new prompt configuration
- list List all configured prompts
- delete Delete a prompt configuration
Options
---help Show help message and exit
📚 Documentation
Visit the deepwiki page for comprehensive project documentation and guides.
