txt: ## run.md
  run
  
  Combined from primary sources listed below.
  
  # [In Thread](#___top "go to top of document")[§](#(Thread)_method_run "direct link")
  
  See primary documentation
  [in context](/type/Thread#method_run)
  for **method run**.
  
  ```raku
  method run(Thread:D:)
  ```
  
  Runs the thread, and returns the invocant. It is an error to run a thread that has already been started.
  
  # [In Independent routines](#___top "go to top of document")[§](#(Independent_routines)_sub_run "direct link")
  
  See primary documentation
  [in context](/type/independent-routines#sub_run)
  for **sub run**.
  
  ```raku
  sub run(
      *@args ($, *@),
      :$in = '-',
      :$out = '-',
      :$err = '-',
      Bool :$bin = False,
      Bool :$chomp = True,
      Bool :$merge = False,
      Str:D :$enc = 'UTF-8',
      Str:D :$nl = "\n",
      :$cwd = $*CWD,
      Hash() :$env = %*ENV,
      :$arg0,
      :$win-verbatim-args = False
  --> Proc:D)
  
  ```
  
  Runs an external command *without involving a shell* and returns a [`Proc`](/type/Proc) object. By default, the external command will print to standard output and error, and read from standard input.
  
  ```raku
  run 'touch', '--', '*.txt'; # Create a file named “*.txt”
  
  run <rm -- *.txt>; # Another way to use run, using word quoting for the
                     # arguments
  ```
  
  If you want to pass some variables you can still use `< >`, but try to avoid using `« »` as it will do word splitting if you forget to quote variables:
  
  ```raku
  my $file = ‘--my arbitrary filename’;
  run ‘touch’, ‘--’, $file;  # RIGHT
  run <touch -->, $file;     # RIGHT
  
  run «touch -- "$file"»;    # RIGHT but WRONG if you forget quotes
  run «touch -- $file»;      # WRONG; touches ‘--my’, ‘arbitrary’ and ‘filename’
  run ‘touch’, $file;        # WRONG; error from `touch`
  run «touch "$file"»;       # WRONG; error from `touch`
  
  ```
  
  Note that `--` is required for many programs to disambiguate between command-line arguments and [filenames that begin with hyphens](https://mywiki.wooledge.org/BashPitfalls#Filenames_with_leading_dashes).
  
  A sunk [`Proc`](/type/Proc) object for a process that [exited](/routine/exitcode) unsuccessfully will throw an [`Exception`](/type/Exception). If you wish to ignore the exceptions, and return a [`Proc`](/type/Proc) you can introspect, use [run](/routine/run) in non-sink context:
  
  ```raku
  run 'false';     # SUNK! Will throw an Exception
  run('false').so; # OK. Evaluates Proc in Bool context; no sinking. Ignore returned Proc
  my $a = run('false'); # Can call methods on the Proc in $a.
  ```
  
  If you want to capture standard output or error instead of having it printed directly you can use the `:out` or `:err` arguments, which will make them available using their respective methods: [`Proc.out`](/type/Proc) and [`Proc.err`](/type/Proc).
  
  ```raku
  my $proc = run 'echo', 'Raku is Great!', :out, :err;
  $proc.out.slurp(:close).say; # OUTPUT: «Raku is Great!␤»
  $proc.err.slurp(:close).say; # OUTPUT: «␤»
  ```
  
  You can use these arguments to redirect them to a filehandle, thus creating a kind of *pipe*:
  
  ```raku
  my $ls-alt-handle = open :w, '/tmp/cur-dir-ls-alt.txt';
  my $proc = run "ls", "-alt", :out($ls-alt-handle);
  # (The file will contain the output of the ls -alt command)
  ```
  
  These argument are quite flexible and admit, for instance, handles to redirect them. See [`Proc`](/type/Proc) and [`Proc::Async`](/type/Proc/Async) for more details.
  
  See also [`new`](/type/Proc#routine_new) and [`spawn`](/type/Proc#method_spawn) for more examples and explanation of all arguments.
  