ScriptIt

A powerful cross-runtime script runner with TUI, environment management, and colored console output. Works seamlessly with Node.js, Bun, and Deno.

🎨 NEW in v0.5.1: Enhanced documentation and improved GitHub Pages deployment!

🎯 NEW in v0.6.0: Interactive Environment Prompts for secure variable collection!

🏗️ NEW in v0.7.0: Unified architecture with CLI refactoring and enhanced TUI experience!

🚀 Quick Start

# Install globally
bun add -g @glyphtek/scriptit

# Initialize a new project
scriptit init

# Run the interactive TUI
scriptit run

# Or execute a single script (colored console enabled by default)
scriptit exec ./scripts/my-script.js

📚 Documentation

📖 Visit the full documentation site →

✨ Key Features

🎨 Developer Experience

Colored Console Output: Automatic color coding for console methods with beautiful output
- 🤍 White for console.log() • 🔴 Red for console.error()
- 🟡 Yellow for console.warn() • 🔵 Blue for console.info() • ⚫ Gray for console.debug()
Interactive Terminal UI: Multi-panel interface for script selection and real-time output
Enhanced Script Context: Rich context object with colored console support

⚡ Runtime & Performance

Cross-Runtime Compatibility: Node.js (18+), Deno, and Bun support
Dynamic Script Loading: Fresh loading on each execution for external updates
Lambda Function Support: Perfect for existing functions - just point and run!
Flexible Script Patterns: Traditional lifecycle or modern default export functions

🔧 Configuration & Environment

Configuration Files: runner.config.js for project-specific behavior
Environment Management: Smart .env file loading with variable interpolation
Script Discovery: Automatic nested discovery with customizable exclude patterns
Working Directory Support: Run from anywhere with --pwd option

📦 Integration Ready

CLI & Library: Use standalone or integrate into your applications
Event System: Listen to script execution events
Git Integration: Smart .gitignore management for temporary files

Prerequisites

Choose one of the following JavaScript runtimes:

Bun (v1.0.0+) - Recommended for best performance
Node.js (v18.0.0+)
Deno (latest)

Installation

Global Installation

Bun (Recommended)

bun add -g @glyphtek/scriptit

Node.js

npm install -g @glyphtek/scriptit
# or
yarn global add @glyphtek/scriptit

Deno

deno install --allow-read --allow-write --allow-run --allow-env -n scriptit npm:@glyphtek/scriptit

Local Installation

Bun: bun add @glyphtek/scriptit
Node.js: npm install @glyphtek/scriptit
Deno: import { createScriptRunner } from "npm:@glyphtek/scriptit"

CLI Usage

Initialize Project

scriptit init

Creates a complete project structure with example scripts, configuration, and proper .gitignore setup.

Options:

-s, --scripts-dir <dir> - Directory for scripts (default: scripts)
-t, --tmp-dir <dir> - Directory for temporary files (default: tmp)
-f, --force - Overwrite existing files and directories

Interactive Terminal UI

scriptit run
# or simply
scriptit

Options:

-c, --config <path> - Path to runner configuration file
-s, --scripts-dir <dir> - Override scripts directory from config
-t, --tmp-dir <dir> - Override temporary directory from config
--no-tui - Run without Terminal UI, just list available scripts
--force-tui - Force TUI mode even when debug is enabled

Navigation:

↑↓ or j/k: Navigate scripts • Tab: Switch panels • Enter: Execute
C: Toggle config • F: Toggle files • R: Refresh • Q: Quit

Execute Single Scripts

# Basic execution (colored console enabled by default)
scriptit exec ./scripts/my-script.ts

# With environment variables
scriptit exec ./scripts/deploy.ts -e NODE_ENV=production API_KEY=secret

# With interactive environment prompts
scriptit exec ./scripts/deploy.ts --env-prompts API_KEY,SECRET_TOKEN

# With custom configuration
scriptit exec ./scripts/my-script.ts -c custom.config.js

# Multiple environment variables
scriptit exec ./scripts/script.ts -e NODE_ENV=prod -e DEBUG=false -e PORT=8080

# Combine static and prompted environment variables
scriptit exec ./scripts/deploy.ts -e NODE_ENV=production --env-prompts API_KEY,SECRET_TOKEN

Options:

-c, --config <path> - Path to runner configuration file
-e, --env <vars...> - Set environment variables (e.g., NAME=value X=Y)
--env-prompts <vars...> - Prompt for environment variables before execution (e.g., API_KEY,SECRET)

Global Options

Available for all commands:

# Enable debug mode with verbose logging
scriptit --debug exec ./scripts/my-script.ts

# Set working directory (all relative paths resolve from here)
scriptit --pwd /path/to/project exec ./scripts/deploy.ts

# Show version
scriptit --version

# Show help
scriptit --help

Working Directory Support

The --pwd option is perfect for:

CI/CD pipelines - Run from build directories
Multi-project setups - Manage scripts across repositories
Lambda integration - Point to existing function directories

# Change working directory before execution
scriptit --pwd /path/to/project run

# All relative paths resolve from the specified directory
scriptit --pwd /app exec ./scripts/deploy.ts

Script Types & Examples

Traditional Lifecycle Pattern

// scripts/deployment.ts
export const description = "Deploy application with full lifecycle";

export async function tearUp(context) {
  context.log('Setting up deployment...');
  return { startTime: Date.now() };
}

export async function execute(context, tearUpResult) {
  const console = context.console || global.console;
  
  console.info('Starting deployment...');
  console.warn('This will overwrite production!');
  
  // Main deployment logic
  const result = await deployApplication(context.env.API_KEY);
  
  console.log('Deployment completed successfully');
  return result;
}

export async function tearDown(context, executeResult, tearUpResult) {
  const duration = Date.now() - tearUpResult.startTime;
  context.log(`Deployment completed in ${duration}ms`);
}

Lambda/Default Export Pattern

// scripts/data-processor.ts
export const description = "Process data with colored output";

export default async function(context) {
  const console = context.console || global.console;
  
  console.log('Processing data...');
  console.info(`Environment: ${context.env.NODE_ENV}`);
  
  try {
    const result = await processLargeDataset(context.env.INPUT_FILE);
    console.log('✅ Processing completed successfully');
    return result;
  } catch (error) {
    console.error('❌ Processing failed:', error.message);
    throw error;
  }
}

Enhanced Context Object

interface ScriptContext {
  // Enhanced console with colors (when enabled)
  console: {
    log: (...args: unknown[]) => void;    // White
    info: (...args: unknown[]) => void;   // Blue
    warn: (...args: unknown[]) => void;   // Yellow  
    error: (...args: unknown[]) => void;  // Red
    debug: (...args: unknown[]) => void;  // Gray
  };
  
  // Environment & configuration
  env: Record<string, string | undefined>;
  tmpDir: string;
  configPath?: string;
  log: (message: string) => void;
  params: Record<string, unknown>;
  
  // Default parameters from config
  [key: string]: unknown;
}

Interactive Environment Prompts

ScriptIt supports interactive prompting for environment variables across both CLI and TUI interfaces, allowing you to securely collect sensitive data at runtime without hardcoding values.

Universal Prompting

Environment variable prompting works seamlessly across all interfaces:

CLI: Terminal-based prompting with readline
TUI: Beautiful modal dialogs with visual feedback
Library: Programmatic integration with custom prompters

Both interfaces support the same features:

Password masking with * characters
Smart detection (only prompts for missing variables)
Type-aware prompting (input vs password fields)
Consistent variable precedence across all interfaces

Declarative Method (Script-defined)

Scripts can declare their required environment variables using the variables export:

// Full definition with custom prompts and types
export const variables = [
  { name: 'API_KEY', message: 'Enter your API key:', type: 'password' },
  { name: 'USER_NAME', message: 'Enter your username:', type: 'input' },
];

// Shorthand definition for quick setup
export const variables = ['API_KEY', 'DATABASE_URL', 'SECRET_TOKEN'];

export async function execute(context) {
  const console = context.console || global.console;
  
  // Variables are automatically prompted and available in context.env
  console.log(`API Key: ${context.env.API_KEY ? '***hidden***' : 'Not set'}`);
  console.log(`Username: ${context.env.USER_NAME || 'Not provided'}`);
  
  return { success: true };
}

Imperative Method (CLI-driven)

Use the --env-prompts flag to prompt for any variables on demand:

# Prompt for specific variables
scriptit exec my-script.js --env-prompts API_KEY,SECRET_TOKEN

# Space-separated format also works
scriptit exec my-script.js --env-prompts API_KEY SECRET_TOKEN

# Works with the run command too
scriptit run --env-prompts DATABASE_URL,API_KEY

Variable Types

input (default): Regular text input
password: Hidden input with masked characters (*)

Execution Priority

ScriptIt follows this order when collecting environment variables:

Existing Environment: Variables already set in shell, .env files, or via --env flag
Skip Prompting: Variables that are already set are not prompted again
Combine Sources: CLI --env-prompts + script variables export (CLI takes precedence for duplicates)
Interactive Collection: Prompt for any missing variables
Script Execution: All variables available in context.env

Final Environment Precedence (highest to lowest):

Prompted Variables - Collected interactively
CLI Arguments (--env NAME=value) - CLI-provided environment variables
Config Default Params - From runner.config.js
Environment Files - .env, .env.local, etc.

Security Features

Password masking: Sensitive inputs are hidden with * characters
No logging: Prompted values are not logged or displayed in output
Process isolation: Values are set in process.env for script duration only

Library Usage

Basic Integration

import { createScriptRunner } from '@glyphtek/scriptit';

const runner = await createScriptRunner({
  scriptsDir: './scripts',
  tmpDir: './tmp',
  consoleInterception: { enabled: true },  // Enable colored console
  excludePatterns: ['*.helper.*', '_*'],
});

// Execute scripts
const result = await runner.executeScript('deploy.ts', {
  params: { environment: 'production' },
  env: { API_KEY: 'secret' }
});

// Event handling
runner.on('script:beforeExecute', (scriptPath) => {
  console.log(`🚀 Executing: ${scriptPath}`);
});

Advanced Configuration

// Multi-project setup
const projectRunner = await createScriptRunner({
  workingDirectory: '/projects/my-app',
  scriptsDir: './deployment-scripts',
  envFiles: ['.env', '.env.production'],
  defaultParams: {
    projectName: 'My App',
    version: process.env.npm_package_version
  }
});

// Lambda function integration
const lambdaRunner = await createScriptRunner({
  workingDirectory: '/lambda-functions',
  scriptsDir: './',
  excludePatterns: ['node_modules/**', '*.test.*'],
  consoleInterception: { enabled: true }
});

Configuration

Create a runner.config.js file in your project root:

// runner.config.js
export default {
  scriptsDir: './scripts',
  tmpDir: './tmp',
  envFiles: ['.env', '.env.local', '.env.production'],
  excludePatterns: [
    '**/node_modules/**',
    '**/*.test.*',
    '**/*.helper.*',
    '_*',
    '**/helpers/**'
  ],
  defaultParams: {
    appName: 'My Application',
    version: '1.0.0',
    apiUrl: '${API_BASE_URL}/api/v1'  // Environment variable interpolation
  }
};

Configuration Options

Option	Type	Default	Description
`scriptsDir`	`string`	`"scripts"`	Scripts directory path
`tmpDir`	`string`	`"tmp"`	Temporary files directory
`envFiles`	`string[]`	`[".env"]`	Environment files to load
`excludePatterns`	`string[]`	`[]`	Script exclusion patterns
`defaultParams`	`object`	`{}`	Default script parameters

Migration Guide

Upgrading to v0.5.0 (Colored Console)

CLI Usage:

# Colored console is enabled by default in CLI
scriptit exec my-script.js

Library Usage:

const runner = createScriptRunner({
  consoleInterception: { enabled: true }  // Enable colored console
});

Script Updates:

// Use enhanced console for best results
export default async function(context) {
  const console = context.console || global.console;
  console.log('This will be colored when interception is enabled');
}

Upgrading to v0.4.0 (TUI & Default Exports)

New TUI interface: scriptit run now opens interactive UI
Default export support: Lambda functions work directly
No breaking changes: Existing scripts continue to work

Troubleshooting

Common Issues

🔍 Script not found

Check your scriptsDir configuration
Ensure files have .js or .ts extensions
Verify exclude patterns aren't filtering your scripts

🌍 Environment variables not loading

Ensure .env files are in project root or configured in envFiles
Check file permissions and syntax
Use context.log() to debug loaded variables

🖥️ TUI not working properly

Some terminals have limited support - try --no-tui
Ensure terminal size is adequate (minimum 80x24)
Try different terminal emulators
Use --debug for verbose logging

🎨 Colored console not working

Colored console is enabled by default in CLI mode
For library usage, set consoleInterception: { enabled: true }
Some terminals may not support all colors
Ensure scripts use context.console fallback pattern

🔧 Permission errors

Check file permissions for script and temp directories
Ensure ScriptIt has necessary runtime permissions
Verify working directory access with --pwd

⚙️ Debug mode issues

Use --debug flag for verbose logging
TUI is disabled by default in debug mode (use --force-tui to override)
Check SCRIPTIT_DEBUG environment variable

Getting Help

If you encounter issues not covered here, please check our troubleshooting guide or open an issue.

Development

Quick Setup

git clone https://github.com/glyphtek/scriptit.git
cd scriptit
bun install
bun run build
bun test

Available Scripts

Command	Description
`bun run dev`	Development mode
`bun run build`	Production build
`bun test`	Run all tests
`bun run lint`	Code linting
`bun run format`	Code formatting

Contributing Guidelines

Fork & Clone: Create your feature branch
Test: Write tests for new functionality
Quality: Follow TypeScript best practices
Compatibility: Ensure cross-runtime support
Documentation: Update docs for new features

Community & Support

🤝 Get Help

🌟 Show Support

🚀 Contributing

We welcome contributions! Ways to help:

Bug Reports: Detailed reproduction steps
Feature Requests: Describe your use case
Code Contributions: PRs with tests
Documentation: Improve guides and examples
Community: Help others in discussions

🤝 Contributing

We welcome contributions from the community! ScriptIt is an open source project that thrives on collaboration.

Quick Start for Contributors

Fork the repository on GitHub
Clone your fork locally: git clone https://github.com/YOUR_USERNAME/scriptit.git
Create a feature branch from develop: git checkout -b feature/your-feature-name
Make your changes with tests and documentation
Submit a pull request to the develop branch

Development Setup

# Install dependencies
bun install

# Run tests
bun test

# Build project
bun run build

# Lint and format
bun run check

What We're Looking For

🐛 Bug fixes - Help us squash issues
✨ New features - Enhance ScriptIt's capabilities
📚 Documentation - Improve guides and examples
🧪 Tests - Increase coverage and reliability
🎨 UI/UX - Make the TUI even better
⚡ Performance - Optimize for speed and memory

Project Structure

src/cli.ts - Command-line interface
src/lib.ts - Library API
src/core/ - Core execution engine
src/ui/ - Terminal UI components
src/common/ - Shared utilities and types
docs/ - Documentation and guides
examples/ - Usage examples

For detailed contribution guidelines, see CONTRIBUTING.md.

📋 Project Status

Branch Protection

main - Protected production branch
develop - Integration branch for new features
All changes require pull requests with:
- ✅ Passing tests
- ✅ Code review approval
- ✅ CI/CD checks

Quality Assurance

Automated Testing - 31+ tests across multiple runtimes
Continuous Integration - GitHub Actions for testing, linting, and building
Cross-Runtime Support - Tested on Bun, Node.js, and Deno
Security Scanning - Automated vulnerability detection
Documentation - Comprehensive guides and API documentation

Release Process

Feature Development - Work in feature branches
Pull Request - Submit to develop branch
Code Review - Maintainer review and approval
Integration Testing - Automated CI/CD pipeline
Release - Tagged releases with automated NPM publishing

🔒 Security

Security is a top priority for ScriptIt. We follow responsible disclosure practices:

Report vulnerabilities to security@glyphtek.com
Security updates are released promptly
Supported versions receive security patches

See SECURITY.md for our complete security policy.

License

MIT License - see the LICENSE file for details.

ScriptIt - Making script management simple and powerful across all JavaScript runtimes.

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github		.github
bin		bin
docs		docs
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
SECURITY.md		SECURITY.md
biome.json		biome.json
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

License

glyphtek/scriptit

Folders and files

Latest commit

History

Repository files navigation

ScriptIt

🚀 Quick Start

📚 Documentation

✨ Key Features

🎨 Developer Experience

⚡ Runtime & Performance

🔧 Configuration & Environment

📦 Integration Ready

Table of Contents

Prerequisites

Installation

Global Installation

Local Installation

CLI Usage

Initialize Project

Interactive Terminal UI

Execute Single Scripts

Global Options

Working Directory Support

Script Types & Examples

Traditional Lifecycle Pattern

Lambda/Default Export Pattern

Enhanced Context Object

Interactive Environment Prompts

Universal Prompting

Declarative Method (Script-defined)

Imperative Method (CLI-driven)

Variable Types

Execution Priority

Security Features

Library Usage

Basic Integration

Advanced Configuration

Configuration

Configuration Options

Migration Guide

Upgrading to v0.5.0 (Colored Console)

Upgrading to v0.4.0 (TUI & Default Exports)

Troubleshooting

Common Issues

Getting Help

Development

Quick Setup

Available Scripts

Contributing Guidelines

Community & Support

🤝 Get Help

🌟 Show Support

🚀 Contributing

🤝 Contributing

Quick Start for Contributors

Development Setup

What We're Looking For

Project Structure

📋 Project Status

Branch Protection

Quality Assurance

Release Process

🔒 Security

License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Packages