Package Exports
- @cmdop/node
Readme
@cmdop/node
Node.js SDK for CMDOP agent interaction via gRPC.
Installation
npm install @cmdop/node
# or
pnpm add @cmdop/node
# or
yarn add @cmdop/nodeRequirements: Node.js >= 18.0.0
Quick Start
import { CMDOPClient } from '@cmdop/node';
// Connect to local agent (auto-discovery)
const client = await CMDOPClient.local();
// Or connect via cloud relay
const client = await CMDOPClient.remote('cmdop_live_xxx');
// Create a terminal session
const session = await client.terminal.create({ cols: 120, rows: 40 });
console.log('Session ID:', session.sessionId);
// Send input
await client.terminal.sendInput(session.sessionId, 'echo "Hello World"\n');
// Cleanup
await client.terminal.close(session.sessionId);
await client.close();Features
Terminal Service
Full PTY terminal control:
// Create session
const session = await client.terminal.create({
cols: 120,
rows: 40,
shell: '/bin/bash',
cwd: '/home/user',
env: { MY_VAR: 'value' },
});
// Send input
await client.terminal.sendInput(session.sessionId, 'ls -la\n');
// Resize
await client.terminal.resize(session.sessionId, 200, 50);
// Send signal (e.g., Ctrl+C)
await client.terminal.signal(session.sessionId, 2); // SIGINT
// Get session history
const history = await client.terminal.getHistory(session.sessionId);
// List all sessions
const { sessions } = await client.terminal.list();
// Close session
await client.terminal.close(session.sessionId);Files Service
File system operations:
// List directory
const files = await client.files.list(session.sessionId, '/tmp');
// Read file
const content = await client.files.read(session.sessionId, '/tmp/file.txt');
// Write file
await client.files.write(session.sessionId, '/tmp/new.txt', 'Hello World');
// File info
const stat = await client.files.stat(session.sessionId, '/tmp/file.txt');
// Create directory
await client.files.mkdir(session.sessionId, '/tmp/newdir');
// Move/Copy
await client.files.move(session.sessionId, '/tmp/old.txt', '/tmp/new.txt');
await client.files.copy(session.sessionId, '/tmp/src.txt', '/tmp/dst.txt');
// Delete
await client.files.delete(session.sessionId, '/tmp/file.txt');
// Search files
const results = await client.files.search(session.sessionId, '/tmp', '*.log');
// Create archive
await client.files.archive(session.sessionId, '/tmp/archive.tar.gz', ['/tmp/dir']);Agent Service
AI-powered command execution:
// Run agent with natural language
const result = await client.agent.run(session.sessionId, 'List all files in /tmp');
console.log(result.text);
console.log(result.toolResults); // Tool execution details
console.log(result.usage); // Token usage
// Structured data extraction
interface FileList {
files: string[];
count: number;
}
const data = await client.agent.extract<FileList>(
session.sessionId,
'List files in /tmp and count them',
JSON.stringify({
type: 'object',
properties: {
files: { type: 'array', items: { type: 'string' } },
count: { type: 'number' },
},
})
);
console.log(data.files, data.count);Connection Types
Local Connection
Connects to the local CMDOP agent via Unix socket (Linux/macOS) or Named Pipe (Windows):
const client = await CMDOPClient.local();The agent is auto-discovered from ~/.cmdop/agent.info.
Remote Connection
Connects via CMDOP cloud relay with API key authentication:
const client = await CMDOPClient.remote('cmdop_live_xxx');
// Or with agent ID for specific machine
const client = await CMDOPClient.remote('cmdop_live_xxx', {
agentId: 'agent-uuid',
});Resource Management
Using Symbol.asyncDispose (TypeScript 5.2+):
await using client = await CMDOPClient.local();
// Client automatically closed when leaving scopeOr manual cleanup:
const client = await CMDOPClient.local();
try {
// ... use client
} finally {
await client.close();
}Error Handling
import {
CMDOPError,
ConnectionError,
AuthenticationError,
SessionError,
TimeoutError,
NotFoundError,
PermissionError,
} from '@cmdop/node';
try {
await client.terminal.sendInput(sessionId, 'command\n');
} catch (error) {
if (error instanceof SessionError) {
console.log('Session not found or closed');
} else if (error instanceof TimeoutError) {
console.log('Operation timed out');
} else if (error instanceof PermissionError) {
console.log('Permission denied');
}
}Related Packages
- @cmdop/core - Shared types and configuration
- @cmdop/react - React hooks for browser-based interaction
Documentation
For full documentation, visit https://cmdop.com/docs
License
MIT