UTCP CLI Plugin
Command-line interface plugin for UTCP, enabling integration with command-line tools and processes.
Features
- 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_ENDplaceholder 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
- Timeout Management: Configurable execution timeouts
- Error Handling: Comprehensive subprocess error management
Installation
pip install utcp-cli
Quick Start
from utcp.utcp_client import UtcpClient
# Multi-step CLI tool
client = await UtcpClient.create(config={
"manual_call_templates": [{
"name": "file_analysis",
"call_template_type": "cli",
"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_analysis.count_python_files", {"target_dir": "/project"})
Configuration Examples
Basic Multi-Command Operation
{
"name": "file_analysis",
"call_template_type": "cli",
"commands": [
{
"command": "cd UTCP_ARG_target_dir_UTCP_END",
"append_to_final_output": false
},
{
"command": "ls -la"
}
],
"working_dir": "/tmp"
}
With Environment Variables and Output Control
{
"name": "python_pipeline",
"call_template_type": "cli",
"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}"
}
}
Cross-Platform Git Operations
{
"name": "git_analysis",
"call_template_type": "cli",
"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"
}
}
Referencing Previous Command Output
{
"name": "conditional_processor",
"call_template_type": "cli",
"commands": [
{
"command": "git status --porcelain",
"append_to_final_output": false
},
{
"command": "echo \"Changes detected: $CMD_0_OUTPUT\"",
"append_to_final_output": true
}
]
}
Cross-Platform Considerations
Command Syntax
Commands should use appropriate syntax for the target platform:
Windows (PowerShell):
{
"commands": [
{"command": "Get-ChildItem UTCP_ARG_path_UTCP_END"},
{"command": "Set-Location UTCP_ARG_dir_UTCP_END"}
]
}
Unix/Linux/macOS (Bash):
{
"commands": [
{"command": "ls -la UTCP_ARG_path_UTCP_END"},
{"command": "cd UTCP_ARG_dir_UTCP_END"}
]
}
Universal Commands
Some commands work across platforms:
{
"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
from utcp.exceptions import ToolCallError
try:
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:
print(f"CLI tool execution failed: {e}")
# Script execution failed - check individual command outputs
Common Use Cases
- 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
import pytest
from utcp.utcp_client import UtcpClient
@pytest.mark.asyncio
async def test_multi_command_cli_tool():
client = await UtcpClient.create(config={
"manual_call_templates": [{
"name": "test_cli",
"call_template_type": "cli",
"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_chain", {"message": "hello"})
assert "Previous: hello" in result
Related Documentation
Examples
For complete examples, see the UTCP examples repository.
Metadata
Release files for utcp-cli 1.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| utcp_cli-1.1.5.tar.gz | 30.5 kB | Without provenance | Details for utcp_cli-1.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| utcp_cli-1.1.5-py3-none-any.whl | Python 3 | none | any | Details for utcp_cli-1.1.5-py3-none-any.whl |
Total release size: 49.7 kB
Release files / utcp_cli-1.1.5.tar.gz
| Download URL | utcp_cli-1.1.5.tar.gz |
|---|---|
| Size | 30.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
92eca0a458c1a5b95b439c4417f39c7a4145416720063bc535d4f65edde9460d
|
|
BLAKE2b-256 checksum How to use checksums |
12448ddd90d52d69df39400cb9378206f0437e6cb2d66934bf485de9c2a39924
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Release files / utcp_cli-1.1.5-py3-none-any.whl
| Download URL | utcp_cli-1.1.5-py3-none-any.whl |
|---|---|
| Size | 19.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f10225feb7d60ba0cec296a124b93c8116814e4728d2f07a5697a00bfe621c61
|
|
BLAKE2b-256 checksum How to use checksums |
fb093854bbf836dab995f7fea6c5eef9f521788f0089197a0b16b53096cd79de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Security for utcp-cli 1.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.