Arguments and Options

Arguments and Options

RubyShell provides intuitive argument handling that converts Ruby hashes into command-line flags.

Positional Arguments

Pass arguments as strings:

sh.git("commit", "-m", "Initial commit")
sh.cp("source.txt", "dest.txt")
sh.mkdir("-p", "path/to/folder")

Flag Options

Single-character flags (-x)

Use single-character symbols or keys:

sh.ls(l: true)           # ls -l
sh.git("status", s: true) # git status -s
sh.rm(r: true, f: true)  # rm -r -f

Multi-character flags (--flag)

Use symbols or strings with multiple characters:

sh.docker("ps", all: true)       # docker ps --all
sh.git("log", oneline: true)     # git log --oneline
sh.grep({ color: "auto" }, "pattern") # grep --color=auto pattern

Flags with Values

sh.git("log", n: 5)              # git log -n 5
sh.docker("run", name: "myapp")  # docker run --name myapp
sh.curl(o: "output.txt", "url")  # curl -o output.txt url

Array Values

Arrays expand into multiple arguments:

sh.git("add", "file1.rb", "file2.rb")
sh.docker({ e: ["VAR1=a", "VAR2=b"] }, "run")  # -e VAR1=a -e VAR2=b run

Mixed Usage

Combine positional arguments with flags:

sh.find(".", type: "f", name: "*.rb")
# find . --type f --name "*.rb"

sh.rsync({ a: true, v: true }, "src/", "dest/")
# rsync -a -v src/ dest/

Internal Options

Options starting with _ are RubyShell-specific and not passed to the command:

Option	Description
_stdin	Pipe input to the command
_debug	Enable debug output for this command
_parse	Parse output as structured data (:json, :yaml, :csv)

sh.wc(l: true, _stdin: "line1\nline2\nline3")  # wc -l (with stdin)
sh.echo("test", _debug: true)                   # Shows debug info

Output Parsing with _parse

Automatically parse command output into Ruby data structures.

Note: Parsers must be required manually before use:

require "rubyshell/parsers/json"
require "rubyshell/parsers/yaml"
require "rubyshell/parsers/csv"

JSON

result = sh.echo('{"name": "Ruby", "version": 3}', _parse: :json)
# => {"name" => "Ruby", "version" => 3}

result["name"]  # => "Ruby"

YAML

result = sh.cat("config.yml", _parse: :yaml)
# => {"database" => {"host" => "localhost", "port" => 5432}}

result["database"]["host"]  # => "localhost"

CSV

result = sh.cat("data.csv", _parse: :csv)
# => [["name", "age"], ["Alice", "30"], ["Bob", "25"]]

result.first  # => ["name", "age"] (header row)

Real-world Examples

# Parse Docker container info
containers = sh.docker("inspect", "mycontainer", _parse: :json)

# Parse kubectl output
pods = sh.kubectl("get", "pods", o: "yaml", _parse: :yaml)

# Parse AWS CLI output
instances = sh.aws("ec2", "describe-instances", output: "json", _parse: :json)

---

Next: Command Chaining