Merge pull request #61 "Update CLI" from universal-tool-calling-protocol/dev

Update CLI

Author: h3xxit

README.md

@@ -437,17 +437,35 @@ Note the name change from `http_stream` to `streamable_http`.
 
 ```json
 {
-  "name": "my_cli_tool",
+  "name": "multi_step_cli_tool",
   "call_template_type": "cli", // Required
-  "command_name": "my-command --utcp", // Required
+  "commands": [ // Required - sequential command execution
+    {
+      "command": "git clone UTCP_ARG_repo_url_UTCP_END temp_repo",
+      "append_to_final_output": false
+    },
+    {
+      "command": "cd temp_repo && find . -name '*.py' | wc -l"
+      // Last command output returned by default
+    }
+  ],
   "env_vars": { // Optional
-    "MY_VAR": "my_value"
+    "GIT_AUTHOR_NAME": "UTCP Bot",
+    "API_KEY": "${MY_API_KEY}"
   },
-  "working_dir": "/path/to/working/directory", // Optional
+  "working_dir": "/tmp", // Optional
   "auth": null // Optional (always null for CLI)
 }
 ```
 
+**CLI Protocol Features:**
+- **Multi-command execution**: Commands run sequentially in single subprocess
+- **Cross-platform**: PowerShell on Windows, Bash on Unix/Linux/macOS  
+- **State preservation**: Directory changes (`cd`) persist between commands
+- **Argument placeholders**: `UTCP_ARG_argname_UTCP_END` format
+- **Output referencing**: Access previous outputs with `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`
+- **Flexible output control**: Choose which command outputs to include in final result
+
 ### Text Call Template
 
 ```json

core/README.md

@@ -439,7 +439,16 @@ Note the name change from `http_stream` to `streamable_http`.
 {
   "name": "my_cli_tool",
   "call_template_type": "cli", // Required
-  "command_name": "my-command --utcp", // Required
+  "commands": [ // Required - array of commands to execute in sequence
+    {
+      "command": "cd UTCP_ARG_target_dir_UTCP_END",
+      "append_to_final_output": false // Optional, default is false if not last command
+    },
+    {
+      "command": "my-command --input UTCP_ARG_input_file_UTCP_END"
+      // append_to_final_output defaults to true for last command
+    }
+  ],
   "env_vars": { // Optional
     "MY_VAR": "my_value"
   },
@@ -448,6 +457,12 @@ Note the name change from `http_stream` to `streamable_http`.
 }
 ```
 
+**Notes:**
+- Commands execute in a single subprocess (PowerShell on Windows, Bash on Unix)
+- Use `UTCP_ARG_argname_UTCP_END` placeholders for arguments
+- Reference previous command output with `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`, etc.
+- Only the last command's output is returned by default
+
 ### Text Call Template
 
 ```json

core/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "utcp"
-version = "1.0.2"
+version = "1.0.4"
 authors = [
   { name = "UTCP Contributors" },
 ]

core/tests/client/test_utcp_client.py

@@ -147,7 +147,7 @@ async def sample_tools():
 
     cli_call_template = CliCallTemplate(
         name="test_cli_provider",
-        command_name="echo",
+        commands=[{"command": "echo UTCP_ARG_command_UTCP_END"}],
         call_template_type="cli"
     )
 
@@ -496,7 +496,7 @@ async def test_load_manual_call_templates_from_file(self, isolated_communication
                 {
                     "name": "cli_template",
                     "call_template_type": "cli",
-                    "command_name": "echo"
+                    "commands": [{"command": "echo UTCP_ARG_message_UTCP_END"}]
                 }
             ]
         }

plugins/communication_protocols/cli/README.md

@@ -6,13 +6,16 @@ Command-line interface plugin for UTCP, enabling integration with command-line t
 
 ## Features
 
-- **Command Execution**: Run any command-line tool as a UTCP tool
+- **Multi-Command Execution**: Execute multiple commands sequentially in a single subprocess
+- **State Preservation**: Directory changes and environment persist between commands
+- **Cross-Platform Script Generation**: PowerShell on Windows, Bash on Unix/Linux/macOS
+- **Flexible Output Control**: Choose which command outputs to include in final result
+- **Argument Substitution**: `UTCP_ARG_argname_UTCP_END` placeholder system
+- **Output Referencing**: Access previous command outputs with `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`
 - **Environment Variables**: Secure credential and configuration passing
 - **Working Directory Control**: Execute commands in specific directories
-- **Input/Output Handling**: Support for stdin, stdout, stderr processing
-- **Cross-Platform**: Works on Windows, macOS, and Linux
 - **Timeout Management**: Configurable execution timeouts
-- **Argument Validation**: Optional input sanitization
+- **Error Handling**: Comprehensive subprocess error management
 
 ## Installation
 
@@ -25,109 +28,184 @@ pip install utcp-cli
 ```python
 from utcp.utcp_client import UtcpClient
 
-# Basic CLI tool
+# Multi-step CLI tool
 client = await UtcpClient.create(config={
     "manual_call_templates": [{
-        "name": "file_tools",
+        "name": "file_analysis",
         "call_template_type": "cli",
-        "command_name": "ls -la ${path}"
+        "commands": [
+            {
+                "command": "cd UTCP_ARG_target_dir_UTCP_END",
+                "append_to_final_output": false
+            },
+            {
+                "command": "find . -type f -name '*.py' | wc -l"
+            }
+        ]
     }]
 })
 
-result = await client.call_tool("file_tools.list", {"path": "/home"})
+result = await client.call_tool("file_analysis.count_python_files", {"target_dir": "/project"})
 ```
 
 ## Configuration Examples
 
-### Basic Command
+### Basic Multi-Command Operation
 ```json
 {
-  "name": "file_ops",
+  "name": "file_analysis",
   "call_template_type": "cli",
-  "command_name": "ls -la ${path}",
+  "commands": [
+    {
+      "command": "cd UTCP_ARG_target_dir_UTCP_END",
+      "append_to_final_output": false
+    },
+    {
+      "command": "ls -la"
+    }
+  ],
   "working_dir": "/tmp"
 }
 ```
 
-### With Environment Variables
+### With Environment Variables and Output Control
 ```json
 {
-  "name": "python_script",
+  "name": "python_pipeline",
   "call_template_type": "cli",
-  "command_name": "python script.py ${input}",
+  "commands": [
+    {
+      "command": "python setup.py install",
+      "append_to_final_output": false
+    },
+    {
+      "command": "python script.py --input UTCP_ARG_input_file_UTCP_END --result \"$CMD_0_OUTPUT\"",
+      "append_to_final_output": true
+    }
+  ],
   "env_vars": {
     "PYTHONPATH": "/custom/path",
     "API_KEY": "${API_KEY}"
   }
 }
 ```
 
-### Processing JSON with jq
+### Cross-Platform Git Operations
 ```json
 {
-  "name": "json_processor",
+  "name": "git_analysis",
   "call_template_type": "cli",
-  "command_name": "jq '.data'",
-  "stdin": "${json_input}",
-  "timeout": 10
+  "commands": [
+    {
+      "command": "git clone UTCP_ARG_repo_url_UTCP_END temp_repo",
+      "append_to_final_output": false
+    },
+    {
+      "command": "cd temp_repo",
+      "append_to_final_output": false  
+    },
+    {
+      "command": "git log --oneline -10",
+      "append_to_final_output": true
+    },
+    {
+      "command": "echo \"Repository has $(find . -name '*.py' | wc -l) Python files\"",
+      "append_to_final_output": true
+    }
+  ],
+  "env_vars": {
+    "GIT_AUTHOR_NAME": "UTCP Bot",
+    "GIT_AUTHOR_EMAIL": "bot@utcp.dev"
+  }
 }
 ```
 
-### Git Operations
+### Referencing Previous Command Output
 ```json
 {
-  "name": "git_tools",
+  "name": "conditional_processor",
   "call_template_type": "cli",
-  "command_name": "git ${operation} ${args}",
-  "working_dir": "${repo_path}",
-  "env_vars": {
-    "GIT_AUTHOR_NAME": "${author_name}",
-    "GIT_AUTHOR_EMAIL": "${author_email}"
-  }
+  "commands": [
+    {
+      "command": "git status --porcelain",
+      "append_to_final_output": false
+    },
+    {
+      "command": "echo \"Changes detected: $CMD_0_OUTPUT\"",
+      "append_to_final_output": true
+    }
+  ]
 }
 ```
 
-## Security Considerations
+## Cross-Platform Considerations
 
-- Commands run in isolated subprocesses
-- Environment variables provide secure credential passing
-- Working directory restrictions limit file system access
-- Input validation prevents command injection
+### Command Syntax
+Commands should use appropriate syntax for the target platform:
 
+**Windows (PowerShell):**
 ```json
 {
-  "name": "safe_grep",
-  "call_template_type": "cli",
-  "command_name": "grep ${pattern} ${file}",
-  "working_dir": "/safe/directory",
-  "allowed_args": {
-    "pattern": "^[a-zA-Z0-9_-]+$",
-    "file": "^[a-zA-Z0-9_./-]+\\.txt$"
-  }
+  "commands": [
+    {"command": "Get-ChildItem UTCP_ARG_path_UTCP_END"},
+    {"command": "Set-Location UTCP_ARG_dir_UTCP_END"}
+  ]
 }
 ```
 
+**Unix/Linux/macOS (Bash):**
+```json
+{
+  "commands": [
+    {"command": "ls -la UTCP_ARG_path_UTCP_END"},
+    {"command": "cd UTCP_ARG_dir_UTCP_END"}
+  ]
+}
+```
+
+### Universal Commands
+Some commands work across platforms:
+```json
+{
+  "commands": [
+    {"command": "git status"},
+    {"command": "python --version"},
+    {"command": "node -v"}
+  ]
+}
+```
+
+## Security Considerations
+
+- Commands execute in isolated subprocesses with controlled environment
+- Environment variables provide secure credential passing
+- Previous command outputs should be used carefully to avoid injection
+- Commands should use platform-appropriate syntax
+
 ## Error Handling
 
 ```python
 from utcp.exceptions import ToolCallError
-import subprocess
 
 try:
-    result = await client.call_tool("cli_tool.command", {"arg": "value"})
+    result = await client.call_tool("cli_tool.multi_command", {
+        "repo_url": "https://github.com/example/repo.git",
+        "target_dir": "analysis_temp"
+    })
 except ToolCallError as e:
-    if isinstance(e.__cause__, subprocess.CalledProcessError):
-        print(f"Command failed with exit code {e.__cause__.returncode}")
-        print(f"stderr: {e.__cause__.stderr}")
+    print(f"CLI tool execution failed: {e}")
+    # Script execution failed - check individual command outputs
 ```
 
 ## Common Use Cases
 
-- **File Operations**: ls, find, grep, awk, sed
-- **Data Processing**: jq, sort, uniq, cut
-- **System Monitoring**: ps, top, df, netstat
-- **Development Tools**: git, npm, pip, docker
-- **Custom Scripts**: Python, bash, PowerShell scripts
+- **Multi-step Builds**: setup → compile → test → package
+- **Git Workflows**: clone → analyze → commit → push  
+- **Data Pipelines**: fetch → transform → validate → output
+- **File Operations**: navigate → search → process → report
+- **Development Tools**: install dependencies → run tests → generate docs
+- **System Administration**: check status → backup → cleanup → verify
+- **Custom Workflows**: Any sequence of command-line operations
 
 ## Testing CLI Tools
 
@@ -136,17 +214,25 @@ import pytest
 from utcp.utcp_client import UtcpClient
 
 @pytest.mark.asyncio
-async def test_cli_tool():
+async def test_multi_command_cli_tool():
     client = await UtcpClient.create(config={
         "manual_call_templates": [{
             "name": "test_cli",
             "call_template_type": "cli",
-            "command_name": "echo ${message}"
+            "commands": [
+                {
+                    "command": "echo UTCP_ARG_message_UTCP_END",
+                    "append_to_final_output": false
+                },
+                {
+                    "command": "echo \"Previous: $CMD_0_OUTPUT\""
+                }
+            ]
         }]
     })
 
-    result = await client.call_tool("test_cli.echo", {"message": "hello"})
-    assert "hello" in result["stdout"]
+    result = await client.call_tool("test_cli.echo_chain", {"message": "hello"})
+    assert "Previous: hello" in result
 ```
 
 ## Related Documentation

plugins/communication_protocols/cli/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "utcp-cli"
-version = "1.0.2"
+version = "1.1.0"
 authors = [
   { name = "UTCP Contributors" },
 ]