shutl

name	shutl
description	Use this skill when the user wants to organize, manage, and execute shell scripts as commands with metadata-driven arguments and flags.

Shutl Plugin

Command-line tool for organizing, managing, and executing shell scripts as commands. Automatically creates CLI commands from shell scripts with metadata-driven arguments and flags.

Commands

Script Management

• shutl script create <location> <name> — Create a new script with optional editor and type
• shutl script edit <command> — Edit an existing script

Running User Scripts

• shutl _ _ -- <command> — Run any user-defined script with arguments and flags

Usage Examples

# Create a new script
shutl script create tools deploy --type bash
shutl script create utils backup --editor vim

# Edit existing script
shutl script edit tools deploy

# Run user-defined scripts (after creation)
shutl tools deploy --input file.txt --host example.com
shutl utils backup --dry-run

Installation

brew tap k15r/shutl
brew install shutl

Or from source:

git clone https://github.com/k15r/shutl.git
cd shutl
cargo build --release

Script Metadata

Create shell scripts in ~/.shutl directory with metadata comments:

#!/bin/bash
#@description: Example command with various metadata
#@arg:input - Input file path
#@arg:output - Output file path [default:output.txt]
#@flag:host - Host name [default:localhost]
#@flag:dry-run - Perform a dry run [bool,default:false]
#@arg:...files - Additional files to process

# Your script logic here
if [ "$SHUTL_DRY_RUN" = "true" ]; then
    echo "Dry run mode enabled"
fi
echo "Hostname: ${SHUTL_HOST}"
echo "Processing input file: $SHUTL_INPUT"
echo "Output will be saved to: $SHUTL_OUTPUT"

Metadata Syntax

Metadata	Syntax
Description	#@description: Your command description
Required argument	#@arg:name - Argument description
Optional argument with default	#@arg:name - Argument with default [default:value]
Argument with options	#@arg:name - Argument with allowed values [options:val1|val2]
Catch-all argument	#@arg:... - Additional arguments description
Named catch-all	#@arg:...name - Named catch-all arguments
Required catch-all	#@arg:...files - Required named catch-all [required]
Flag with default	#@flag:name - Flag with default value [default:value]
Boolean flag	#@flag:name - Boolean flag [bool]
Flag with options	#@flag:name - Flag with allowed values [options:val1|val2]
Required flag	#@flag:name - Required flag [required]
Flag with file completion	#@flag:name - Flag with file completion [file]
Flag with directory completion	#@flag:name - Flag with directory completion [dir]
Flag with path completion	#@flag:name - Flag with any path completion [path]

Command Completion

Enable command completion by adding to shell configuration:

bash:

. <(COMPLETE=bash shutl)

zsh:

. <(COMPLETE=zsh shutl)

Key Features

• Dynamic Command Generation: Automatically creates CLI commands from shell scripts
• Metadata Support: Special comments define command metadata (description, args, flags)
• Flexible Argument Handling: Required and optional arguments with defaults
• Boolean Flags: Automatically generates flags with negated versions (--no-flag)
• Catch-all Arguments: Supports additional arguments beyond defined parameters
• Directory-based Organization: Organize commands in directories for better structure
• Command Completion: Shell completion for commands, arguments, and flags
• Environment Variables: Override default scripts directory with SHUTL_DIR

Directory Descriptions

Add a .shutl file in any directory to provide a description in help output:

mkdir -p ~/.shutl/deploy
echo "Deployment scripts for various environments" > ~/.shutl/deploy/.shutl

Environment Variables

• SHUTL_DIR: Override the default scripts directory (~/.shutl)

Project Structure

~/.shutl/
├── command1.sh
└── subdir/
    ├── .shutl          # Optional: directory description
    └── command2.sh

Common Workflows

Creating a new script

shutl script create utils backup --type bash
# Edit the generated script with metadata
shutl script edit utils backup

Organizing scripts by category

shutl script create deploy production
shutl script create deploy staging
shutl script create database migrate

Running scripts with flags

# Boolean flags
shutl deploy production --dry-run
shutl deploy production --no-dry-run

# With arguments
shutl database migrate --env production --verbose