@syrin/cli 1.3.2 → 1.4.1

package/README.md

@@ -1,231 +1,248 @@
 # Syrin
 
-![Syrin Logo](/assets/syrin-logo-dark-bg.png)
+![Syrin Logo](https://github.com/Syrin-Labs/cli/raw/main/assets/syrin-logo-dark-bg.png)
 
-[![npm version](https://badge.fury.io/js/%40syrin%2Fsyrin.svg)](https://badge.fury.io/js/%40syrin%2Fsyrin) [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![npm version](https://badge.fury.io/js/%40syrin%2Fcli.svg)](https://www.npmjs.com/package/@syrin/cli) [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.12.0-brightgreen)](https://nodejs.org/)
 
-**Syrin is a runtime intelligence system for MCP servers.**
+## Stop Silent Failures in AI Tool Calls
 
-It helps developers **see, validate, and reason about MCP execution** before systems reach production.
+Your AI agent just called the same tool 47 times with identical parameters.
+Your logs look fine. You're silently burning $200 in tokens.
 
-Documentation: [https://docs.syrin.dev](https://docs.syrin.dev)
+**Syrin catches these failures before production.**
 
 ---
 
-## The Problem
+## What Is This?
 
-Building MCP servers today usually looks like this:
+Syrin is a development toolkit for [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers — the standard way AI agents call external tools.
 
-1. Define tools and prompts
-2. Connect an LLM
-3. Run the server
-4. Hope execution behaves as expected
+**Without Syrin:**
 
-When things go wrong:
+```txt
+Tool called 47x          →  No visibility
+$200 burned              →  Silent failure
+Logs look "fine"         →  Debug for hours
+```
 
-- Tools are called for unclear reasons
-- Behaviour changes between runs
-- Debugging relies on logs and guesswork
-- Contract issues surface only after failures
+**With Syrin:**
 
-Most problems are discovered **after** deployment.
+```txt
+Loop detected at call #3 →  Execution halted
+Full event trace         →  See exactly what happened
+Contract validated       →  Catch issues before runtime
+```
 
 ---
 
-## Installation
+## What Syrin Catches
 
-### Quick start
+**Tool Loops** — Model proposes the same tool repeatedly with no progress
 
-```bash
-npx @syrin/cli init
-```
+**Wrong Tool Selection** — Similar names, overlapping schemas, ambiguous descriptions cause silent misbehavior
 
-### Global install
+**Silent Failures** — Tool throws an error but execution continues with broken state
 
-```bash
-npm install -g @syrin/cli
-```
+**Contract Mismatches** — Input/output schemas don't align between chained tools
 
-### Local install (recommended for CI)
+**Hidden Dependencies** — Tools assume state that doesn't exist
 
-```bash
-npm install @syrin/cli
-```
+Documentation: [https://docs.syrin.dev](https://docs.syrin.dev)
 
-Requirements:
+---
 
-- Node.js ≥ 18
-- npm ≥ 9
+## See It In Action
+
+<table>
+<tr>
+<td width="33%"><strong>syrin analyse</strong><br/>Catch contract issues</td>
+<td width="33%"><strong>syrin dev</strong><br/>Interactive development</td>
+<td width="33%"><strong>syrin test</strong><br/>Sandboxed tool testing</td>
+</tr>
+<tr>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-analyse/analyse.gif" width="280" alt="syrin analyse demo"/></td>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-dev/dev.gif" width="280" alt="syrin dev demo"/></td>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-test/test_tool.gif" width="280" alt="syrin test demo"/></td>
+</tr>
+<tr>
+<td width="33%"><strong>syrin init</strong><br/>Project setup</td>
+<td width="33%"><strong>syrin list</strong><br/>Inspect tools</td>
+<td width="33%"><strong>syrin test --connection</strong><br/>Connection test</td>
+</tr>
+<tr>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-init/init.gif" width="280" alt="syrin init demo"/></td>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-list/list.gif" width="280" alt="syrin list demo"/></td>
+<td><img src="https://github.com/Syrin-Labs/cli/raw/main/assets/demo/syrin-test/test_connection.gif" width="280" alt="syrin test --connection demo"/></td>
+</tr>
+</table>
 
 ---
 
-## The Syrin Way
+## Try It Now
 
-Syrin changes the workflow.
+```bash
+# No install needed — run directly
+npx @syrin/cli analyse --transport http --url http://localhost:8000/mcp
+```
 
-Instead of guessing how MCP behaves, you **inspect and validate it explicitly**.
+Or install globally:
 
-**Before:**
+```bash
+npm install -g @syrin/cli
 
-```text
-Write tools → Connect LLM → Run server → Debug via logs
+syrin init --global
+syrin doctor                                                    # Check your environment
+syrin analyse --transport http --url http://localhost:8000/mcp   # Analyze an MCP server
+syrin dev --exec --transport http --url http://localhost:8000/mcp # Interactive dev mode
 ```
 
-**With Syrin:**
+Or initialize a project with local config:
 
-```text
-Define tools
-→ Analyse contracts
-→ Validate protocol
-→ Inspect behaviour interactively
-→ Enable execution with confidence
+```bash
+npx @syrin/cli init
+syrin doctor
+syrin analyse
 ```
 
-Syrin does not replace MCP.  
-It makes MCP systems understandable and testable.
+**Want to try with a sample server?** Clone the repo and use the included [example MCP server](./examples/demo-mcp-py/):
 
----
-
-## What Syrin Does
+```bash
+git clone https://github.com/Syrin-Labs/cli.git && cd cli/examples/demo-mcp-py
+python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
+python server.py --mode http --port 8000 &
+npx @syrin/cli analyse --transport http --url http://localhost:8000/mcp
+```
 
-- Validates MCP protocol compliance
-- Analyses tool contracts statically
-- Lets you interact with MCP servers using real LLMs
-- Shows which tools are proposed and why
-- Prevents accidental execution by default
-- Surfaces configuration and contract errors early
+Requirements: Node.js >= 20.12, npm >= 9
 
 ---
 
-## Key Capabilities
-
-### Static Tool Contract Analysis (`syrin analyse`)
+## Core Commands
 
-LLMs rely entirely on tool contracts.  
-If contracts are vague or incomplete, behaviour becomes unreliable.
+| Command | What It Does |
+|---------|--------------|
+| `syrin analyse` | Static analysis — catches contract issues before runtime |
+| `syrin dev` | Interactive mode — see exactly what your LLM proposes |
+| `syrin test` | Contract testing — validate tools in sandboxed execution |
+| `syrin doctor` | Environment check — validate config and connections |
+| `syrin list` | Inspect tools, resources, and prompts from your server |
 
-`syrin analyse` inspects:
+---
 
-- Tool definitions
-- Parameter schemas
-- Description clarity
-- Implicit dependencies between tools
+## Global Configuration
 
-This catches issues **before runtime**.
+Syrin supports both **local** (project-specific) and **global** (user-wide) configurations. This allows you to:
 
-```bash
-syrin analyse
-```
+- Use Syrin from any directory without initializing a project
+- Share LLM API keys across multiple projects
+- Set default agent names and LLM providers globally
 
-This is especially useful in CI:
+### Quick Setup
 
 ```bash
-syrin analyse --ci
-```
+# Set up global configuration
+syrin config setup --global
 
----
+# Set API keys in global .env
+syrin config edit-env --global
 
-### Interactive Execution Inspection (`syrin dev`)
-
-`syrin dev` provides a governed chat interface for MCP servers.
+# Use Syrin from any directory
+syrin dev --exec --transport http --url http://localhost:8000/mcp
+```
 
-- Preview tool calls before execution
-- Execute tools only when explicitly enabled
-- Switch between LLM providers
-- Inspect large tool outputs safely
+### Configuration Management
 
 ```bash
-syrin dev
-```
+# View global config
+syrin config list --global
 
-Enable execution only when ready:
+# Set global LLM provider
+syrin config set openai.model "gpt-4-turbo" --global
 
-```bash
-syrin dev --exec
+# Set default provider
+syrin config set-default claude --global
 ```
 
----
+See the [Configuration Guide](docs/Commands/syrin-config.md) for more details.
 
-### Tool-Level Structural Safety Validation (`syrin test`)
+## Key Capabilities
 
-**v1.3.0 Feature**: `syrin test` now validates tool contracts through sandboxed execution.
+### `syrin analyse` — Find Problems Before They Hit Production
 
-This acts as a "hard design gate" to ensure each tool is individually safe for agent-driven systems:
+**The Problem:** Your LLM picks the wrong tool, or calls tools with missing parameters. You only find out after deployment when users report broken behavior.
 
-- **Tool Unit Contracts**: Define behavioral guarantees in `tools/<tool-name>.yaml` files
-- **Sandboxed Execution**: Tools tested in isolated environments with resource limits
-- **Behavioral Observation**: Detects side effects, non-determinism, output explosions, hidden dependencies
-- **Process Reuse**: Optimized for performance (100+ tools in 1-3 minutes)
+**The Solution:** Static analysis of your tool contracts catches issues before any code runs.
 
 ```bash
-# Validate all tools
-syrin test
-
-# Test specific tool
-syrin test --tool fetch_user
-
-# Strict mode (warnings become errors)
-syrin test --strict
-
-# JSON output for CI
-syrin test --json
+syrin analyse           # Check all tool contracts
+syrin analyse --ci      # Exit code 1 on errors (for CI pipelines)
+syrin analyse --strict  # Treat warnings as errors
 ```
 
-**Connection Testing** (legacy behavior):
+**What it catches:**
+- Vague or missing tool descriptions
+- Parameters without descriptions (LLMs guess wrong)
+- Overlapping tools that confuse model selection
+- Schema mismatches between chained tools
+- Circular dependencies
 
-```bash
-syrin test --connection
-```
+---
+
+### `syrin dev` — See What Your LLM Actually Does
 
-### Protocol and Configuration Validation
+**The Problem:** Your LLM calls tools, but you can't see *why* it chose that tool, what parameters it's sending, or what happens between steps. You're debugging blind.
 
-Before running anything, Syrin validates assumptions.
+**The Solution:** An interactive environment where you see every tool proposal before it executes.
 
 ```bash
-syrin doctor
-syrin test --connection  # Test MCP connection only
+syrin dev         # Preview mode (no execution)
+syrin dev --exec  # Enable execution when ready
 ```
 
-These commands ensure:
-
-- Configuration is valid
-- Environment variables are set
-- MCP protocol is followed correctly
+**What you get:**
+- See exactly which tool the LLM wants to call and why
+- Inspect parameters before they're sent
+- Step through tool chains one call at a time
+- Full event trace of every decision
 
 ---
 
-## Typical Workflow
+### `syrin test` — Validate Tools in Isolation
+
+**The Problem:** A tool works fine in manual testing, but in production it has side effects you didn't expect, returns massive outputs that blow your context window, or behaves differently on repeated calls.
+
+**The Solution:** Sandboxed execution that validates each tool against its behavioral contract.
 
 ```bash
-syrin init        # Initialise configuration
-syrin doctor      # Validate setup
-syrin analyse     # Static analysis of tool contracts
-syrin test        # Validate tool contracts (sandboxed execution)
-syrin test --connection  # Test MCP protocol connection
-syrin dev         # Inspect behaviour interactively
+syrin test                 # Test all tools
+syrin test --tool fetch_user  # Test specific tool
+syrin test --strict        # Warnings become errors
+syrin test --json          # JSON output for CI
 ```
 
-This workflow is designed to catch issues **before production**.
+**What it catches:**
+- Unexpected side effects (file writes, network calls)
+- Non-deterministic outputs
+- Output size explosions
+- Hidden dependencies on external state
+- Contract violations
 
 ---
 
-## Commands Overview
+### `syrin doctor` — Validate Your Setup
 
-| Command                   | Purpose                                       |
-| ------------------------- | --------------------------------------------- |
-| `syrin init`              | Initialise a Syrin project                    |
-| `syrin doctor`            | Validate configuration and environment        |
-| `syrin analyse`           | Static analysis of MCP tool contracts         |
-| `syrin test`              | Validate tool contracts (sandboxed execution) |
-| `syrin test --connection` | Test MCP protocol connection (legacy)         |
-| `syrin list`              | Inspect tools, resources, and prompts         |
-| `syrin dev`               | Interactive execution inspection              |
+**The Problem:** Something's misconfigured, but you're not sure what. API keys? Transport settings? MCP connection?
 
-Full documentation: [https://docs.syrin.dev/commands](https://docs.syrin.dev/commands)
+**The Solution:** A single command that checks everything.
+
+```bash
+syrin doctor              # Check config, env, connections
+syrin test --connection   # Test MCP connection only
+```
 
 ---
 
-## Tool Contracts (v1.3.0)
+## Tool Contracts
 
 Define behavioral guarantees for your tools in `tools/<tool-name>.yaml` files:
 
@@ -246,17 +263,12 @@ See [Tool Contracts Documentation](./docs/tool-contracts.md) for details.
 
 ## Configuration
 
-Syrin uses a single configuration file:
+Syrin supports **two configuration layers**:
 
-```bash
-syrin.yaml
-```
+- **Local** (`syrin.yaml` in project root) — transport, MCP connection, LLM providers
+- **Global** (`~/.syrin/syrin.yaml`) — shared LLM API keys and defaults across projects
 
-This file defines:
-
-- Transport type (`stdio` or `http`)
-- MCP server connection
-- Allowed LLM providers
+Local config overrides global config. CLI flags override both.
 
 Configuration reference: [https://docs.syrin.dev/configuration](https://docs.syrin.dev/configuration)
 
@@ -286,17 +298,37 @@ Provider configuration: [https://docs.syrin.dev/configuration/llm](https://docs.
 
 ---
 
+## Community
+
+- [Discord](https://discord.gg/j8GUvHybSa) — Ask questions, share feedback
+- [GitHub Discussions](https://github.com/Syrin-Labs/cli/discussions) — Feature ideas, show & tell
+- [Documentation](https://docs.syrin.dev) — Full guides and API reference
+
+Found a bug or have a feature request? [Open an issue](https://github.com/Syrin-Labs/cli/issues) — we read every one.
+
+If Syrin helped you catch something your logs missed, a [star on GitHub](https://github.com/Syrin-Labs/cli) helps others find it too.
+
+---
+
 ## Links
 
 - Documentation: [https://docs.syrin.dev](https://docs.syrin.dev)
-- GitHub: [https://github.com/syrin-labs/cli](https://github.com/syrin-labs/cli)
-- Issues: [https://github.com/syrin-labs/cli/issues](https://github.com/syrin-labs/cli/issues)
+- GitHub: [https://github.com/Syrin-Labs/cli](https://github.com/Syrin-Labs/cli)
+- Issues: [https://github.com/Syrin-Labs/cli/issues](https://github.com/Syrin-Labs/cli/issues)
 - npm: [https://www.npmjs.com/package/@syrin/cli](https://www.npmjs.com/package/@syrin/cli)
 
 ---
 
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before submitting PRs.
+
+For security issues, please see our [Security Policy](SECURITY.md).
+
+---
+
 ## License
 
-ISC License. See LICENSE for details.
+ISC License. See [LICENSE](LICENSE) for details.
 
-Made with ❤️ by **Syrin Labs**.
+Made with care by **Syrin Labs**.

package/dist/cli/commands/config.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `syrin config` command implementation.
+ * Manages both local and global Syrin configurations.
+ */
+export interface ConfigCommandOptions {
+    /** Operate on global config */
+    global?: boolean;
+    /** Operate on local config */
+    local?: boolean;
+    /** Key to get/set (e.g., "openai.model", "agent_name") */
+    key?: string;
+    /** Value to set */
+    value?: string;
+}
+/**
+ * Execute config set command.
+ */
+export declare function executeConfigSet(key: string, value: string, options?: ConfigCommandOptions, projectRoot?: string): Promise<void>;
+/**
+ * Execute config get command.
+ */
+export declare function executeConfigGet(key: string, options?: ConfigCommandOptions, projectRoot?: string): Promise<void>;
+/**
+ * Execute config list command.
+ */
+export declare function executeConfigList(options?: ConfigCommandOptions, projectRoot?: string): Promise<void>;
+/**
+ * Execute config show command (same as list for now).
+ */
+export declare function executeConfigShow(options?: ConfigCommandOptions, projectRoot?: string): Promise<void>;
+/**
+ * Execute config edit command.
+ */
+export declare function executeConfigEdit(options?: ConfigCommandOptions, projectRoot?: string): Promise<void>;
+/**
+ * Execute config edit-env command.
+ */
+export declare function executeConfigEditEnv(options?: ConfigCommandOptions, projectRoot?: string): Promise<void>;
+/**
+ * Execute config set-default command.
+ */
+export declare function executeConfigSetDefault(provider: string, options?: ConfigCommandOptions, projectRoot?: string): Promise<void>;
+/**
+ * Execute config remove command.
+ */
+export declare function executeConfigRemove(provider: string, options?: ConfigCommandOptions, projectRoot?: string): Promise<void>;
+//# sourceMappingURL=config.d.ts.map