shcripts 0.0.1
A modern CLI tool to manage your bash scripts and job submissions.
Requires Python: >=3.9

# `shcripts`
![shcripts logo](docs/assets/logo.svg)

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

```bash
# 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

```bash
# 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

```bash
# List all templates
shcripts list

# Filter by category
shcripts list --category mcmc

# Filter by tag
shcripts list --tag slurm
```

### 3. View a Template

```bash
# 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:

```bash
#!/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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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.

```bash
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.

```bash
shcripts list [OPTIONS]

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

### `show`
Display the content of a script template.

```bash
shcripts show <name> [OPTIONS]

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

### `generate`
Generate a script from a template with variable substitution.

```bash
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.

```bash
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.

```bash
shcripts status [job-id] [OPTIONS]

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

### `history`
Show job submission history.

```bash
shcripts history [OPTIONS]

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

### `remove`
Remove a script template from the collection.

```bash
shcripts remove <name> [OPTIONS]

Options:
  -f, --force   Skip confirmation
```

## Template Variables

Templates use Jinja2 syntax for variables. Common patterns:

```bash
# 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**:
   ```bash
   # 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**:
   ```bash
   for dataset in data1 data2 data3; do
     shcripts submit --template analysis \
       --var dataset=$dataset \
       --var output_dir=/results/$dataset
   done
   ```

3. **Monitor all jobs**:
   ```bash
   shcripts status --all
   ```

4. **Review history**:
   ```bash
   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