Bun Shell Commands

This skill covers how to write effective shell commands in OpenCode custom commands using Bun Shell (Bun's bash-like shell implementation).

Context

OpenCode uses Bun Shell for executing shell commands in custom commands via the !command syntax. Bun Shell is a bash-like shell written in Zig that provides cross-platform shell scripting, but it has some differences from traditional bash.

Supported Features

✅ Arguments

Positional arguments work correctly:

!`echo "Arg1: $1" && echo "Arg2: $2" && echo "Arg3: $3"`

Usage: /mycommand 5 "hello world" "a,b,c"

✅ Command Substitution

Use $(command) for command substitution:

!`echo "Sum: $(seq $1 | awk '{s+=$1} END {print s}')"`

✅ Pipes

Pipe commands using |:

!`echo "$2" | tr '[:lower:]' '[:upper:]' | rev`

✅ Environment Variables

Set environment variables and use them:

!`TEST_VAR="$1" && echo "TEST_VAR=$TEST_VAR"`

Store command substitution results in variables:

!`REV=$(echo "$2" | rev) && echo "Reversed: $REV"`

✅ Command Chaining

Use && to chain commands (instead of newlines or ;):

!`echo "First" && echo "Second" && echo "Third"`

✅ Available Commands

Bun Shell includes these built-in commands:

• cd, ls, rm, echo, pwd, cat, touch, mkdir, which, mv
• seq, dirname, basename, true, false, yes

Common external commands also work:

• awk, sed, tr, wc, grep, head, tail
• find, xargs, sort, uniq

Unsupported Features

❌ Shell Control Structures

Do NOT use for, while, do, done:

# ❌ DOESN'T WORK
!`for i in $(seq 1 $1); do echo $i; done`

❌ Arithmetic Expansion

Do NOT use $(( )) directly in the template:

# ❌ DOESN'T WORK
!`echo "Squared: $(($1 * $1))"`

Use $(awk '{...}') instead:

# ✅ WORKS
!`echo "$1" | awk '{print $1 * $1}'`

❌ Native Brace Expansion

Native brace expansion is not supported:

# ❌ DOESN'T WORK
!`echo {1,2,3}`

Use pipes to simulate expansion:

# ✅ WORKS
!`echo "$3" | tr ',' '\n' | awk '{print "Expanded:", $1}'`

Patterns and Best Practices

Loops via Pipes

Instead of for loops, use seq with awk:

# Generate numbers 1 to N with squares
!`seq $1 | awk '{print $1, "-> squared:", $1*$1}'`

Multi-step Operations

Use environment variables to store intermediate results:

# Reverse text, count chars, and show both
!`REV=$(echo "$2" | rev) && COUNT=$(echo "$2" | wc -c) && echo "Reversed: $REV (${COUNT} chars)"`

Conditional Logic

Use awk for conditionals:

# Classify numbers as even/odd
!`seq $1 | awk '{if ($1 % 2 == 0) print $1 ": even"; else print $1 ": odd"}'`

Text Processing

Combine tr, sed, awk for text manipulation:

# Uppercase, reverse, and format
!`echo "$2" | tr '[:lower:]' '[:upper:]' | rev | sed 's/^/> /'`

Working with Multiple Arguments

Use separate shell blocks for independent tests:

## Test 1: Arithmetic with $1
!`seq $1 | awk '{s+=$1} END {print "Sum:", s}'`

## Test 2: Text processing with $2
!`echo "$2" | tr '[:lower:]' '[:upper:]' | rev`

## Test 3: Pattern with $3
!`echo "$3" | tr ',' '\n' | wc -l`

Example: Complete Command

---
description: Test Bun Shell capabilities
---

Test Bun Shell with multiple features:

## Argument passing
!`echo "Arg1: [$1]" && echo "Arg2: [$2]" && echo "Arg3: [$3]"`

## Command substitution
!`echo "Sum of 1 to $1: $(seq $1 | awk '{s+=$1} END {print s}')"`

## Text processing
!`echo "$2" | tr '[:lower:]' '[:upper:]' | rev | wc -c`

## Environment variables
!`REV=$(echo "$2" | rev) && echo "Reversed via var: $REV"`

Usage: /mycommand 5 "hello world" "a,b,c"

Debugging

If a shell command fails silently:

1. Simplify to just echo "$1" to verify argument passing
2. Test each pipe segment separately
3. Replace complex awk with simpler tr or sed
4. Use echo at each step to verify intermediate values

References

• Bun Shell Documentation
• OpenCode Commands Documentation