🥝 kiwi-runner

CLI tool for executing commands from URLs - run complex command sequences with platform-specific support.

Features

• 🌐 Execute commands from URLs - Store and run commands from any HTTP(S) endpoint
• 🖥️ Platform-specific support - Different commands for Linux, macOS, and Windows
• 🔒 Security first - Built-in verification system and user trust lists
• 📝 Aliases - Save URLs under short names like @setup for quick access
• 🔄 Multiple commands - Execute sequences of commands with a single URL
• 📊 Comprehensive logging - Error logs with detailed stack traces

Installation

npm install -g kiwi-runner

Quick Start

# Execute a command from a URL
kiwi example.com/setup

# Use an alias
kiwi @deploy

# Create an alias
kiwi alias create deploy example.com/deploy

Command Format

Commands are defined in JSON format:

Simple Command

{
  "description": "Check Node.js version",
  "commands": "node --version"
}

Platform-specific Commands

{
  "description": "System information",
  "commands": {
    "linux": "uname -a",
    "darwin": "sw_vers",
    "windows": "systeminfo"
  }
}

Multiple Commands

{
  "description": "Setup environment",
  "commands": [
    "echo 'Installing dependencies...'",
    "npm install",
    "echo 'Setup complete!'"
  ]
}

Security

kiwi-runner has a two-tier security system:

1. Built-in verified URLs - Maintained by the package developers
2. User trusted URLs - Your personal list of trusted URLs

When executing a URL that's not verified, you'll be prompted to:

• View the command preview
• Execute once
• Add to your trusted list and execute

Managing Trusted URLs

# List trusted URLs
kiwi trusted

# Remove a URL from trusted list
kiwi trusted remove example.com/setup

Aliases

Save frequently used URLs under short names:

# Create alias (wizard mode)
kiwi alias create

# Create alias directly
kiwi alias create setup example.com/setup

# List all aliases
kiwi alias

# Use an alias
kiwi @setup

# Remove an alias
kiwi alias remove setup

CLI Commands

# Execute commands
kiwi <url|@alias>

# Alias management
kiwi alias                    # List aliases
kiwi alias create             # Create alias (wizard)
kiwi alias create <name> <url># Create alias directly
kiwi alias remove <name>      # Remove alias

# Trusted URLs
kiwi trusted                  # List trusted URLs
kiwi trusted remove <url>     # Remove from trusted list

# Logs
kiwi --log                    # Show log directory

# Help
kiwi --help                   # Show help
kiwi alias --help             # Alias help
kiwi trusted --help           # Trusted URLs help

Options

• -h, --help - Show help
• -v, --version - Show version
• --log - Show log directory
• --json - Output in JSON format
• --no-interaction - Disable interactive prompts

Examples

Host Command Files

Create a JSON file with your commands:

{
  "description": "Development setup",
  "commands": [
    "git clone https://github.com/user/repo.git",
    "cd repo",
    "npm install",
    "npm run dev"
  ]
}

Host it anywhere (GitHub Gist, your server, etc.) and run:

kiwi yourdomain.com/dev-setup.json

Platform-specific Workflows

{
  "description": "Build project",
  "commands": [
    "npm install",
    {
      "linux": "chmod +x build.sh && ./build.sh",
      "darwin": "chmod +x build.sh && ./build.sh",
      "windows": "build.bat"
    },
    "echo 'Build complete!'"
  ]
}

Hosting Your Command Files

You can host your JSON command files anywhere:

• GitHub Gist (raw URL)
• GitHub Pages
• Your own server
• Any static file hosting (Netlify, Vercel, etc.)
• CDN (jsDelivr, unpkg, etc.)

Development

# Clone the repository
git clone <repository-url>
cd kiwi

# Install dependencies
pnpm install

# Build the project
pnpm build

# Link globally for development
pnpm link --global

License

MIT

Author

Your Name