rubyshell 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef414945c6e9fc58ca5320103e4abf00d551737dffadd06e171e8ca37330752b
-  data.tar.gz: d1784dc8f6ba9a21ea7e0da4fbde153b4f2f6d980037b572e02fe3c8b86a2e49
+  metadata.gz: 69051d4ef363ab387d6a7a92f4cdfa12ea51dd71983ebedf11583ca891ce00e4
+  data.tar.gz: 9bd6d572911e0c494833a8ab459b69c7648aacdaf18e13be95a03b7ff6270687
 SHA512:
-  metadata.gz: a993d2b94f11e041a10dafb537a4bfb6395c3d06f81ed19da5cb3fb0b1a5e290d08fe310ee34592447aa90ce0910e714b35941c2bef78f1dbe0fa8abb7692348
-  data.tar.gz: 146e1d266782ea61c73776799d7beadce9fcba0e1659edcf253c85e5c9ae57f143a39e27479d12394ee469bf589185a218ebb007b6b2fd7a6782606ec20a67c9
+  metadata.gz: 6d17ebb0eae8370dc331dc55cf45bb357d7f83841e2845db69af3da128ca128da3c284468d234230ab0faf4b374202cc374d45bf27adecf99dc79f547481c9b5
+  data.tar.gz: bfe7a64951d3fb6ddd5ca5988de9afcd90ef6cc5bf66fba063796c004103028daa20c33c373bb75de1b26d317702ff03771ff37499a5ef3c10100d5912bcbdcf

data/CHANGELOG.md

@@ -1,5 +1,116 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
 ## [Unreleased]
 
-## [0.1.0] - 2025-09-10
+### Added
+
+- **Parallel Execution** ([#34](https://github.com/albertalef/rubyshell/pull/34))
+  ```ruby
+  sh do
+    results = parallel do
+      curl("https://api1.example.com")
+      curl("https://api2.example.com")
+      chain { ls | wc("-l") }
+    end
+
+    results.each { |r| puts r }
+  end
+  ```
+  - Returns an Enumerator with results in completion order
+  - Supports regular commands, chains, and `sh()` calls
+  - Errors are captured and returned as values (not raised)
+
+- **Chain Options** ([#34](https://github.com/albertalef/rubyshell/pull/34))
+  ```ruby
+  # Debug mode for chains
+  chain(debug: true) { ls | grep("test") }
+
+  # Parse chain output
+  chain(parse: :json) { curl("https://api.example.com") }
+  ```
+
+- **Environment Variables** ([#47](https://github.com/albertalef/rubyshell/pull/47))
+  ```ruby
+  # Command-level
+  sh.npm("start", _env: { NODE_ENV: "production" })
+
+  # Block-level
+  sh(env: { DATABASE_URL: "postgres://localhost/db" }) do
+    rake("db:migrate")
+  end
+
+  # Global
+  RubyShell.env[:API_KEY] = "secret"
+  RubyShell.config(env: { DEBUG: "true" })
+  ```
+
+- **Debug Mode** ([#39](https://github.com/albertalef/rubyshell/pull/39))
+  ```ruby
+  # Global
+  RubyShell.debug = true
+
+  # Block scope
+  RubyShell.debug { sh.ls }
+
+  # Per command
+  sh.git("status", _debug: true)
+  ```
+
+- **Output Parsers** ([#38](https://github.com/albertalef/rubyshell/pull/38))
+  ```ruby
+  sh.cat("data.json", _parse: :json)   # => Hash
+  sh.cat("config.yml", _parse: :yaml)  # => Hash
+  sh.cat("users.csv", _parse: :csv)    # => Array
+  ```
+
+### Changed
+
+- **BREAKING:** Renamed `_env` to `env` in `RubyShell.config` and `sh` block options ([#34](https://github.com/albertalef/rubyshell/pull/34))
+  ```ruby
+  # Before
+  RubyShell.config(_env: { DEBUG: "true" })
+  sh(_env: { NODE_ENV: "production" }) { ... }
+
+  # After
+  RubyShell.config(env: { DEBUG: "true" })
+  sh(env: { NODE_ENV: "production" }) { ... }
+  ```
+  Note: Command-level `_env` option remains unchanged.
+
+- Refactored specs directory structure
+
+
+## [1.4.0] - 2026-01-23
+
+### Added
+
+- **Executable generator** ([#29](https://github.com/albertalef/rubyshell/pull/29))
+  ```bash
+  $ rubyshell new myscript
+  # Creates executable file with chmod +x
+  ```
+
+- **Stdin parameter support**
+  - `_stdin` option to pass string or command output to stdin
+  ```ruby
+  xclip(_stdin: "text")
+  wc("-l", _stdin: some_command!)
+  ```
+
+- **Array values in hash params**
+  ```ruby
+  sed(e: ["one", "two", "three"])
+  # equivalent to: sed -e 'one' -e 'two' -e 'three'
+  ```
+
+- **Direct command execution for special syntax**
+  ```ruby
+  sh("notify-send", "hello")
+  sh("wl-copy", text)
+  ```
+
+## Previous
 
-- Initial release
+- Not Tracked

data/README.md

@@ -2,7 +2,7 @@
   <img alt="RubyShell" src="./docs/images/rubyshelllogo.png" width="60%">
 </h1>
 
-<h3 align="center">✨ Rubist way to create shell scripts ✨</h3>
+<h3 align="center">The Rubyist way to write shell scripts</h3>
 
 <p align="center">
   <a href="https://rubygems.org/gems/rubyshell">
@@ -23,11 +23,11 @@
     ·
     <a href="#usage">Usage</a>
     ·
-    <a href="#complete-example">Examples</a>
+    <a href="https://github.com/albertalef/rubyshell/wiki">Wiki</a>
     ·
-    <a href="#contributing">Contributing</a>
+    <a href="#real-world-examples">Examples</a>
     ·
-    <a href="#sponsors">Sponsors</a>
+    <a href="#contributing">Contributing</a>
   </p>
 </p>
 <br />
@@ -41,162 +41,412 @@
   end
 ```
 
-Yes, that’s valid Ruby!
+Yes, that's valid Ruby!
 `ls` and `cat` are just shell commands, but **RubyShell** makes them behave like Ruby methods.
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+```bash
+bundle add rubyshell
+```
+
+Or install directly:
+
+```bash
+gem install rubyshell
+```
+
+## Why RubyShell?
+
+### The Problem
+
+Ever written something like this?
+
+```bash
+# Bash: Find large files modified in the last 7 days, show top 10 with human sizes
+find . -type f -mtime -7 -exec ls -lh {} \; 2>/dev/null | \
+  awk '{print $5, $9}' | \
+  sort -hr | \
+  head -10
+```
+
+Or tried to do error handling in bash?
 
-    $ bundle add rubyshell
+```bash
+# Bash: Hope nothing goes wrong...
+output=$(some_command 2>&1) || echo "failed somehow"
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### The Solution
 
-    $ gem install rubyshell
+```ruby
+sh do
+  # Ruby + Shell: Same task, actually readable
+  find(".", type: "f", mtime: "-7")
+    .lines
+    .map { |f| [File.size(f.strip), f.strip] }
+    .sort_by(&:first)
+    .last(10)
+    .each { |size, file| puts "#{size / 1024}KB  #{file}" }
+rescue RubyShell::CommandError => e
+  puts "Failed: #{e.message}"
+  puts "Exit code: #{e.status}"
+end
+```
 
 ## Usage
 
-### Calling a shell command
-With RubyShell, every shell command can be used inside the ruby, you just need to call
+### Basic Commands
 
 ```ruby
+require 'rubyshell'
+
 sh do
-  puts pwd # => /Users/albertalef/projects/rubyshell
+  pwd                        # Run any command
+  ls("-la")                  # With arguments
+  mkdir("project")           # Create directories
+  docker("ps", all: true)    # --all flag
+  git("status", s: true)     # -s flag
 end
+
+# Or chain directly
+sh.git("log", oneline: true, n: 5)
 ```
 
-### Using without the block
-If you want to start an irb or pry session, and run commands as first-class citizens then do the following.
+### Pipelines
 
 ```ruby
-extend RubyShell::Executor
+sh do
+  # Using chain block
+  chain { cat("access.log") | grep("ERROR") | wc("-l") }
 
-pwd # => /Users/albertalef/projects/rubyshell
+  # Using bang pattern
+  (cat!("data.csv") | sort! | uniq!).exec
+end
 ```
 
-### Passing arguments
-Here we have different ways to pass arguments to a command.
-You can separate strings, use only one, use hashes, anyway will work
+### Directory Scoping
 
 ```ruby
 sh do
-  docker("ps", all: true) # Using hash syntax = docker ps --all
+  cd "/var/log" do
+    # Commands run here, then return to original dir
+    tail("-n", "100", "syslog")
+  end
+  # Back to original directory
+end
+```
 
-  docker("ps", a: true) # Using hash syntax = docker ps -a
+### Error Handling
 
-  docker("ps", '-a') # Passing multiple strings = docker ps -a
+```ruby
+sh do
+  begin
+    rm("-rf", "important_folder")
+  rescue RubyShell::CommandError => e
+    puts "Command: #{e.command}"
+    puts "Stderr: #{e.stderr}"
+    puts "Exit code: #{e.status}"
+  end
+end
+```
+
+### Parallel Execution
 
-  docker("ps -a") # Passing one string = docker ps -a
+Run multiple commands concurrently and get results as they complete:
+
+```ruby
+sh do
+  results = parallel do
+    curl("https://api1.example.com")
+    curl("https://api2.example.com")
+    chain { ls | wc("-l") }
+  end
+
+  results.each { |r| puts r }
 end
 ```
 
-### Changing folder
-Has two possible ways, changing the folder of the code, or running code only inside a folder 
+Returns an Enumerator with results in completion order. Errors are captured and returned as values (not raised).
+
+### Environment Variables
+
+```ruby
+# Command-level
+sh.npm("start", _env: { NODE_ENV: "production" })
+
+# Block-level
+sh(env: { DATABASE_URL: "postgres://localhost/db" }) do
+  rake("db:migrate")
+end
+
+# Global
+RubyShell.env[:API_KEY] = "secret"
+RubyShell.config(env: { DEBUG: "true" })
+```
+
+### Debug Mode
+
+```ruby
+# Global
+RubyShell.debug = true
+
+# Block scope
+RubyShell.debug { sh.ls }
+
+# Per command
+sh.git("status", _debug: true)
+# Output:
+#   Executed: git status
+#   Duration: 0.003521s
+#   Pid: 12345
+#   Exit code: 0
+#   Stdout: "On branch main..."
+```
+
+### Output Parsers
+
+Parse command output directly into Ruby objects:
+
+```ruby
+sh.cat("data.json", _parse: :json)   # => Hash
+sh.cat("config.yml", _parse: :yaml)  # => Hash
+sh.cat("users.csv", _parse: :csv)    # => Array
+```
+
+### Chain Options
+
+```ruby
+# Debug mode for chains
+chain(debug: true) { ls | grep("test") }
+
+# Parse chain output
+chain(parse: :json) { curl("https://api.example.com") }
+```
+
+## Real-World Examples
+
+### Git Workflow Automation
 
-##### Chaging code folder
 ```ruby
 sh do
-  puts pwd # => /Users/albertalef/projects/rubyshell
+  # Stash changes, pull, pop, and show what changed
+  changes = git("status", porcelain: true).lines
+
+  if changes.any?
+    puts "Stashing #{changes.count} changed files..."
+    git("stash")
+    git("pull", rebase: true)
+    git("stash", "pop")
+  else
+    git("pull", rebase: true)
+  end
 
-  cd 'examples'
+  # Show recent commits by author
+  git("log", oneline: true, n: 100)
+    .lines
+    .map { |line| `git show -s --format='%an' #{line.split.first}`.strip }
+    .tally
+    .sort_by { |_, count| -count }
+    .first(5)
+    .each { |author, count| puts "#{author}: #{count} commits" }
+end
+```
+
+### Log Analysis
 
-  puts pwd  # => /Users/albertalef/projects/rubyshell/examples
+```ruby
+sh do
+  cd "/var/log" do
+    # Parse nginx logs: top 10 IPs by request count
+    cat("nginx/access.log")
+      .lines
+      .map { |line| line.split.first }  # Extract IP
+      .tally
+      .sort_by { |_, count| -count }
+      .first(10)
+      .each { |ip, count| puts "#{ip.ljust(15)} #{count} requests" }
+  end
 end
 ```
 
-##### Executing code inside another folder
+### Docker Cleanup
 
 ```ruby
 sh do
-  cd 'examples' do
-    puts pwd  # => /Users/albertalef/projects/rubyshell/examples
+  # Remove containers that exited more than a day ago
+  containers = docker("ps", a: true, format: "{{.ID}} {{.Status}}")
+    .lines
+    .select { |line| line.include?("Exited") }
+    .map { |line| line.split.first }
+
+  if containers.any?
+    puts "Removing #{containers.count} dead containers..."
+    docker("rm", *containers)
   end
 
-  puts pwd  # => /Users/albertalef/projects/rubyshell
+  # Remove dangling images
+  images = docker("images", f: "dangling=true", q: true).lines.map(&:strip)
+
+  if images.any?
+    puts "Removing #{images.count} dangling images..."
+    docker("rmi", *images)
+  end
+
+  puts "Disk usage:"
+  puts docker("system", "df")
 end
 ```
 
-### Chaining commands
-The `chain` method make possible we use shell operators inside the ruby, like `& && | > >> < <<`
+### Batch File Processing
 
 ```ruby
 sh do
-  chain { echo "Dummy text" >> "dummy.txt" }
-  
-  puts cat("dummy.txt") # => "Dummy text"
+  # Convert all PNGs to WebP, preserving directory structure
+  find(".", name: "*.png")
+    .lines
+    .map(&:strip)
+    .each do |png|
+      webp = png.sub(/\.png$/, ".webp")
+      puts "Converting: #{png}"
+
+      begin
+        cwebp("-q", "80", png, o: webp)
+        rm(png)
+      rescue RubyShell::CommandError => e
+        puts "  Failed: #{e.message}"
+      end
+    end
 end
+```
 
+### System Health Check
+
+```ruby
 sh do
-  number_of_files = chain { ls | wc('-l') }.chomp
+  puts "=== System Health ==="
+
+  # Disk usage warnings
+  df("-h")
+    .lines
+    .drop(1)
+    .each do |line|
+      parts = line.split
+      usage = parts[4].to_i
+      mount = parts[5]
+      puts "WARNING: #{mount} at #{usage}%" if usage > 80
+    end
 
-  puts number_of_files # => 5
+  # Memory info
+  mem = cat("/proc/meminfo")
+    .lines
+    .first(3)
+    .to_h { |l| k, v = l.split(":"); [k, v.strip] }
+
+  puts "\nMemory: #{mem['MemAvailable']} available of #{mem['MemTotal']}"
+
+  # Top 5 CPU consumers
+  puts "\nTop CPU processes:"
+  ps("aux", sort: "-%cpu")
+    .lines
+    .drop(1)
+    .first(5)
+    .each { |proc| puts "  #{proc.split[10]}% - #{proc.split[10..-1].join(' ').slice(0, 40)}" }
 end
 ```
 
-### Executing without a block
-The `sh` method can receive any method call, and execute shell commands
+### Interactive Script with Confirmation
 
 ```ruby
-sh.puts pwd # => /Users/albertalef/projects/rubyshell
+sh do
+  files = find(".", name: "*.tmp", mtime: "+30").lines.map(&:strip)
+
+  if files.empty?
+    puts "No old temp files found."
+    exit
+  end
 
-sh.cd 'examples'
+  puts "Found #{files.count} temp files older than 30 days:"
+  files.first(10).each { |f| puts "  #{f}" }
+  puts "  ... and #{files.count - 10} more" if files.count > 10
 
-puts sh.pwd  # => /Users/albertalef/projects/rubyshell/examples
+  total_size = files.sum { |f| File.size(f) rescue 0 }
+  puts "\nTotal size: #{total_size / 1024 / 1024}MB"
+
+  print "\nDelete all? [y/N] "
+  if gets.strip.downcase == 'y'
+    files.each { |f| rm(f) }
+    puts "Deleted #{files.count} files."
+  end
+end
 ```
 
-## Complete example
+### Deploy Script
 
 ```ruby
 #!/usr/bin/env ruby
+require 'rubyshell'
 
-require "rubyshell"
-require "securerandom"
+APP_NAME = "myapp"
+DEPLOY_PATH = "/var/www/#{APP_NAME}"
 
 sh do
-  mkdir "files"
+  puts "Deploying #{APP_NAME}..."
 
-  cd "files" do
-    5.times do |i|
-      chain do
-        echo(SecureRandom.alphanumeric(16)) >> "#{i}.txt"
-      end
-    end
+  # Ensure clean state
+  git("status", porcelain: true).lines.tap do |changes|
+    abort "Uncommitted changes!" if changes.any?
+  end
 
-    puts "Number of Files: #{ls.lines.count}"
+  # Run tests
+  puts "Running tests..."
+  rake("spec")
 
-    ls.each_line do |filename|
-      puts cat(filename)
-    end
+  # Build and deploy
+  cd DEPLOY_PATH do
+    git("pull", "origin", "main")
+    bundle("install", deployment: true)
+    rake("db:migrate")
+
+    # Restart with zero downtime
+    puts "Restarting..."
+    systemctl("reload", APP_NAME)
   end
-ensure
-  rm "-rf files"
-end
 
-# Running:
-#
-# ❯ ./examples/example1.rb
-#
-# Number of Files: 5
-# o6Kw8KHvWJnLGSeQ
-# qkRKcZHqu2Moq1se
-# nUPluln9GM1ydtoz
-# rkdYsc1RBhkeN1dq
-# ZPXZMqzYfyFfjPHF
+  puts "Deployed successfully!"
+
+rescue RubyShell::CommandError => e
+  puts "Deploy failed: #{e.message}"
+  exit 1
+end
 ```
 
-## Coming
+## Comparison
 
-- Support to Streams
+| Task | Bash | RubyShell |
+|------|------|-----------|
+| Error handling | `cmd \|\| echo "fail"` | `rescue CommandError` |
+| String manipulation | `echo $var \| sed \| awk` | `result.gsub(/.../)` |
+| Data structures | Arrays only | Hashes, objects, classes |
+| Iteration | `for f in *; do` | `.each`, `.map`, `.select` |
+| Testing | DIY | RSpec, Minitest |
 
-## Development
+## Documentation
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+See [Wiki](https://github.com/albertalef/rubyshell/wiki) for complete documentation including all options and advanced features.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Development
+
+```bash
+bin/setup          # Install dependencies
+rake spec          # Run tests
+rake rubocop       # Lint code
+bin/console        # Interactive console
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/albertalef/rubyshell. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/albertalef/rubyshell/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/albertalef/rubyshell).
 
 ## Sponsors
 
@@ -206,8 +456,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/albert
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Rubysh project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/albertalef/rubyshell/blob/master/CODE_OF_CONDUCT.md).
+MIT License - see [LICENSE](https://opensource.org/licenses/MIT).

data/lib/rubyshell/chain_context.rb

@@ -2,15 +2,22 @@
 
 module RubyShell
   class ChainContext
-    def self.sh(command, *args)
+    def initialize(options = {})
+      @options = options
+    end
+
+    def sh(command, *args)
       method_missing(command, *args)
     end
 
-    def self.method_missing(method_name, *args, &block)
-      RubyShell::Chainer.new(RubyShell::Command.new(method_name, *(args << { _manual: true }), &block))
+    def method_missing(method_name, *args, &block)
+      RubyShell::Chainer.new(
+        RubyShell::Command.new(method_name, *args, &block),
+        @options
+      )
     end
 
-    def self.respond_to_missing?(_name, _include_private)
+    def respond_to_missing?(_name, _include_private)
       false
     end
   end

data/lib/rubyshell/chainer.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
+require "debug"
 module RubyShell
   class Chainer
-    attr_reader :parts
+    attr_reader :parts, :options
 
     def initialize(command, options = {})
       @parts = [command]
@@ -19,6 +20,14 @@ module RubyShell
       self
     end
 
+    def shared_settings
+      %i[env debug]
+    end
+
+    def settings
+      @options.select { shared_settings.include?(_1.to_sym) }.transform_keys { :"_#{_1}" }
+    end
+
     def method_missing(method_name, *args, &block)
       if method_name.start_with?(/[^A-Za-z0-9]/)
         handle_chain(method_name, args.first)
@@ -32,7 +41,13 @@ module RubyShell
     end
 
     def exec_commands
-      RubyShell::TerminalExecutor.capture(to_shell, @options)
+      result = RubyShell::Debugger.run_wrapper(self, debug: @options[:debug]) do
+        RubyShell::TerminalExecutor.capture(to_shell, settings)
+      end
+
+      result = RubyShell::Parser.parse(@options[:parse], result) if @options[:parse]
+
+      result
     end
 
     alias exec exec_commands

data/lib/rubyshell/command.rb

@@ -16,7 +16,13 @@ module RubyShell
     end
 
     def exec_command
-      RubyShell::TerminalExecutor.capture(to_shell, @options)
+      result = RubyShell::Debugger.run_wrapper(self, debug: @options[:_debug]) do
+        RubyShell::TerminalExecutor.capture(to_shell, @options)
+      end
+
+      result = RubyShell::Parser.parse(@options[:_parse], result) if @options[:_parse]
+
+      result
     end
 
     alias exec exec_command

data/lib/rubyshell/debugger.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RubyShell
+  module Debugger
+    class << self
+      def run_wrapper(command, debug: nil)
+        if debug || RubyShell.debug?
+
+          time_one = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          result = yield
+
+          time_two = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          RubyShell.log(<<~TEXT
+            \nExecuted: #{command.to_shell.chomp}
+              Duration: #{format("%.6f", time_two - time_one)}s
+              Pid: #{result.metadata[:exit_status].pid}
+              Exit code: #{result.metadata[:exit_status].to_i}
+              Stdout: #{result.to_s.inspect}
+          TEXT
+                       )
+
+          result
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/rubyshell/env_proxy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyShell
+  module EnvProxy
+    class << self
+      def env
+        @env ||= {}
+      end
+
+      def to_h
+        env
+      end
+
+      def []=(key, value)
+        env[key.to_s] = value
+      end
+
+      def [](key)
+        env[key.to_s]
+      end
+
+      def set(hash)
+        @env = hash&.transform_keys(&:to_s) || {}
+      end
+    end
+  end
+end

data/lib/rubyshell/executor.rb

@@ -6,12 +6,18 @@ module RubyShell
 
     include RubyShell::OverwritedCommands
 
-    def chain(&block)
-      RubyShell::ChainContext.class_eval(&block).exec_commands
+    def chain(options = {}, &block)
+      RubyShell::ChainContext.new(options).instance_exec(&block).exec_commands
     end
 
-    def method_missing(method_name, *args)
-      command = RubyShell::Command.new(method_name.to_s.gsub(/!$/, ""), *args)
+    def parallel(options = {}, &block)
+      RubyShell.debug(options[:debug]) do
+        RubyShell::ParallelExecutor.new(options)._evaluate(&block)._run
+      end
+    end
+
+    def method_missing(method_name, *args, **kwargs)
+      command = RubyShell::Command.new(method_name.to_s.gsub(/!$/, ""), *args, **kwargs)
 
       if method_name.to_s.match?(/!$/)
         command

data/lib/rubyshell/parallel_executor.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RubyShell
+  class ParallelExecutor
+    def initialize(options = {})
+      @commands = []
+      @options = options
+
+      @queue = Queue.new
+    end
+
+    def shared_settings
+      %i[env debug]
+    end
+
+    def settings
+      @options.select { shared_settings.include?(_1.to_sym) }.transform_keys { :"_#{_1}" }
+    end
+
+    def _evaluate(&block)
+      instance_exec(&block)
+
+      self
+    end
+
+    def _run
+      @commands.each do |command|
+        Thread.new do
+          @queue << begin
+            command.exec
+          rescue StandardError => e
+            e
+          end
+        end
+      end
+
+      Enumerator.new do |y|
+        @commands.size.times { y << @queue.pop }
+      end
+    end
+
+    def chain(options = {}, &block)
+      @commands << RubyShell::ChainContext.new(settings.merge(options)).instance_exec(&block)
+    end
+
+    def sh(command, *args)
+      method_missing(command, *args)
+    end
+
+    def method_missing(method_name, *args, **kwargs)
+      command = RubyShell::Command.new(method_name.to_s.gsub(/!$/, ""), *args, **settings, **kwargs)
+
+      @commands << command
+    end
+
+    def respond_to_missing?(_name, _include_private)
+      false
+    end
+  end
+end

data/lib/rubyshell/parser.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RubyShell
+  class Parser
+    class ParserNotFound < StandardError
+    end
+
+    def self.parse(parser_key, value)
+      parser_class = locate_parser(parser_key)
+
+      parser_class.parse(value)
+    end
+
+    def self.locate_parser(parser_key)
+      Object.const_get("RubyShell::Parsers::#{parser_key.to_s.split("_").map(&:capitalize).join}")
+    rescue NameError
+      raise ParserNotFound
+    end
+  end
+end

data/lib/rubyshell/parsers/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RubyShell
+  module Parsers
+    class Base
+      def self.parse(_value)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/rubyshell/parsers/csv.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module RubyShell
+  module Parsers
+    class Csv < Base
+      def self.parse(value)
+        CSV.parse(value)
+      end
+    end
+  end
+end

data/lib/rubyshell/parsers/json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyShell
+  module Parsers
+    class Json < Base
+      def self.parse(value)
+        JSON.parse(value, symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/rubyshell/parsers/yaml.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RubyShell
+  module Parsers
+    class Yaml < Base
+      def self.parse(value)
+        YAML.safe_load(value, permitted_classes: [Symbol])
+      end
+    end
+  end
+end

data/lib/rubyshell/results/string_result.rb

@@ -3,6 +3,14 @@
 module RubyShell
   module Results
     class StringResult < String
+      def initialize(value, **kwargs)
+        @metadata = kwargs.delete(:metadata)
+
+        super
+      end
+
+      attr_reader :metadata
+
       def inspect
         if $stdin.isatty
           to_s

data/lib/rubyshell/terminal_executor.rb

@@ -13,7 +13,9 @@ module RubyShell
                       options[:_stdin]
                     end
 
-      Open3.popen3(command) do |stdin, stdout, stderr, w_thread|
+      env_hash = RubyShell.env.to_h.merge(options[:_env]&.transform_keys(&:to_s) || {})
+
+      Open3.popen3(env_hash, command) do |stdin, stdout, stderr, w_thread|
         stdin.write(stdin_value) if stdin_value
 
         stdin.close
@@ -64,7 +66,13 @@ module RubyShell
           )
         end
 
-        RubyShell::Results::StringResult.new(output.chomp)
+        RubyShell::Results::StringResult.new(
+          output.chomp,
+          metadata: {
+            command: command,
+            exit_status: status
+          }
+        )
       end
     rescue StandardError => e
       raise e if e.is_a?(RubyShell::CommandError)

data/lib/rubyshell/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyShell
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

data/lib/rubyshell.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "logger"
+
 require_relative "rubyshell/version"
 require_relative "rubyshell/command"
 require_relative "rubyshell/chainer"
@@ -10,15 +12,70 @@ require_relative "rubyshell/error"
 require_relative "rubyshell/results/string_result"
 require_relative "rubyshell/terminal_executor"
 require_relative "rubyshell/sanitizer"
+require_relative "rubyshell/parser"
+require_relative "rubyshell/parsers/base"
+require_relative "rubyshell/debugger"
+require_relative "rubyshell/env_proxy"
+require_relative "rubyshell/parallel_executor"
+
+module RubyShell
+  class << self
+    def debug=(value)
+      @debug_mode = !!value
+    end
+
+    def debug(value = true) # rubocop:disable Style/OptionalBooleanParameter
+      previous_value = @debug_mode
+
+      @debug_mode = value
+
+      result = yield
+
+      @debug_mode = previous_value
+
+      result
+    end
+
+    def debug?
+      @debug_mode == true
+    end
+
+    attr_writer :logger
+
+    def logger
+      @logger ||= Logger.new($stdout)
+    end
+
+    def log_level=(level)
+      @log_level = level.to_s
+    end
+
+    def log(text)
+      logger.send(@log_level || :info, text)
+    end
+
+    def env
+      RubyShell::EnvProxy
+    end
+
+    def config(kwargs)
+      env.set(kwargs[:env]) if kwargs[:env]
+    end
+  end
+end
 
 module Kernel
-  def sh(command = nil, *args, &block)
+  def sh(command = nil, *args, **kwargs, &block)
     if command
-      RubyShell::Executor.send(command, *args)
+      RubyShell::Executor.send(command, *args, **kwargs)
     elsif block.nil?
       RubyShell::Executor
     else
-      RubyShell::Executor.class_eval(&block)
+      RubyShell.config(kwargs)
+
+      RubyShell.debug(kwargs[:debug]) do
+        RubyShell::Executor.class_eval(&block)
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubyshell
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - albertalef
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-23 00:00:00.000000000 Z
+date: 2026-02-06 00:00:00.000000000 Z
 dependencies: []
 description: A rubist way to run shell commands
 email:
@@ -28,9 +28,17 @@ files:
 - lib/rubyshell/chain_context.rb
 - lib/rubyshell/chainer.rb
 - lib/rubyshell/command.rb
+- lib/rubyshell/debugger.rb
+- lib/rubyshell/env_proxy.rb
 - lib/rubyshell/error.rb
 - lib/rubyshell/executor.rb
 - lib/rubyshell/overwrited_commands.rb
+- lib/rubyshell/parallel_executor.rb
+- lib/rubyshell/parser.rb
+- lib/rubyshell/parsers/base.rb
+- lib/rubyshell/parsers/csv.rb
+- lib/rubyshell/parsers/json.rb
+- lib/rubyshell/parsers/yaml.rb
 - lib/rubyshell/results/string_result.rb
 - lib/rubyshell/sanitizer.rb
 - lib/rubyshell/terminal_executor.rb