Examples

Real-world examples of agents using shuck to access the interactive CLI ecosystem.

Agent Runs Database Queries

PostgreSQL

# Agent inspects table schema
echo "\dt" | shuck psql -U myuser mydb

# Agent gets a row count
count=$(shuck psql -U myuser mydb -- "SELECT COUNT(*) FROM users;")
echo "Users: $count"

# Agent checks replication status
shuck psql -U postgres -- "SELECT * FROM pg_stat_replication;"

MySQL

# Agent lists tables
shuck mysql -u root mydb -- "SHOW TABLES;"

# Agent checks table structure
shuck mysql -u root mydb -- "DESCRIBE users;"

Redis

# Agent checks a session key
shuck redis-cli -- "GET session:user:42"

# Agent inspects cache state
shuck redis-cli -- "
DBSIZE
INFO memory
"

MongoDB

# Agent counts documents
echo "db.users.countDocuments()" | shuck mongosh mydb

# Agent runs an aggregation
echo "db.orders.aggregate([{\$group: {_id: '\$status', count: {\$sum: 1}}}])" | shuck mongosh mydb

Agent Checks Package Health

# Homebrew health check — agent diagnoses environment issues
shuck brew doctor 2>&1 > health.txt

# Python dependency check — agent finds broken packages
shuck --json pip check

# npm project health — agent verifies project state
shuck --json npm doctor

# Rust toolchain — agent checks installed versions
shuck rustup show

# Go module verification
shuck go mod verify

Agent Debugs Containers

# Agent inspects a running container
shuck docker exec mycontainer cat /etc/hostname

# Agent checks container status with structured output
shuck --json docker compose ps

# Agent reads container logs (ANSI stripped for clean parsing)
shuck docker logs mycontainer --tail 100

# Agent checks container resource usage
shuck docker stats --no-stream

# Agent inspects container networking
shuck docker exec mycontainer ss -tlnp

Agent Manages Git Workflows

# Agent runs an interactive rebase
shuck git rebase -i HEAD~3 -- "pick\npick\nsquash"

# Agent stages specific hunks
shuck git add -p -- "y\nn\ny"

# Agent inspects stash contents
shuck git stash show -p

# Agent runs interactive diff tool
shuck git difftool -- "q"

Agent Inspects System State

# Agent checks service status (pager and color stripped)
shuck systemctl status nginx

# Agent reads recent logs
shuck journalctl -u myservice --no-pager -n 50

# Agent captures system resource snapshot
shuck --timeout 2 top -b -n 1

# Agent checks disk usage
shuck df -h

# Agent inspects network connections
shuck ss -tlnp

Agent Manages Language Versions

# Agent checks installed Node versions
shuck nvm ls

# Agent inspects Python environments
shuck pyenv versions

# Agent verifies Ruby version
shuck rbenv versions

# Agent checks Rust toolchain
shuck rustup show

Agent Runs Remote Commands

# Agent checks disk space on remote host
shuck ssh user@host -- "df -h"

# Agent verifies a remote service
shuck --json ssh user@host -- "systemctl is-active myservice"

# Agent inspects remote logs
shuck ssh user@host -- "journalctl -u myservice -n 20 --no-pager"

Auth-Gated CLI Tools

# GitHub CLI (authenticated via GH_TOKEN)
shuck gh pr list --repo myorg/myrepo > open-prs.txt

# AWS CLI (authenticated via env vars or ~/.aws/credentials)
shuck aws s3 ls > buckets.txt

# Docker registry operations
shuck docker pull myregistry.io/myimage:latest 2>&1 | tee pull.log

# Kubernetes
shuck kubectl get pods -n production > pods.txt

Agent Decision Chaining

The --json flag is designed for agents to chain shuck output into decision-making:

Run tests and branch on result

#!/bin/bash
result=$(shuck --json --timeout 120 npm test)
exit_code=$(echo "$result" | jq .exit_code)

if [ "$exit_code" -eq 0 ]; then
  echo "Tests passed"
else
  echo "Tests failed — stderr:"
  echo "$result" | jq -r .stderr
  exit 1
fi

Parallel tool execution

# Agent runs multiple checks in parallel, collects results
for tool in "pip check" "npm doctor" "rustup show"; do
  shuck --json $tool > "results/$(echo $tool | tr ' ' '-').json" &
done
wait
echo "All diagnostics collected"

Structured task runner

#!/bin/bash
task="$1"
result=$(shuck --json --timeout 120 run-task "$task")

echo "Task: $task"
echo "Exit: $(echo "$result" | jq .exit_code)"
echo "Time: $(echo "$result" | jq .duration_ms)ms"
echo "Output:"
echo "$result" | jq -r .stdout

Debugging Tips

# See what shuck is doing (verbose mode)
shuck --verbose my-tool

# See raw PTY output before stripping
shuck --raw my-tool | cat -v

# Check timing
shuck --json my-tool | jq .duration_ms