shcripts

A powerful CLI tool for managing bash scripts and SLURM job submissions with template support and job tracking.

Features

• 📝 Script Template Management: Store and organize reusable bash script templates
• 🔄 Jinja2 Templating: Use variables in templates for flexible script generation
• 🚀 SLURM Job Submission: Submit jobs directly from templates or script files
• 📊 Job Tracking: Keep track of submitted jobs with automatic status updates
• 🎨 Rich CLI Interface: Beautiful terminal output with syntax highlighting
• 📦 Organized Storage: Category and tag-based organization of scripts

Installation

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

# Install with uv
uv sync

# Or install in development mode
uv pip install -e .

Quick Start

1. Add a Script Template

# Add the example SLURM script as a template
shcripts add montepython src/shcripts/template/example.sh \
  --description "MontePython MCMC run with BOSS/eBOSS data" \
  --category "mcmc" \
  --tag slurm --tag python

2. List Available Templates

# List all templates
shcripts list

# Filter by category
shcripts list --category mcmc

# Filter by tag
shcripts list --tag slurm

3. View a Template

# Show template with syntax highlighting
shcripts show montepython

# Show raw content
shcripts show montepython --raw

4. Generate Scripts from Templates

Templates support Jinja2 variables. Modify your template to include variables:

#!/bin/bash
#SBATCH --job-name={{ job_name }}
#SBATCH --time={{ time }}
#SBATCH --ntasks={{ ntasks }}
#SBATCH --mem={{ memory }}

echo "Running {{ description }}"
# Your commands here

Generate with variables:

# Generate and print to stdout
shcripts generate montepython \
  --var job_name=my-job \
  --var time=10:00:00 \
  --var ntasks=16 \
  --var memory=64GB \
  --var description="My analysis run"

# Generate to file
shcripts generate montepython \
  --output my_job.sh \
  --var job_name=my-job \
  --var time=10:00:00

5. Submit SLURM Jobs

# Submit from a template
shcripts submit --template montepython \
  --var job_name=run-001 \
  --var time=48:00:00

# Dry run to preview
shcripts submit --template montepython \
  --var job_name=test \
  --dry-run

# Submit from a script file
shcripts submit path/to/script.sh

6. Track Job Status

# Check specific job
shcripts status 12345

# List all tracked jobs
shcripts status --all

# View submission history
shcripts history

# Limit history results
shcripts history --limit 5

7. Remove Templates

# Remove with confirmation
shcripts remove montepython

# Force remove without confirmation
shcripts remove montepython --force

Commands Reference

add

Add a new script template to the collection.

shcripts add <name> <script-path> [OPTIONS]

Options:
  -d, --description TEXT   Script description
  -c, --category TEXT      Script category [default: general]
  -t, --tag TEXT           Tags (can be used multiple times)

list

List all stored script templates.

shcripts list [OPTIONS]

Options:
  -c, --category TEXT   Filter by category
  -t, --tag TEXT        Filter by tag

show

Display the content of a script template.

shcripts show <name> [OPTIONS]

Options:
  -r, --raw   Show raw file content without syntax highlighting

generate

Generate a script from a template with variable substitution.

shcripts generate <template-name> [OPTIONS]

Options:
  -o, --output TEXT   Output file path
  -v, --var TEXT      Variables in key=value format (can be used multiple times)

submit

Submit a SLURM job from a file or template.

shcripts submit [script-path] [OPTIONS]

Options:
  -t, --template TEXT   Template name to use
  -v, --var TEXT        Variables in key=value format (can be used multiple times)
  --dry-run             Show what would be submitted without submitting

status

Check the status of SLURM jobs.

shcripts status [job-id] [OPTIONS]

Options:
  -a, --all   Show all tracked jobs

history

Show job submission history.

shcripts history [OPTIONS]

Options:
  -n, --limit INTEGER   Number of recent jobs to show [default: 10]

remove

Remove a script template from the collection.

shcripts remove <name> [OPTIONS]

Options:
  -f, --force   Skip confirmation

Template Variables

Templates use Jinja2 syntax for variables. Common patterns:

# Simple variable substitution
{{ variable_name }}

# Default values
{{ variable_name | default("default_value") }}

# Conditionals
{% if condition %}
  # commands
{% endif %}

# Loops
{% for item in list %}
  echo {{ item }}
{% endfor %}

Storage

All data is stored in ~/.shcripts/:

• templates/ - Script template files
• scripts.json - Template metadata
• jobs.json - Job submission history

Example Workflow

1. Create a template with variables:

   # Edit template/analysis.sh with Jinja2 variables
   # Add it to shcripts
   shcripts add analysis template/analysis.sh \
     --description "General analysis pipeline" \
     --category "data-analysis"
   

2. Submit multiple jobs with different parameters:

   for dataset in data1 data2 data3; do
     shcripts submit --template analysis \
       --var dataset=$dataset \
       --var output_dir=/results/$dataset
   done
   

3. Monitor all jobs:

   shcripts status --all
   

4. Review history:

   shcripts history --limit 20
   

Tips

• Use descriptive template names and categories for easy organization
• Add multiple tags to templates for flexible filtering
• Use --dry-run to preview generated scripts before submission
• Keep template variables documented in the script description
• Use the show command to review templates before generating scripts

Requirements

• Python >= 3.9
• SLURM (for job submission features)
• Dependencies: typer, rich, jinja2 (managed by uv)

License

MIT License

Copyright (c) 2025, Rodrigo Calderon