Package Exports
- @xec-sh/core
- @xec-sh/core/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@xec-sh/core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
@xec-sh/core
Universal execution engine providing a unified API for running commands across local, SSH, Docker, and Kubernetes environments.
Installation
npm install @xec-sh/coreDocumentation
Features
- Universal API - Same syntax works everywhere
- Template Literals - Safe command interpolation with automatic escaping
- Type Safety - Full TypeScript support with IntelliSense
- Streaming - Real-time output without buffering
- Connection Pooling - Automatic SSH connection reuse
- Error Handling - Result-based pattern with detailed context
Basic Usage
import { $ } from '@xec-sh/core';
// Local execution
await $`echo "Hello, World!"`;
// Variables are automatically escaped
const filename = "file with spaces.txt";
await $`touch ${filename}`;
// Error handling
const result = await $`grep pattern file.txt`.nothrow();
if (!result.isSuccess()) {
console.log('Pattern not found');
}Execution Adapters
SSH
const ssh = $.ssh({ host: 'server.com', username: 'user' });
// Execute commands
await ssh`uname -a`;
await ssh`df -h`;
// File transfer
await ssh.uploadFile('./local.txt', '/remote/path.txt');
await ssh.downloadFile('/remote/file.txt', './local-copy.txt');
// SSH tunnels
const tunnel = await ssh.tunnel({
localPort: 5433,
remoteHost: 'localhost',
remotePort: 5432
});Docker
// Execute in existing container
const docker = $.docker({ container: 'my-app' });
await docker`ps aux`;
// Create new container
const container = await $.docker({
image: 'node:18',
name: 'test-container'
}).start();
await container.exec`npm test`;
await container.stop();
await container.remove();Kubernetes
const k8s = $.k8s({ namespace: 'default' });
const pod = k8s.pod('my-app-pod');
// Execute commands
await pod.exec`hostname`;
// Stream logs
await pod.follow(line => console.log(line));
// Port forwarding
const forward = await pod.portForward(8080, 80);
console.log(`Access at localhost:${forward.localPort}`);Advanced Features
Parallel Execution
import { parallel } from '@xec-sh/core';
const results = await parallel([
$`npm install`,
$`npm run build`,
$`npm test`
], { maxConcurrent: 2 });Configuration
// Global configuration
import { configure } from '@xec-sh/core';
configure({
shell: '/bin/bash',
timeout: 30000,
env: { NODE_ENV: 'production' }
});
// Per-command configuration
await $`npm test`
.cwd('/app')
.env({ NODE_ENV: 'test' })
.timeout(60000)
.retry(3);Event System
$.on('command:start', (event) => {
console.log(`Starting: ${event.command}`);
});
$.on('command:error', (event) => {
console.error(`Failed: ${event.error.message}`);
});API Reference
Core Functions
$- Main execution function$.ssh()- SSH adapter$.docker()- Docker adapter$.k8s()- Kubernetes adapterconfigure()- Global configurationparallel()- Parallel execution
Utilities
escapeShellArg()- Shell argument escapingquoteShellArg()- Shell argument quotingRuntimeDetector- Runtime detectionProcessPromise- Promise-based process handling
More Documentation
Contributing
Links
License
MIT © Xec Contributors