Skip to main content

Installation

System Requirements​

Before installing Xec, ensure your system meets these requirements:

  • Node.js: Version 22.18.0 or higher — the CLI runs TypeScript files through Node's own type stripping, on by default since 22.18. The libraries (@xec-sh/core and friends) used programmatically need only Node 20.
  • Operating System: macOS, Linux, or Windows — all three run the unit suite in CI
  • Package Manager: npm (included with Node.js) or pnpm

Optional Dependencies​

For full functionality, you may also want:

  • Docker: For container execution features
  • kubectl: For Kubernetes pod execution
  • SSH Client: For remote execution (OpenSSH recommended)

Installation Methods​

Install Xec globally to use it from anywhere on your system:

# Using npm
npm install -g @xec-sh/cli

# Using pnpm
pnpm add -g @xec-sh/cli

Verify the installation:

xec --version

Project Installation​

Add Xec to your project for scripting and automation:

# Install the CLI as a dev dependency
npm install --save-dev @xec-sh/cli

# Install the core library for programmatic use
npm install @xec-sh/core

Add to your package.json scripts:

{
  "scripts": {
    "deploy": "xec deploy.ts",
    "build": "xec run build",
    "test": "xec test --coverage"
  }
}

Development Installation​

For contributing to Xec or using the latest development version:

# Clone the repository
git clone https://github.com/xec-sh/xec.git
cd xec

# Enable Corepack for pnpm
corepack enable

# Install dependencies
pnpm install

# Build the project
pnpm build

# Link for global usage
pnpm link --global

Package Overview​

Xec consists of multiple packages:

@xec-sh/cli​

The command-line interface for Xec.

npm install -g @xec-sh/cli

Features:

  • Command execution across environments
  • Task automation
  • Script running
  • Configuration management

@xec-sh/core​

The core execution engine for programmatic use.

npm install @xec-sh/core

Features:

  • Template literal execution API
  • Multi-environment adapters
  • Connection pooling
  • Error handling

@xec-sh/testing​

Testing utilities for Xec scripts and commands.

npm install --save-dev @xec-sh/testing

Features:

  • Test containers
  • Mock targets
  • Test helpers

Platform-Specific Setup​

macOS​

npm install -g @xec-sh/cli

Linux​

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @xec-sh/cli

# Fedora/RHEL
sudo dnf install nodejs
npm install -g @xec-sh/cli

# Arch Linux
sudo pacman -S nodejs npm
npm install -g @xec-sh/cli

Windows​

Native Windows is supported and tested:

# Install Node.js from nodejs.org first
npm install -g @xec-sh/cli

Commands there run through cmd.exe by default, and Xec's own behaviour — escaping, paths, globs, line endings, timeouts — is identical to the other platforms. What differs is what the shell itself understands: cmd has no &&, no $VAR expansion and none of the POSIX tools. See Windows and cross-platform scripts.

WSL2 is worth having if your scripts are written in POSIX shell syntax and you would rather not change them:

# In WSL2 terminal
npm install -g @xec-sh/cli

Docker Installation​

Run Xec in a container:

FROM node:22-alpine
RUN npm install -g @xec-sh/cli
WORKDIR /app
COPY . .
CMD ["xec", "run", "script.ts"]

Verifying Installation​

After installation, verify everything is working:

# Check version
xec --version

# Show help
xec --help

# Test execution
xec -e "console.log('Hello from Xec!')"

Configuration Setup​

Initialize Xec in your project:

# Scaffold .xec/ in the current project (config, commands, scripts)
xec new project

# Or create individual artifacts
xec new script deploy
xec new command greet

Environment Variables​

Configure Xec behavior with environment variables:

# Load an additional config file
export XEC_CONFIG=/custom/path/config.yaml

# Enable debug output
export XEC_DEBUG=true

# Disable colors
export NO_COLOR=1

Troubleshooting Installation​

Common Issues​

Permission Denied

# Fix npm global permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Module Not Found

# Clear npm cache
npm cache clean --force

# Reinstall
npm install -g @xec-sh/cli

Version Conflicts

# Check Node.js version
node --version  # Should be >= 22.18.0

# Update Node.js if needed
nvm install 22
nvm use 22

TypeScript Issues

# Install TypeScript support
npm install -g typescript tsx

Updating Xec​

Keep Xec up to date:

# Update global installation
npm update -g @xec-sh/cli

# Update project installation
npm update @xec-sh/core @xec-sh/cli

# Check for updates
npm outdated -g @xec-sh/cli

Uninstalling​

To remove Xec from your system:

# Global uninstall
npm uninstall -g @xec-sh/cli

# Project uninstall
npm uninstall @xec-sh/core @xec-sh/cli

# Remove configuration (optional)
rm -rf ~/.xec
rm -rf .xec/

Next Steps​

Getting Help​

If you encounter issues: