Quick Start

Once shuck is installed, your agent can run any interactive CLI tool.

Basic Usage

shuck <command> [args...] [-- <stdin-input>]

The simplest case:

shuck echo "hello world"
# hello world

Your First Agent Command

An agent needs to check the PostgreSQL version on a server:

echo "SELECT version();" | shuck psql -U postgres
# PostgreSQL 16.2 on x86_64-pc-linux-gnu ...

Or using the -- separator to pass stdin:

shuck python3 -- "print(2 + 2)"
# 4

JSON Output Mode — The Agent Interface

Use --json (or -j) to get structured output. This is how agents should consume shuck output — it provides exit codes, timing, and clean separation of stdout/stderr:

shuck --json echo "hello"

{
  "stdout": "hello\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 8,
  "timed_out": false,
  "command": "echo",
  "args": ["hello"]
}

Agent Scenarios

Check a Database Schema

# Agent inspects PostgreSQL tables
echo "\dt" | shuck psql -U postgres mydb

# Agent runs a MySQL query and saves results
shuck mysql -u root mydb -- "SHOW TABLES;" > tables.txt

Run Diagnostics

# Agent checks Homebrew health
shuck --json brew doctor

# Agent verifies npm project health
shuck --json npm doctor

Verify a Deployment

# Agent checks if a service is running
shuck --json ssh user@host -- "systemctl is-active myservice"

# Agent inspects container status
shuck --json docker compose ps

Agent Decision Chaining

# Agent runs tests, branches on result
result=$(shuck --json npm test)
exit_code=$(echo "$result" | jq .exit_code)
if [ "$exit_code" -ne 0 ]; then
  echo "Tests failed — reading stderr"
  echo "$result" | jq -r .stderr
fi

Timeout

Set a timeout with --timeout (or -t):

shuck --timeout 10 slow-command
# Exits with code 124 if timeout is reached

Environment Variables

Pass environment variables to the child process:

shuck --env NODE_ENV=production node server.js

Common Patterns

Capture and process output

shuck some-interactive-tool | grep "pattern" | head -20

Save to file

shuck my-cli > output.txt 2>&1

Use in agent scripts

#!/bin/bash
result=$(shuck --json my-interactive-tool -- "some input")
echo "Exit: $(echo "$result" | jq .exit_code)"
echo "Output: $(echo "$result" | jq -r .stdout)"

Next Steps

Back to Home Edit on GitHub