# shuck

> Make any interactive CLI non-interactive

shuck wraps any interactive CLI program in a pseudo-terminal, captures its output, strips ANSI escape sequences and TUI artifacts, and returns clean, pipeable UTF-8 text.

## Docs

- [Introduction](https://shuck.build/docs/getting-started/introduction): What shuck is, why it exists, and how it makes interactive CLIs pipeable for AI agents and automation workflows.
- [Installation](https://shuck.build/docs/getting-started/installation): Install shuck on macOS, Linux, or Windows using cargo, brew, curl, npm, or pip.
- [Quick Start](https://shuck.build/docs/getting-started/quick-start): Run your first shuck command in under 60 seconds.
- [How shuck Works](https://shuck.build/docs/concepts/how-it-works): PTY allocation, VTE ANSI stripping state machine, and process isolation.
- [PTY vs Pipes](https://shuck.build/docs/concepts/pty-vs-pipes): Why interactive CLIs behave differently in PTY vs pipe mode, and when shuck uses each.
- [ANSI Stripping](https://shuck.build/docs/concepts/ansi-stripping): Single-pass VTE state machine that strips escape sequences with zero allocations.
- [CLI Reference](https://shuck.build/docs/reference/cli-reference): Complete documentation for all shuck command-line options and arguments.
- [Exit Codes](https://shuck.build/docs/reference/exit-codes): How child process exit codes are propagated. shuck reserves 124-127 for its own errors.
- [JSON Output](https://shuck.build/docs/reference/json-output): Structured output schema for AI agents and automation scripts.
- [Library API](https://shuck.build/docs/reference/library-api): Use shuck as a Rust library to embed PTY execution in your own programs.
- [Agent Integration](https://shuck.build/docs/guides/agent-integration): Integrate shuck into AI agent pipelines with Python, TypeScript, and bash examples.
- [CI/CD Usage](https://shuck.build/docs/guides/ci-cd-usage): GitHub Actions, GitLab CI, CircleCI configuration. shuck auto-detects CI environments.
- [MCP Server](https://shuck.build/docs/guides/mcp-server): Run shuck as an MCP server so LLMs can call shuck_run directly.
- [Examples](https://shuck.build/docs/guides/examples): Real-world examples — AI tools, Python/Node REPLs, database CLIs, CI patterns.

## Install

```
cargo install shuck
brew install shuck
curl -fsSL https://shuck.build/install.sh | sh
```

## Usage

```
shuck <command> [args...] [-- <input>]
shuck --json echo hello
shuck --timeout 5 slow-command
echo "input" | shuck python3
```

## JSON Output Format

```json
{
  "stdout": "...",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 42,
  "timed_out": false,
  "command": "echo",
  "args": ["hello"]
}
```

## Exit Codes

- 0-123: Child process exit code (passthrough)
- 124: Timeout reached (GNU timeout convention)
- 125: shuck internal error
- 126: Command not executable
- 127: Command not found

## Source

https://github.com/srinitude/shuck