⚡ CLI Execution Agent

SLM CLI Agent

Lightweight shell helper that translates natural language commands to safe, platform-specific shell scripts and executes them locally on CPU with built-in command security constraints.

💻 Installation

Terminal

              # Install in editable mode locally
pip install -e ./slm_cli_agent

# Set performance environment parameters
export SLM_CLI_AGENT_N_THREADS=4
export SLM_CLI_AGENT_N_CTX=2048
            

🐙 Checkout from GitHub

Clone only this agent's folder from the monorepo using Git sparse-checkout — no need to download the full repository:

Option 1 — Sparse Checkout (Recommended)

Terminal — Git Sparse Checkout

              # 1. Create and enter a new directory
$ mkdir slm_cli_agent && cd slm_cli_agent

# 2. Initialise empty git repo and add remote
$ git init
$ git remote add origin https://github.com/t00114218-stack/SLMAgents.git

# 3. Enable sparse-checkout and set target folder
$ git sparse-checkout init --cone
$ git sparse-checkout set slm_cli_agent

# 4. Pull only that agent's source
$ git pull origin main
            

Option 2 — Full Repository Clone

Terminal — Full Clone

              $ git clone https://github.com/t00114218-stack/SLMAgents.git
$ cd SLMAgents/slm_cli_agent
            

💡 Tip: After checkout, install the package locally with pip install -e ./slm_cli_agent to run in editable mode without publishing to PyPI.

⚙️ Configuration API

Constructor Parameters

Parameter	Type / Default	Description
model_path	str \| None	Explicit path to the ONNX model directory. Defaults to caching/sharing the main model in the monorepo.
cache_dir	str \| None	HF model directory path. Also settable via SLM_CLI_AGENT_CACHE_DIR.
n_ctx	int \| 2048	Context window size in tokens. Also settable via SLM_CLI_AGENT_N_CTX.
n_threads	int \| 4	CPU threads for ONNX Runtime. Also settable via SLM_CLI_AGENT_N_THREADS.
system_prompt	str \| None	Optional custom system prompt instructions overriding the default template.
user_input	str \| None	Optional additional user-supplied target parameters or variables.

generate_command() Parameters

Parameter	Type / Default	Description
query	str	Required. Natural language description of what you want to achieve.
stream	bool \| False	If True, enables token streaming of the model's explanation and thinking process. Returns a Python generator.
system_prompt	str \| None	Optional custom system prompt instructions overriding the default template.
user_input	str \| None	Optional additional user-supplied target parameters or variables.

Python Quick Start

              from slm_cli_agent.cli_agent import SLMCLIAgent
 
agent = SLMCLIAgent()
 
# Generate command from query
cmd, explanation = agent.generate_command("find all files ending with .py in current folder")
print(cmd)
# Output: find . -name "*.py"
            

Unified Command Execution (`run()`)

For convenience, you can translate and execute shell instructions in a single method call:

Unified Execution

              result = agent.run("list directory contents in clean format")
print(f"Executed Command: {result['command']}")
print(f"Success: {result['success']}")
print(f"Output:\n{result['stdout']}")
            

Safe Command Execution

The CLI Agent provides a safe command execution API that screens script blocks for destructive patterns prior to invoking them in the local environment.

Executing Command

              code, stdout, stderr = agent.execute_command("echo 'Hello CLI Agent'")
print(f"Return code: {code}")
print(f"Stdout: {stdout}")
            

⚠️ Dry-Run Checks: Destructive patterns (e.g. rm -rf /, mkfs, dd if=, shutdown) are caught by the protection engine, resulting in a return code of -1 and an error returned to prevent command-line accidents.

Complex Command Pipelines

The CLI Agent handles complex natural language requirements involving multiple nested operations, pipes, file redirections, and limits:

Pipeline Example

              query = (
    "Find all files in /var/log ending with .log modified in the last 7 days, "
    "search them for the term 'ERROR' case-insensitively, count the matching "
    "lines for each file, sort the count descending, and output the top 5 records "
    "while ignoring permission denied errors."
)
result = agent.run(query)
print(result["command"])
            

Resulting Bash Pipeline:

find /var/log -type f -name "*.log" -mtime -7 2>/dev/null | xargs grep -io "ERROR" 2>/dev/null | cut -d: -f1 | sort | uniq -c | sort -rn | head -n 5

Security & Hardening

🔒 Restricted Access: While the agent blocks common destructive commands, always review the generated script before execution. It is highly recommended to run the agent in environment profiles with restricted write access and minimal administrative rights.