CLI Executor

Execute shell commands, run scripts, and manage files for AgentOS agents. This is one of the two fundamental primitives (along with Web Browser) that enables recursive self-building agent capabilities.

Features

• Shell Execution: Run any shell command with output capture
• File Management: Read, write, and list files/directories
• Security Controls: Dangerous command detection and blocking
• Cross-Platform: Works on Windows, macOS, and Linux

Installation

npm install @framers/agentos-ext-cli-executor

Quick Start

import { createExtensionPack } from '@framers/agentos-ext-cli-executor';
import { ExtensionManager } from '@framers/agentos';

const extensionManager = new ExtensionManager();

// Register the CLI extension
extensionManager.register(createExtensionPack({
  options: {
    defaultShell: 'bash',
    timeout: 60000,
    blockedCommands: ['rm -rf /', 'format']
  },
  logger: console
}));

Tools

shell_execute

Execute a shell command.

const result = await gmi.executeTool('shell_execute', {
  command: 'npm install lodash',
  cwd: '/path/to/project',
  timeout: 30000
});
// Returns: { command, exitCode, stdout, stderr, duration, success }

file_read

Read file contents.

const result = await gmi.executeTool('file_read', {
  path: './package.json',
  encoding: 'utf-8'
});
// Returns: { path, content, size, truncated, encoding }

// Read last 50 lines
const logs = await gmi.executeTool('file_read', {
  path: './app.log',
  lines: 50,
  fromEnd: true
});

file_write

Write content to a file.

const result = await gmi.executeTool('file_write', {
  path: './config.json',
  content: JSON.stringify({ key: 'value' }),
  createDirs: true
});
// Returns: { path, bytesWritten, created, appended }

list_directory

List directory contents.

const result = await gmi.executeTool('list_directory', {
  path: './src',
  recursive: true,
  pattern: '*.ts',
  includeStats: true
});
// Returns: { path, entries: [{ name, path, type, size, ... }], count }

Security

The extension includes built-in security controls:

Dangerous Pattern Detection

Commands matching these patterns are blocked by default:

• rm -rf / (recursive delete root)
• format C: (format drives)
• Fork bombs
• Direct disk writes
• System shutdown/reboot commands

Custom Blocklists

createExtensionPack({
  options: {
    blockedCommands: ['sudo', 'su', 'chmod 777'],
    allowedCommands: ['npm', 'node', 'python', 'git'] // Whitelist mode
  }
});

Disabling Safety Checks (Dangerous)

If you need full control (for example, in a locked-down container or local dev), you can disable all command safety checks:

createExtensionPack({
  options: {
    dangerouslySkipSecurityChecks: true
  }
});

Risk Assessment

Each command is assessed for risk level:

Risk Level	Examples
safe	ls, cat, npm list
low	echo "text" > file.txt
medium	rm file.txt, eval
high	sudo, `curl
critical	rm -rf /, blocked patterns

Configuration

Option	Type	Default	Description
defaultShell	string	auto	Shell to use (bash, powershell, cmd, zsh)
timeout	number	60000	Default timeout (ms)
workingDirectory	string	process.cwd()	Default working directory
allowedCommands	string[]	[]	Command whitelist (empty = all)
blockedCommands	string[]	[]	Command blacklist (additional to built-in dangerous patterns)
dangerouslySkipSecurityChecks	boolean	false	Disable all command safety checks (use only in trusted environments)
env	object	{}	Environment variables

Use Cases

Code Generation and Execution

// Write generated code
await gmi.executeTool('file_write', {
  path: './generated/app.py',
  content: generatedPythonCode,
  createDirs: true
});

// Execute it
await gmi.executeTool('shell_execute', {
  command: 'python ./generated/app.py',
  timeout: 30000
});

Project Setup

// Create project structure
await gmi.executeTool('shell_execute', {
  command: 'npx create-react-app my-app --template typescript'
});

// Install dependencies
await gmi.executeTool('shell_execute', {
  command: 'npm install axios lodash',
  cwd: './my-app'
});

Log Analysis

// Read recent logs
const logs = await gmi.executeTool('file_read', {
  path: '/var/log/app.log',
  lines: 100,
  fromEnd: true
});

// Parse and analyze
const errorCount = logs.output.content.match(/ERROR/g)?.length || 0;

The Two Primitives Theory

This extension, combined with the Web Browser extension, provides the two fundamental capabilities needed for a recursive self-building agent:

1. CLI Executor (this extension)

   • Execute arbitrary code
   • Manage files
   • Install dependencies
   • Run tests and builds

2. Web Browser (see web-browser extension)

   • Search for information
   • Read documentation
   • Learn new techniques
   • Verify implementations

Together, an intelligent agent can:

1. Identify what it needs to learn → Web search
2. Find documentation/tutorials → Web scraping
3. Write code → File write
4. Execute and test → Shell execute
5. Debug and iterate → Repeat

License

MIT © Frame.dev