🛠️ ScriptThing

ScriptThing organizes your scripts, handles Python imports between them, and syncs your dotfiles.

---

Why ScriptThing?

• Create scripts with proper structure instantly
• Share Python functions between scripts without packaging
• Keep scripts organized in repositories
• Sync dotfiles across machines
• Edit and manage everything from one command

---

Quick Start

Installation

# Install from PyPI (recommended)
pip install scriptthing

# Development install
git clone https://github.com/scriptthing/scriptthing.git
cd scriptthing
pip install -e .

Requirements: Python ≥ 3.10

First Steps

# Create your first script
scriptthing new py hello_world

# Add ScriptThing to your shell PATH
eval "$(scriptthing install)"

# Your script is now available everywhere
hello_world

---

Python Modules

Instead of copying functions between scripts or setting up proper Python packages, create simple modules:

# Create a reusable module
scriptthing new module my_utils
scriptthing edit my_utils

# Use it in any script
scriptthing new py data_processor
# data_processor.py can now: from my_utils import clean_data

Modules work across repositories and can be installed into any Python environment without packaging.

---

Built-in Utilities

ScriptThing provides utilities that your scripts can import and use:

# Data formatting and output
from scriptthing.output import from_dict, from_table
from scriptthing.formats import DataParser

# Time and duration parsing
from scriptthing.utils.dates import parse_duration

# Pretty printing and logging
from scriptthing.utils.pretty import printjson
from scriptthing.utils import log, debug, info

# Variable storage with TTL
from scriptthing.utils import store

# Script execution and shell interaction
from scriptthing.shell import Executable, ShellScript

Key Features:

• Data formats: Parse/format JSON, CSV, XML, HTML, Markdown, YAML
• Time utilities: Human-friendly duration parsing ("1h 30m")
• Logging: Structured logging with multiple levels
• Storage: Persistent key-value store with expiration
• Shell integration: Execute scripts and commands programmatically

---

Repository Structure

my-repo/
├── scripts/           # Executable scripts
├── modules/           # Python modules
├── dotfiles/          # Config files to sync
├── functions/         # Shell functions (sourced on demand)
├── extensions/        # Shell extensions (always sourced)
└── .venv/             # Python environment

---

Commands

Script Management

scriptthing new py my_tool           # Create Python script
scriptthing new sh deploy_app       # Create shell script  
scriptthing edit my_tool             # Edit script with smart layout
scriptthing edit script1 script2    # Edit multiple scripts (tabs/splits)
scriptthing ls                       # List all scripts
scriptthing rm my_tool               # Remove script
scriptthing import ./legacy_tool.py # Import existing script

Repository Management

Repositories are collections of scripts, modules, and dotfiles. You can have multiple repositories for different projects or purposes.

ScriptThing creates a default repository at ~/.config/scriptthing/repo for immediate use. Commands without --repo use this default.

scriptthing repos add /path/to/repo     # Add existing repository
scriptthing repos ls                    # List all repositories
scriptthing repos create ./new-repo     # Create new repository
scriptthing repos install <git-url>     # Install remote repository
scriptthing repos refresh               # Update symlinks and dependencies

Dotfile Management

scriptthing dotfiles sync              # Sync dotfiles to home directory
scriptthing dotfiles status            # Show sync status
scriptthing dotfiles conflicts         # Check for conflicts
scriptthing dotfiles hotswap ~/.bashrc other-repo  # Switch versions

Shell Integration

eval "$(scriptthing install)"          # Add to shell startup
scriptthing install --help-text        # Show installation instructions

# Shell extensions are sourced automatically on shell startup
scriptthing new extension my_aliases    # Create shell extension
scriptthing new function my_helper      # Create sourceable function

---

Templates & Languages

ScriptThing includes built-in templates for common script types:

Language	Command	Description
Python	scriptthing new py name	Standard Python script
Shell	scriptthing new sh name	Bash script with proper headers
Argorator	scriptthing new arg name	Shell with advanced argument parsing
Function	scriptthing new function name	Shell function (sourced)
Extension	scriptthing new extension name	Shell extension (always sourced)
Module	scriptthing new module name	Python module for reuse

Template Customization

Templates use Jinja2 and can be customized per repository. Create custom templates by adding them to your repository's template directory.

---

Dotfiles

# Put config files in dotfiles/ directory
my-repo/dotfiles/.bashrc
my-repo/dotfiles/.vimrc

# Sync to home directory
scriptthing dotfiles sync
# Creates: ~/.bashrc -> /path/to/repo/dotfiles/.bashrc

# Handle conflicts when multiple repos have the same file
scriptthing dotfiles conflicts
scriptthing dotfiles hotswap ~/.bashrc preferred-repo

---

Configuration

Repository config in scriptthing.toml:

[repo]
name = "my-scripts"
add_bin_to_path = true

Global config at ~/.config/scriptthing/config.toml

---

Advanced Features

# Edit multiple files with smart layouts
scriptthing edit script1 script2 --tabs

# Install Python packages to repository
scriptthing modules install requests --repo my-project

# Manage variables with expiration
scriptthing vars set API_KEY "secret" --ttl 1h

---

Command Reference

Command	Description
scriptthing new <type> <name>	Create new script from template
scriptthing edit <name>...	Edit scripts with smart layouts
scriptthing ls	List all scripts, functions, extensions
scriptthing rm <name>	Remove script from repository
scriptthing import <path>	Import existing script
scriptthing repos <cmd>	Repository management commands
scriptthing dotfiles <cmd>	Dotfile synchronization commands
scriptthing vars <cmd>	Variable management commands
scriptthing modules <cmd>	Python module management
scriptthing install	Generate shell integration code

---

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/scriptthing/scriptthing.git
cd scriptthing
pip install -e ".[test]"
pytest

---

License

MIT License. See LICENSE for details.

---

Ready to organize your scripts? pip install scriptthing and start building! 🚀