CLI Reference

Synopsis

shuck [OPTIONS] <COMMAND> [ARGS...] [-- <INPUT>]

Arguments

`<COMMAND>`

The CLI program to run non-interactively. shuck will search your $PATH for the command.

shuck python3
shuck /usr/local/bin/node

`[ARGS...]`

Arguments to pass to the command. Passed verbatim after the command name.

shuck python3 -c "print('hello')"
shuck node --version
shuck git log --oneline -10

`[-- <INPUT>]`

Input to feed to the command’s stdin via the -- separator. Everything after -- is treated as a single string of stdin input.

shuck python3 -- "print('hello')"
shuck node -- "console.log(process.version)"

Options

`-i, --input <TEXT>`

Input text to feed to the child’s stdin.

shuck python3 -i "print('hello')"

`-f, --input-file <PATH>`

Read stdin input from a file.

shuck python3 -f script.py
shuck node -f index.js

`-t, --timeout <SECS>`

Timeout in seconds. Defaults to 30. Set to 0 to disable.

shuck --timeout 60 long-running-command
shuck --timeout 0 forever-command   # no timeout

If the timeout is reached, the child is killed and shuck exits with code 124 (GNU timeout convention).

`-s, --stream`

Stream output in real-time before cleaning. Useful for monitoring long-running commands while still stripping ANSI at the end.

shuck --stream long-running-build

`-r, --raw`

Don’t strip ANSI/control sequences. Pass raw PTY output directly to stdout.

shuck --raw colorful-tool > raw.txt

`-q, --quiet`

Suppress stderr from the child process. By default, stderr is forwarded to shuck’s stderr.

shuck --quiet noisy-tool

`-j, --json`

Output structured JSON instead of plain text. See JSON Output for the full schema.

shuck --json echo "hello"
# {"stdout":"hello\n","stderr":"","exit_code":0,"duration_ms":5,...}

`-e, --env <KEY=VALUE>`

Set an environment variable for the child process. Repeatable.

shuck --env DEBUG=1 --env NODE_ENV=production node server.js

`--no-pty`

Don’t allocate a PTY. Use plain pipes instead. Auto-detected when $CI is set.

shuck --no-pty cat /etc/hosts

See PTY vs Pipes for when to use this.

`--shell <SHELL>`

Run the command through a shell. Useful for shell builtins or complex pipelines.

shuck --shell bash -- "echo $HOSTNAME"
shuck --shell zsh -- "print -l ${(f)$(ls)}"

`--cols <N>`

PTY column width. Defaults to 80. Affects how tools wrap their output.

shuck --cols 120 wide-tool

`--rows <N>`

PTY row count. Defaults to 24.

shuck --rows 50 tall-tool

`-v, --verbose`

Show diagnostics on stderr: PTY dimensions, timing, child PID.

shuck --verbose my-tool

`-h, --help`

Print help and exit.

`-V, --version`

Print version and exit.

Exit Codes

Code	Meaning
0–123	Child process exit code (passthrough)
124	Child timed out (`--timeout` reached)
125	shuck internal error
126	Command found but not executable
127	Command not found

See Exit Codes for full details.

Environment Variables

Variable	Effect
`CI=true`	Auto-enables `--no-pty` mode
`SHUCK_TIMEOUT`	Default timeout in seconds (overridden by `--timeout`)
`NO_COLOR`	Disables color in shuck’s own diagnostic output

Examples

# Basic usage
shuck echo "hello world"

# Capture interactive CLI output
shuck mysql -u root mydb -- -e "SHOW TABLES" > tables.txt

# JSON mode for agents
shuck --json python3 -- "import sys; print(sys.version)"

# With timeout
shuck --timeout 5 slow-command

# Pass environment variable
shuck --env TERM=xterm-256color colorful-tool

# Force no PTY (CI mode)
shuck --no-pty make test

# Wide terminal
shuck --cols 200 wide-table-command

Back to Home Edit on GitHub