bun-shell-commands

name	bun-shell-commands
description	Writing shell commands for OpenCode custom commands using Bun Shell

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