run function

int? run(String commandLine, { bool runInShell = false, bool nothrow = false, bool privileged = false, String? workingDirectory, bool extensionSearch = true, })

Runs the given cli commandLine writing any output from both stdout and stderr to the console.

if the nothrow argument is false (the default) then a non-zero exit code will result in RunException been thrown. The RunException will contain the non-zero exit code.

As stderr is written to the console the associated error message will have been written to the console before the command exists.

if the nothrow argument is true then a non-zero exit code will NOT result in an exception. Instead the run method will return the exit code. Again any error message will have been written to the console before the command exists.

If you pass a workingDirectory the command will run in the given workingDirectory. If the workingDirectory is not specified then the command will be run in the current working directory.

Use the runInShell argument if you need your command to be spawned within a shell (e.g. bash). This may be necessary if you need to access a command builtin to the shell.

The privileged argument attempts to escalate the priviledge that the command is run at. If the script is already running in a priviledge environment this s witch will have no affect. Running a command with the privileged switch may cause the OS to prompt the user for a password.

For Linux passing the privileged argument will cause the command to be prefix vai the sudo command.

Current privileged is only supported under Linux.

DCli performs glob (wildcard) expansion on command arguments if it contains any one of *, [ or ? unless the argument is quoted. DCli uses the dart package Glob (https://pub.dev/packages/glob) to do the glob expansion.

The following command will have the argument containing the wild card *.dart expanded to the list of files, in the current directory, that match the pattern *.dart. If no files match the pattern then the pattern will be passed to the command unchanged:

run('ls *.dart');

If you add quotes around the wild card then it will not be expanded:

run('find . -name "*.dart"', workingDirectory: HOME);

Run the command and do not throw an exception if a non-zero exist code is returned.

int exitCode = run('ls *.dart', nothrow=true);

The run function is syncronous and a such will not return until the command completes.

The nothrow argument is EXPERIMENTAL

See:

• start
• startFromArgs for methods that allow you to process data rather than just outputing it to the cli.

Implementation

int? run(
  String commandLine, {
  bool runInShell = false,
  bool nothrow = false,
  bool privileged = false,
  String? workingDirectory,
  bool extensionSearch = true,
}) {
  workingDirectory ??= pwd;

  final runnable = RunnableProcess.fromCommandLine(
    commandLine,
    workingDirectory: workingDirectory,
  );

  return runnable
      .run(
        progress: Progress.print(),
        runInShell: runInShell,
        terminal: false,
        privileged: privileged,
        nothrow: nothrow,
        extensionSearch: extensionSearch,
      )
      .exitCode;
}