rav

A cross-platform Python CLI to shortcut to command-line commands with powerful file download capabilities and integrity verification. Inspired by Makefiles and npm scripts.

Features

✨ Script Management: Define and run custom command shortcuts 🔗 Command Groups: Share working_dir and prefix across related commands 📦 File Downloads: Download files with integrity verification 🔒 Security: Subresource Integrity (SRI) hash verification 🎨 Rich Output: Beautiful terminal output with progress indicators ⚡ Multiple Formats: Support for single commands and multi-command sequences 🔧 Flexible Config: Use rav, scripts, or commands as top-level keys 🔀 Variables: Define reusable values with ${{ vars.NAME }} syntax

Install

It's recommended that you use a virtual environment with rav.

python3 -m pip install rav

Minimum python version is 3.9

Quick Start

Option 1: Interactive Setup

cd ~/path/to/project
rav new

Run through the setup wizard to create rav.yaml

Option 2: Manual Setup

Create rav.yaml:

scripts:
    echo: echo hello world
    server: python -m http.server 8000

Run commands:

rav run echo     # or rav x echo
rav run server   # Start development server  
rav list         # Show all available commands

CLI Commands Reference

Core Commands

Command	Description	Example
`rav run <command>`	Execute a script command	`rav run server`
`rav x <command>`	Shortcut for `rav run`	`rav x echo`
`rav list`	List all available commands	`rav list`
`rav new`	Create new rav project with wizard	`rav new`
`rav sample`	Generate sample rav.yaml file	`rav sample`
`rav version`	Show rav version	`rav version`

Download Commands

Command	Description	Example
`rav download <config>`	Download files using config	`rav download staticfiles`
`rav downloads <config>`	Alias for `rav download`	`rav downloads staticfiles`

Command Options

Option	Description	Example
`-f, --file`	Use custom rav file	`rav run -f custom.yaml echo`
`--overwrite`	Force overwrite existing files	`rav sample --overwrite`
`--verbose`	Enable verbose output	`rav --verbose run command`

Quick Examples

Script execution:

rav x server          # Start development server
rav x test            # Run tests  
rav x build           # Build project

Custom files:

rav run -f project.yaml deploy
rav list -f staging.yaml

Project management:

rav new              # Interactive project setup
rav sample           # Create example file
rav list             # View available commands

Script Configuration

The configuration block is flexible. Use rav, scripts, or commands as the top-level key.

rav.yaml

name: web-development-toolkit

scripts:
    # Development servers
    dev: python -m http.server 8000
    dev-secure: python -m http.server 8443 --bind 127.0.0.1
    
    # Testing and quality assurance  
    test: pytest tests/ -v
    lint: flake8 src/ tests/
    format: black src/ tests/
    
    # Build and deployment
    build:
        - npm run build
        - python setup.py sdist bdist_wheel
        - echo "Build complete!"
    
    deploy:
        - rav run test
        - rav run build  
        - rsync -av dist/ user@server:/var/www/

downloads:
    frontend-deps:
        destination: static/vendor
        overwrite: true
        files:
            - name: htmx.min.js
              url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
              integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm
            - name: tailwind.css
              url: https://cdn.tailwindcss.com/3.4.0/tailwind.min.css

Flexible Configuration Keys

The following all work and will run in this exact order (rav first, scripts second, commands last):

rav:
    echo: echo "this is awesome"
    server: venv/bin/python -m http.server

scripts:
    echo: echo "this is awesome"  
    server: venv/bin/python -m http.server

commands:
    echo: echo "this is awesome"
    server: venv/bin/python -m http.server

Basic Syntax

Commands follow this simple pattern:

rav run <command>       # Execute a script command
rav x <command>         # Shortcut for rav run
rav list                # Show all available commands

Sample Project

Generate a sample project to explore features:

rav sample              # Creates rav.sample.yaml
rav run -f rav.sample.yaml echo

Custom Rav File

Rav supports custom yaml files by default. The yaml declaration needs to be any of the following:

rav
scripts
commands

project.yaml

rav:
    sweet: echo "this is working"
    echo: echo "so is this"

rav.basic.yaml

scripts:
    sweet: echo "this is working"
    echo: echo "so is this"

rav run -f project.yaml sweet

or

rav run --file rav.other.yaml echo

Here's a few rules for custom files:

-f or --file is used to specify a custom rav file
-f or --file must be used prior to the command shortcut name (e.g. rav run -f <your-new-file> <your-command>)

Multiple Commands at Once

rav.yaml

scripts:
    multi: 
        - echo this is
        - echo awesome
        - echo simple
        - echo and 
        - echo easy

Run with:

rav run multi

This is the same as running:

echo this is && echo awesome && echo simple && echo and && echo easy

Variables

Define reusable values with ${{ vars.NAME }} syntax. Great for templates and boilerplates where configuration varies between projects.

Basic Usage

vars:
  PROJECT_NAME: myproject
  PORT: "8000"

scripts:
  server: uv run uvicorn ${{ vars.PROJECT_NAME }}.asgi:application --port ${{ vars.PORT }}
  migrate: uv run python manage.py migrate
  echo: echo "Running ${{ vars.PROJECT_NAME }}"

Run with:

rav run server
# Executes: uv run uvicorn myproject.asgi:application --port 8000

Configuration Keys

Both vars and variables work as the top-level key:

vars:
  PROJECT_NAME: myproject

variables:
  PROJECT_NAME: myproject

Environment Variable Fallback

Variables fall back to environment variables if not defined in YAML:

scripts:
  whoami: echo "Home is ${{ vars.HOME }}"  # Uses $HOME from environment
  greet: echo "Hello ${{ vars.USER }}"     # Uses $USER from environment

Variables with Command Groups

Variables work seamlessly with command groups:

vars:
  PROJECT_NAME: myproject
  PYTHON: uv run python

scripts:
  backend:
    working_dir: backend/src
    prefix: ${{ vars.PYTHON }}

  backend:server: manage.py runserver
  backend:migrate: manage.py migrate

View Resolved Variables

Use rav list --expanded to see commands with variables resolved:

rav list --expanded

┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Command ┃ Script                                               ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ server  │ uv run uvicorn myproject.asgi:application --port 8000│
│ echo    │ echo "Running myproject"                             │
└─────────┴──────────────────────────────────────────────────────┘

Command Groups

Command groups allow you to define shared working_dir and prefix settings that are inherited by related commands. This is useful when you have multiple commands that share common configuration.

Basic Group Syntax

Define a group using a name ending with : pattern. Commands prefixed with that group name inherit its settings:

scripts:
    # Group definition
    backend:
        working_dir: backend/src
        prefix: "uv run"
        cmd: uvicorn app:application --reload

    # These inherit working_dir and prefix from backend:
    backend:migrate: python manage.py migrate
    backend:shell: python manage.py shell
    backend:test: pytest

Running rav run backend:migrate executes:

cd backend/src && uv run python manage.py migrate

Group Configuration Options

Option	Description
`working_dir`	Directory to `cd` into before running commands
`prefix`	String prepended to each command
`cmd`	Default command when running the group itself

Overriding Group Settings

Individual commands can override their group's settings:

scripts:
    backend:
        working_dir: backend/src
        prefix: "uv run"
        cmd: uvicorn app:application --reload

    # Inherits both working_dir and prefix
    backend:migrate: python manage.py migrate

    # Override just the prefix (empty = no prefix)
    backend:install:
        prefix:
        cmd: uv sync --dev

    # Override both working_dir and prefix
    backend:docs:
        working_dir: backend/docs
        prefix: "mkdocs"
        cmd: serve

Real-World Example: Django with Doppler and UV

Using command groups with secret injection and Python environment management:

scripts:
    # Backend group with uv runner
    backend:
        working_dir: backend/src
        prefix: "uv run python manage.py"

    backend:migrate: migrate
    backend:makemigrations: makemigrations
    backend:createsuperuser: createsuperuser
    backend:shell: shell
    backend:collectstatic: collectstatic --noinput

    # Production with secrets injection
    prod:
        working_dir: backend/src
        prefix: "doppler run -- uv run python manage.py"

    prod:migrate: migrate
    prod:collectstatic: collectstatic --noinput

    # Frontend group
    frontend:
        working_dir: frontend
        prefix: "npm run"

    frontend:dev: dev
    frontend:build: build
    frontend:test: test

Usage:

rav run backend:migrate           # → cd backend/src && uv run python manage.py migrate
rav run prod:migrate              # → cd backend/src && doppler run -- uv run python manage.py migrate
rav run frontend:build            # → cd frontend && npm run build

Multi-Command Groups

Groups work with multi-command lists too:

scripts:
    backend:
        working_dir: backend/src
        prefix: "uv run"

    backend:setup:
        - echo "Setting up database..."
        - python manage.py migrate
        - python manage.py collectstatic --noinput
        - echo "Setup complete!"

Each command in the list gets the prefix applied:

cd backend/src && uv run echo "Setting up database..." && uv run python manage.py migrate && ...

Passing Arguments

Arguments are appended to the last command:

rav run backend:migrate myapp
# → cd backend/src && uv run python manage.py migrate myapp

Expanded List View

Use --expanded to see fully resolved commands:

rav list --expanded

File Downloads

Rav includes powerful file download capabilities with support for integrity verification, custom destinations, and batch downloads.

Basic Download Configuration

Add a downloads section to your rav.yaml:

name: my-project

scripts:
    serve: python -m http.server

downloads:
    assets:
        destination: static/vendor
        files:
            - name: htmx.min.js
              url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
            - name: tailwind.css
              url: https://cdn.tailwindcss.com/3.4.0/tailwind.min.css

Download Commands

rav download assets     # Download all files in 'assets' config
rav downloads assets    # Same as above (alias)

Advanced Download Configuration

downloads:
    frontend-deps:
        name: Frontend Dependencies
        destination: static/vendor
        verbose: true                    # Show detailed progress
        overwrite: true                  # Overwrite existing files
        raise_on_error: false           # Continue on individual file errors
        files:
            - name: htmx.min.js
              url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
              integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm
              destination: static/js     # Override global destination
              overwrite: false           # Override global overwrite setting
            
            - name: bootstrap.min.css
              url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
              destination: static/css

Configuration Options

Option	Level	Description	Default
`name`	Download	Human-readable name for the download set	-
`destination`	Download/File	Where to save files	Required
`verbose`	Download	Show detailed download progress	`true`
`overwrite`	Download/File	Overwrite existing files	`false`
`raise_on_error`	Download	Stop on any download error	`false`
`integrity`	File	SRI hash for verification	-
`url`	File	Download URL	Required
`name` or `filename`	File	Local filename	URL basename

File-Level Overrides

Individual files can override the download-level settings:

downloads:
    mixed-settings:
        destination: assets/
        overwrite: false
        verbose: true
        files:
            - name: important-file.js
              url: https://example.com/file.js
              overwrite: true          # Override: will overwrite
              destination: critical/   # Override: different folder
            
            - name: optional-file.css
              url: https://example.com/style.css
              # Uses download-level settings

Download Output

Rav provides rich, colored output showing download progress:

📥 Starting download: frontend-deps
Destination: static/vendor
Files to download: 3
Overwrite existing: true

[1/3] ⬇️  Downloading: htmx.min.js
   → From: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
   → Integrity: sha384-Akqfrbj/...
   ✅ Integrity verified (sha384)
   ✅ Success! (45,234 bytes)

[2/3] ⏭️  Skipping existing file: bootstrap.min.css

[3/3] ⬇️  Downloading: alpine.min.js
   ✅ Success! (15,678 bytes)

---------------------------------------
📊 Download Summary:
   ✅ Downloaded: 2 files
   ⏭️  Skipped: 1 files
---------------------------------------

Integrity Verification

Rav supports Subresource Integrity (SRI) verification to ensure downloaded files haven't been tampered with.

What is SRI?

Subresource Integrity is a security feature that allows you to verify that downloaded files haven't been modified. It uses cryptographic hashes (SHA256, SHA384, SHA512) to ensure file integrity.

Supported Hash Algorithms

SHA256: sha256-<base64hash>
SHA384: sha384-<base64hash>
SHA512: sha512-<base64hash>

Getting SRI Hashes

You can generate SRI hashes using online tools or command line:

Online Tools:

Command Line:

# SHA384 (recommended)
curl -s https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js | \
  openssl dgst -sha384 -binary | openssl base64 -A

# SHA256
curl -s https://example.com/file.js | \
  openssl dgst -sha256 -binary | openssl base64 -A

Using Integrity Verification

Add the integrity field to any file in your download configuration:

downloads:
    secure-assets:
        destination: static/vendor
        files:
            - name: htmx.min.js
              url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
              integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm
            
            - name: bootstrap.min.css
              url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
              integrity: sha384-9ndCyUa/9zzCGWL/iDMdwc9/z3dNS0MaTp5XhVpw5gGa6NZJK5YF6vZmN3K5J5zF

Integrity Verification Process

When integrity is specified, rav will:

Download the file to a temporary location
Calculate the file's hash using the specified algorithm
Compare against the expected hash
Move file to final destination only if verification passes
Delete file and report error if verification fails

Error Handling

With raise_on_error: false (default):

Failed verification logs an error and continues
Failed files are not saved to destination
Download summary shows verification failures

With raise_on_error: true:

Failed verification stops the entire download process
Throws an exception with detailed error information

Example Output with Integrity

[1/2] ⬇️  Downloading: htmx.min.js
   → From: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
   → Integrity: sha384-Akqfrbj/...
   → Downloading to temp for verification: /tmp/rav_downloads/htmx.min.js
   ✅ Integrity verified (sha384)
   → Downloaded to final destination: static/vendor/htmx.min.js
   ✅ Success! (45,234 bytes)

[2/2] ⬇️  Downloading: compromised-file.js
   → From: https://example.com/file.js
   → Integrity: sha384-Expected123...
   ❌ Integrity check failed: sha384-Actual456... != sha384-Expected123...

Security Best Practices

Always use integrity hashes for CDN files
Use SHA384 or SHA512 for better security than SHA256
Verify hashes from trusted sources (official documentation, package registries)
Set raise_on_error: true for critical security files
Keep hashes updated when updating file versions

Complete Examples

Web Development Project

A complete rav.yaml for a modern web development workflow:

name: my-web-app

scripts:
    # Development
    dev: python -m http.server 8000
    dev-watch: 
        - npm run watch
        - rav run dev
    
    # Code quality
    lint:
        - flake8 src/
        - npm run lint
        - echo "✅ Linting complete"
    
    format:
        - black src/
        - prettier --write static/js/
    
    test:
        - pytest tests/ -v --cov=src
        - npm test
    
    # Build pipeline
    build:
        - rm -rf dist/
        - rav download frontend-deps
        - npm run build
        - python setup.py sdist bdist_wheel
        - echo "🚀 Build complete!"
    
    # Deployment
    deploy-staging:
        - rav run test
        - rav run build
        - rsync -av dist/ staging@server:/var/www/staging/
    
    deploy-prod:
        - rav run test
        - rav run build
        - rsync -av dist/ prod@server:/var/www/production/

downloads:
    frontend-deps:
        name: Frontend Dependencies
        destination: static/vendor
        verbose: true
        overwrite: true
        files:
            # CSS Frameworks
            - name: bootstrap.min.css
              url: https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
              integrity: sha384-9ndCyUa/9zzCGWL/iDMdwc9/z3dNS0MaTp5XhVpw5gGa6NZJK5YF6vZmN3K5J5zF
              destination: static/css
            
            # JavaScript Libraries
            - name: htmx.min.js
              url: https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js
              integrity: sha384-Akqfrbj/HpNVo8k11SXBb6TlBWmXXlYQrCSqEWmyKJe+hDm3Z/B2WVG4smwBkRVm
              destination: static/js
            
            - name: alpine.min.js
              url: https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js
              destination: static/js

Data Science Project

Perfect for Jupyter notebooks and data analysis:

name: data-analysis-project

scripts:
    # Environment management
    setup:
        - python -m venv venv
        - venv/bin/pip install -r requirements.txt
        - echo "✅ Environment ready!"
    
    # Jupyter workflows
    notebook: venv/bin/jupyter lab --port=8888
    notebook-clean: venv/bin/jupyter nbconvert --clear-output notebooks/*.ipynb
    
    # Data processing
    download-data: python scripts/download_datasets.py
    process: 
        - python scripts/clean_data.py
        - python scripts/feature_engineering.py
        - echo "📊 Data processing complete"
    
    # Analysis and reporting
    analyze: venv/bin/python scripts/analyze.py
    report: 
        - venv/bin/jupyter nbconvert --to html notebooks/analysis.ipynb
        - echo "📑 Report generated: notebooks/analysis.html"
    
    # Model training
    train:
        - rav run process
        - python scripts/train_model.py
        - echo "🤖 Model training complete"

downloads:
    datasets:
        destination: data/raw
        files:
            - name: sample_data.csv
              url: https://example.com/datasets/sample.csv
            - name: reference_data.json
              url: https://api.example.com/reference/data.json

DevOps/Infrastructure Project

For managing deployments and infrastructure:

name: infrastructure-toolkit

scripts:
    # Infrastructure
    plan: terraform plan
    apply: terraform apply -auto-approve
    destroy: terraform destroy -auto-approve
    
    # Docker workflows
    build: docker build -t myapp:latest .
    run: docker run -p 8080:8080 myapp:latest
    push: 
        - docker tag myapp:latest registry.com/myapp:latest
        - docker push registry.com/myapp:latest
    
    # Kubernetes
    deploy:
        - kubectl apply -f k8s/
        - kubectl rollout status deployment/myapp
    
    logs: kubectl logs -f deployment/myapp
    status: kubectl get pods,services,deployments
    
    # Monitoring setup
    setup-monitoring:
        - rav download monitoring-stack
        - kubectl apply -f monitoring/
        - echo "📊 Monitoring stack deployed"

downloads:
    monitoring-stack:
        destination: monitoring
        files:
            - name: prometheus.yaml
              url: https://raw.githubusercontent.com/prometheus/prometheus/main/documentation/examples/prometheus.yml
            - name: grafana-dashboard.json
              url: https://grafana.com/api/dashboards/1860/revisions/latest/download

Tips and Best Practices

Script Organization

Group related commands using descriptive names
Use comments in YAML to document complex workflows
Chain commands with rav run for reusable components
Keep scripts simple - complex logic belongs in separate files

File Downloads

Always use integrity hashes for security
Organize by purpose (frontend-deps, datasets, configs)
Use descriptive destination paths for better organization
Set appropriate overwrite policies per use case

Project Structure

my-project/
├── rav.yaml              # Main configuration
├── rav.dev.yaml          # Development-specific config
├── rav.prod.yaml         # Production-specific config
├── scripts/              # Complex automation scripts
├── static/vendor/        # Downloaded dependencies
└── data/raw/            # Downloaded datasets

Cross-Platform Compatibility

scripts:
    # Universal commands (recommended)
    test: python -m pytest tests/
    serve: python -m http.server 8000
    
    # Platform-specific alternatives
    serve-win: python -m http.server 8000
    serve-unix: python3 -m http.server 8000

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.claude/commands		.claude/commands
.github/workflows		.github/workflows
rav		rav
.gitignore		.gitignore
README.md		README.md
context7.json		context7.json
pyproject.toml		pyproject.toml
rav.sample.yaml		rav.sample.yaml
rav.yaml		rav.yaml
tox.ini		tox.ini
uv.lock		uv.lock

jmitchel3/rav

Folders and files

Latest commit

History

Repository files navigation

rav

Features

Table of Contents

Install

Quick Start

Option 1: Interactive Setup

Option 2: Manual Setup

CLI Commands Reference

Core Commands

Download Commands

Command Options

Quick Examples

Script Configuration

Flexible Configuration Keys

Basic Syntax

Sample Project

Custom Rav File

Multiple Commands at Once

Variables

Basic Usage

Configuration Keys

Environment Variable Fallback

Variables with Command Groups

View Resolved Variables

Command Groups

Basic Group Syntax

Group Configuration Options

Overriding Group Settings

Real-World Example: Django with Doppler and UV

Multi-Command Groups

Passing Arguments

Expanded List View

File Downloads

Basic Download Configuration

Download Commands

Advanced Download Configuration

Configuration Options

File-Level Overrides

Download Output

Integrity Verification

What is SRI?

Supported Hash Algorithms

Getting SRI Hashes

Using Integrity Verification

Integrity Verification Process

Error Handling

Example Output with Integrity

Security Best Practices

Complete Examples

Web Development Project

Data Science Project

DevOps/Infrastructure Project

Tips and Best Practices

Script Organization

File Downloads

Project Structure

Cross-Platform Compatibility

About

Resources

Uh oh!

Stars

Watchers

Forks

Uh oh!

Contributors 4

Uh oh!

Languages