opsh

name	opsh
description	Write scripts using opsh and its built-in libraries. Load this skill when writing, reviewing, or debugging opsh scripts.

opsh Scripting

opsh is a scripting environment for operations use. It is a curated bash environment with sensible defaults and a standard library. Scripts are bash, but opsh sets strict runtime options and provides a library ecosystem accessed via lib::import.

Script Structure

Every opsh script starts with:

#!/usr/bin/env opsh

lib::import git semver   # import libraries you need

# your script here

opsh can also be sourced into an existing bash script:

#!/usr/bin/env bash
source opsh
lib::import git

Runtime Defaults

opsh sets these options before your script runs. Do not disable them.

Setting	Effect
set -e (errexit)	Non-zero return terminates unless caught
set -u (nounset)	Referencing an unset variable is fatal
set -o pipefail	A pipeline fails if any command in it fails
IFS=''	Word splitting is disabled by default
shopt -s inherit_errexit	Command substitutions inherit errexit
set -o errtrace	ERR traps propagate into functions and subshells

The IFS='' default is important. Unquoted $var where var="a b c" stays as a single string, not three words. Use array::split when you actually need to split a string.

Global Variables

These are set by opsh before your script runs:

Variable	Description
$SCRIPTFILE	Absolute path to your script
$SCRIPTDIR	Directory containing your script
$TMPDIR	Managed temp directory, cleaned up on exit
$OPSHROOTDIR	Root of the opsh installation
$DEBUG	Set this (any value) to enable log::debug

Color variables $CRED, $CGRN, $CYEL, $CBLU, $CNONE are available and are automatically empty when output is not a terminal.

Import System

lib::import <name> [name2 ...]

• Imports are idempotent; importing the same library twice is safe.
• Libraries can declare their own dependencies (e.g. ssh imports path, cloud-init imports command).
• If a library is not found, the script dies via log::fatal.
• Multiple libraries can be imported in a single call.

Naming Convention

All opsh functions use module::function naming with :: as the namespace separator. Follow this convention in your own scripts:

deploy::prepare() { ... }
deploy::execute() { ... }
deploy::cleanup() { ... }

Core Functions (Always Available)

Logging

All log output goes to stderr. Messages are colorized when stderr is a terminal.

Function	Behavior
log::debug	Blue output, only when $DEBUG is set
log::info	Green output
log::warn	Yellow output
log::error	Red output
log::fatal	Red output, then exit 1

log::info "deploying version $VERSION..."
log::fatal "config file not found"

Exit Triggers

Register cleanup functions that run on exit in LIFO (last-in, first-out) order:

exit::trigger <function_or_command> [args...]

start-service() { ... }
stop-service() { ... }

start-service
exit::trigger stop-service    # guaranteed to run on exit

Multiple triggers are supported. They run in reverse registration order.

Temporary Files

$TMPDIR is a managed directory that is automatically removed on exit. Create files and directories inside it:

temp::file [mktemp_args...]   # create a temp file in $TMPDIR
temp::dir  [mktemp_args...]   # create a temp directory in $TMPDIR

scratch=$(temp::file)
echo "data" > "$scratch"
# no cleanup needed; $TMPDIR is removed on exit

Array Utilities

array::join <delimiter> <element1> [element2 ...]
array::split <nameref> <delimiter> <string>

parts=(one two three)
array::join , "${parts[@]}"       # stdout: one,two,three

array::split result ":" "$PATH"   # result is now an array

Version Management

opsh::version                     # print the opsh version
opsh::version::require <min>      # fatal if opsh is too old

opsh::version::require 0.9.0

Libraries

command

lib::import command

Function	Description
command::exists	Returns 0 if command is in $PATH

command::exists docker || log::fatal "docker is required"

path

lib::import path

Function	Description
path::env::add	Prepend directories to $PATH
path::env::remove	Remove a directory from $PATH

path::env::add /opt/mytools/bin
path::env::remove /usr/local/old/bin

git

lib::import git

Function	Description
git::repo::version	Version from git describe --tags --dirty or short SHA
git::repo::current-branch	Current branch name
git::repo::is-clean	Returns 0 if working tree is clean
git::tag::exists	Returns 0 if a local tag exists
git::tag::lookup::remote	Lookup a tag on a remote; prints commit hash

git::tag::lookup::remote returns 1 if the tag is not found, 2 if ambiguous.

VERSION=$(git::repo::version)
git::repo::is-clean || log::fatal "working tree is dirty"

semver

lib::import semver

Function	Description
semver::parse	Parse into $OPSH_SEMVER array [major, minor, patch]
semver::test	Compare two versions: -eq, -gt, -lt, -ge, -le
semver::bump	Bump major, minor, or patch; prints new version

semver::parse populates the global $OPSH_SEMVER array. If the version has a suffix (e.g. -rc1, +build), it appears as a fourth element.

semver::parse v2.1.0 || log::fatal "bad version"
echo "major: ${OPSH_SEMVER[0]}"  # 2

semver::test "$current" -ge "$minimum" || log::fatal "version too old"

new=$(semver::bump minor v1.2.3)  # v1.3.0

ssh

lib::import ssh

Function	Description
ssh::begin	Start SSH context: agent, proxied ssh, config
ssh::end	Tear down SSH context
ssh::config	Append SSH config from stdin
ssh::key::add	Add keys from files or stdin to the agent
ssh::background::run	Launch SSH port forwarding in background
ssh::background::close	Close background port forwarding

ssh::begin creates an isolated SSH agent, a proxied ssh binary that uses a managed config file, and registers ssh::end as an exit trigger. Everything between ssh::begin and ssh::end uses this isolated context.

ssh::begin
ssh::config <<'EOF'
Host bastion
    User deploy
    HostName bastion.example.com
EOF
ssh::key::add ~/.ssh/deploy_key
ssh bastion "uptime"
ssh::end

cloud-init

lib::import cloud-init

Function	Description
cloud-init::is-enabled	Returns 0 if cloud-init is present
cloud-init::wait-for-finish	Blocks until cloud-init completes

if cloud-init::is-enabled; then
    log::info "waiting for cloud-init..."
    cloud-init::wait-for-finish
fi

step-runner

lib::import step-runner

Function	Description
steps::run	Run all prefix::* functions in alphabetical order

Define functions with a shared prefix, then run them:

deploy::01-build() { ... }
deploy::02-test()  { ... }
deploy::03-push()  { ... }

steps::run deploy           # runs all three in order
steps::run deploy 02-test   # starts from 02-test

steps::run logs each step as it executes. Use numbered prefixes to control ordering.

test-harness

lib::import test-harness

Function	Description
testing::register	Register a test function with a description
testing::run	Execute all tests, output TAP v13
testing::fail	Fail the current test with a message

See the "Writing Tests" section below.

Common Idioms

Fatal preconditions

Use || log::fatal for conditions that must be true:

[[ -f $CONFIG ]] || log::fatal "config not found: $CONFIG"
command::exists kubectl || log::fatal "kubectl is required"

Recoverable errors

Capture the return code when you need to handle failure:

local ret=0
some-command || ret=$?
if [[ $ret -ne 0 ]]; then
    log::warn "command failed with $ret, retrying..."
fi

Cleanup with exit triggers

Register cleanup in the order you acquire resources. They run in reverse:

start-database
exit::trigger stop-database

start-server
exit::trigger stop-server
# on exit: stop-server runs first, then stop-database

Default values

Use the ${var:=default} pattern (standard bash parameter expansion). The : builtin discards the result while still triggering assignment:

: "${DEPLOY_ENV:=staging}"
: "${RETRIES:=3}"

Writing Tests

Test files use the test-harness library and output TAP v13 format. They are typically run with prove:

#!/usr/bin/env opsh

lib::import test-harness

check-something() {
    local result
    result=$(my-function)
    [[ $result = "expected" ]] || testing::fail "got: $result"
}

testing::register check-something "verify my-function output"

check-another-thing() {
    my-precondition || testing::fail
    my-action || testing::fail "action failed"
}

testing::register check-another-thing "verify action succeeds"

testing::run

Key patterns:

• Use || testing::fail as an assertion. Optionally pass a message.
• Each test function runs in a subshell, so variable changes do not leak between tests.
• Register all tests before calling testing::run.
• Use $SCRIPTDIR to locate fixture files and shared utilities relative to the test file.
• Source shared test helpers with source "$SCRIPTDIR/utils.opsh".

Checking command output

A common pattern uses diff -u against a heredoc to verify output:

check-output() {
    local outfile
    outfile=$(temp::file)

    my-command > "$outfile"

    diff -u - "$outfile" <<EOF || testing::fail
expected output here
EOF
}

Checking return codes

check-failure() {
    local ret=0
    bad-command || ret=$?
    [[ $ret -eq 1 ]] || testing::fail "expected exit 1, got $ret"
}

Formatting and Linting

When available:

• Format with: shfmt
• Lint with: shellcheck -s bash -x

Quick Reference

lib::import <lib>             # import a library
log::{debug,info,warn,error}  # log to stderr
log::fatal                    # log and exit 1
exit::trigger <func>          # register cleanup (LIFO)
temp::file / temp::dir        # create managed temp files
array::join <delim> <args>    # join to stdout
array::split <ref> <delim> <s># split into named array
command::exists <cmd>         # check PATH for a command
path::env::add <dir>          # prepend to $PATH
path::env::remove <dir>       # remove from $PATH
git::repo::version            # repo version string
git::repo::current-branch     # current branch name
git::repo::is-clean           # clean working tree?
git::tag::exists <tag>        # local tag exists?
semver::parse <ver>           # parse into $OPSH_SEMVER
semver::test <a> <op> <b>     # compare versions
semver::bump <pos> <ver>      # bump major/minor/patch
ssh::begin / ssh::end         # SSH context lifecycle
ssh::config <<EOF             # append SSH config
ssh::key::add [files]         # add keys to agent
steps::run <prefix> [start]   # run prefixed functions
testing::register <fn> [desc] # register a test
testing::run                  # execute all tests (TAP v13)
testing::fail [msg]           # fail current test