Xec - Universal Command Execution System

Universal command execution for the modern stack - A unified TypeScript API for seamless command execution across local, SSH, Docker, and Kubernetes environments.

🎯 The Problem

Modern infrastructure spans multiple environments, each requiring different tools and APIs. This fragmentation leads to duplicated code, context switching, inconsistent error handling, and complex deployment scripts.

✨ The Solution

Xec provides one API to rule them all - the same intuitive template literal syntax works everywhere:

import { $ } from '@xec-sh/core';

// Same API, different environments
await $`npm test`;                                    // Local execution
await $.ssh('server.com')`npm test`;                 // SSH execution
await $.docker({ container: 'app' })`npm test`;      // Docker execution
await $.k8s({ pod: 'app-pod' })`npm test`;          // Kubernetes execution

🚀 Features

Core Capabilities

• 🌍 Universal Execution Engine - Single API for all environments
• 📝 Template Literal Magic - Natural command syntax with $\command``
• 🔄 Multi-Environment Native - Local, SSH, Docker, Kubernetes adapters
• ⚡ Enterprise Performance - Connection pooling, parallel execution, streaming
• 🔒 Type-Safe Everything - Full TypeScript with IntelliSense
• 🛡️ Production Ready - Automatic retries, proper error handling, secure by default

v0.8.0 Highlights

• Enhanced Configuration System - Interactive config management with custom parameters
• Script Context Revolution - Automatic $target injection for write-once, run-anywhere scripts
• Module Loading 2.0 - CDN module support (npm, jsr, esm.sh, unpkg)
• Documentation Precision - Every feature verified against implementation

📦 Installation

# Install CLI globally
npm install -g @xec-sh/cli

# Or add to your project
npm install @xec-sh/core

🎮 Quick Start

Basic Usage

import { $ } from '@xec-sh/core';

// Simple command execution
const result = await $`ls -la`;
console.log(result.stdout);

// With error handling
if (result.ok) {
  console.log('Success!');
} else {
  console.error(`Failed: ${result.cause}`);
}

Method Chaining

await $`npm test`
  .cwd('/project')
  .env({ NODE_ENV: 'test' })
  .timeout(30000)
  .retry(3);

Multi-Environment Execution

// SSH with connection pooling
const server = $.ssh({ 
  host: 'prod.example.com',
  username: 'deploy'
});
await server`docker restart app`;

// Docker with auto-cleanup
await $.docker({ image: 'node:20' })`npm test`;

// Kubernetes with namespace
const k8s = $.k8s({ namespace: 'production' });
await k8s.pod('api-server')`date`;

Write Once, Run Anywhere

New in v0.8.0 - Scripts automatically adapt to their execution context:

// script.ts - works in ANY environment
await $target`npm install`;
await $target`npm test`;
await $target`npm run build`;

Execute the same script everywhere:

xec run script.ts                    # Local execution
xec on server.com script.ts          # SSH execution
xec in container-name script.ts      # Docker execution
xec in pod:app-pod script.ts        # Kubernetes execution

📚 Documentation

• 🏠 Homepage
• 📖 Getting Started
• 🔧 API Reference
• 💡 Examples
• 📝 Changelog

🏗️ Project Structure

Package	Version	Description
@xec-sh/core		Terminal prompts and utils
@xec-sh/core		Core execution engine
@xec-sh/cli		Command-line interface
@xec-sh/testing	-	Testing utilities

🛠️ Development

# Prerequisites
corepack enable          # Enable Yarn 4.9.2
yarn install            # Install dependencies

# Development
yarn dev                # Watch mode
yarn test              # Run tests
yarn build             # Build all packages

# Quality
yarn lint              # Lint code
yarn type-check        # Type checking
yarn test:coverage     # Coverage report

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © Xec Contributors

---

Built with ❤️ by developers, for developers
_{Making command execution universal, type-safe, and delightful}