scwrypts/README.md

Scwrypts

Scwrypts is a CLI and API for safely running scripts in the terminal, CI, and other automated environments.

Local runs provide a user-friendly approach to quickly execute CI workflows and automations in your terminal. Each local run runs through an interactive, sandboxed environment so you never accidentally run dev credentials in production ever again!

Major Version Upgrade Notice

Please refer to Version 4 to Version 5 Upgrade Path when upgrading from scwrypts v4 to scwrypts v5!

Installation

Quick installation is supported through both the Arch User Repository and Homebrew

# AUR
yay -Syu scwrypts

# homebrew
brew install wrynegade/scwrypts

Manual Installation

To install scwrypts manually, clone this repository (and take note of where it is installed) Replacing the /path/to/cloned-repo appropriately, add the following line to your ~/.zshrc:

source /path/to/cloned-repo/scwrypts.plugin.zsh

The next time you start your terminal, you can now execute scwrypts by using the plugin shortcut(s) (by default CTRL + SPACE). Plugin shortcuts are configurable in your scwrypts configuration file found in ~/.config/scwrypts/config.zsh, and here is the default config.

If you want to use the scwrypts program directly, you can either invoke the executable ./scwrypts or link it in your PATH for easy access. For example, if you have ~/.local/bin in your PATH, you might run:

ln -s /path/to/cloned-repo/scwrypts "${HOME}/.local/bin/scwrypts"

PATH Dependencies

Scwrypts provides a framework for workflows which often depend on a variety of other tools. Although the lazy-loaded dependency model allows hardening in CI and extendability, the user is expected to resolve required PATH dependencies.

When running locally, this is typically as simple as "install the missing program," but this may require additional steps when working in automated environments.

By default, the ci plugin is enabled which provides the check all dependencies scwrypt. You can run this to output a comprehensive list of PATH dependencies across all scwrypts groups, but, at a bare minimum, you will need the following applications in your PATH:

zsh

grep  # GNU
sed   # GNU
sort  # GNU

fzf   # https://github.com/junegunn/fzf (only required for interactive / local)
jo    # https://github.com/jpmens/jo
jq    # https://github.com/jqlang/jq
yq    # https://github.com/mikefarah/yq

Usage in CI and Automated Environments

Set environment variable CI=true to run scwrypts in an automated environment. There are a few notable changes to this runtime:

• The Scwrypts sandbox environment will not load. All variables will be read directly from the current context.
• User yes/no prompts will always be YES
• Other user input will default to an empty string
• Logs will not be captured in the user's local cache
• In GitHub actions, *.scwrypts.zsh groups are detected automatically from the $GITHUB_WORKSPACE; set SCWRYPTS_GITHUB_NO_AUTOLOAD=true to disable

Contributing

Before contributing an issue, idea, or pull request, check out the super-brief contributing guide