Built In Commands

A few commands are provided out of the box. To use them in a project, import them:

# E.g., commands.py at the top level of your project
from runcommands.commands import local, remote
runcommand local --help

Or call them from your own commands:

from runcommands import command
from runcommands.commands import local

def test():
    local('python -m unittest discover .')

Copy files locally

copy_file.implementation(destination, follow_symlinks=True, template: arg<BoolOrStr>() = False, context=None)

Copy source file to destination.

The destination may be a file path or a directory. When it’s a directory, the source file will be copied into the directory using the file’s base name.

When the source file is a template, context will be used as the template context. The supported template types are ‘format’ and ‘string’. The former uses str.format_map() and the latter uses string.Template().


shutil.copy() from the standard library is used to do the copy operation.

Sync files with remote

sync.implementation(destination, host, user=None, sudo=False, run_as=None, options=('-rltvz', '--no-perms', '--no-group'), excludes=(), exclude_from=None, delete=False, dry_run=False, mode='u=rwX, g=rwX, o=', quiet=True, pull=False, stdout: arg<StreamOptions>() = None, stderr: arg<StreamOptions>() = None, echo=False, raise_on_error=True) → runcommands.result.Result

Sync files using rsync.

By default, a local source is pushed to a remote destination. To pull from a remote source to a local destination instead, pass pull=True.

Git version

git_version.implementation(show: Print version to stdout = False)

Get tag associated with HEAD; fall back to SHA1.

If HEAD is tagged, return the tag name; otherwise fall back to HEAD’s short SHA1 hash.


Only annotated tags are considered.


When no minimum hash length is specified, the minimum length is determined by git rev-parse based on git’s core.abbrev config variable.


The output isn’t shown by default. To show it, pass the --show flag.

Run local commands

local.implementation(background=False, cd=None, environ: arg<dict>() = None, replace_env=False, paths=(), shell: arg<bool>() = None, stdout: arg<StreamOptions>() = None, stderr: arg<StreamOptions>() = None, echo=False, raise_on_error=True, dry_run=False) → runcommands.result.Result

Run a local command via subprocess.run().

  • args (list|str) – A list of args or a shell command.
  • background (bool) – Run process in background? If this is set, the command will be run in the background via subprocess.Popen then this function will immediately return. The call site will need to wait on the returned Popen object using Popen.wait() or by some other means (perhaps by starting another long-running process in the foreground).
  • cd (str) – Working directory to change to first.
  • environ (dict) – Additional environment variables to pass to the subprocess.
  • replace_env (bool) – If set, only pass env variables from environ to the subprocess.
  • paths (list) – A list of additional paths.
  • shell (bool) – Run as a shell command? The default is to run in shell mode if args is a string. This flag can be used to force a list of args to be run as a shell command too.
  • stdout (StreamOptions) – What to do with stdout (capture, hide, or show).
  • stderr (StreamOptions) – Same as stdout.
  • echo (bool) – Whether to echo the command before running it.
  • raise_on_error (bool) – Whether to raise an exception when the subprocess returns a non-zero exit code.
  • dry_run (bool) – If set, print command instead of running it.

When the command is run in the foreground. - subprocess.Popen: When the command is run in the


Return type:

  • Result


Result – When the subprocess returns a non-zero exit code (and raise_on_error is set).

Run remote commands

remote.implementation(host, user=None, port=None, sudo=False, run_as=None, shell='/bin/sh', cd=None, environ: arg<None>() = None, paths=(), stdout: arg<StreamOptions>() = None, stderr: arg<StreamOptions>() = None, echo=False, raise_on_error=True, dry_run=False) → runcommands.result.Result

Run a remote command via SSH.

Runs a remote shell command using ssh in a subprocess like so:

ssh -q [-t] [<user>@]<host> [sudo [-u <run_as>] -H] /bin/sh -c '
    [cd <cd> &&]
    [export XYZ="xyz" &&]
    [export PATH="<path>" &&]
  • cmd (list|str) – The command to run. If this is a list, it will be flattened into a string.
  • host (str) – Remote host to SSH into.
  • user (str) – Remote user to log in as (defaults to current local user).
  • port (int) – SSH port on remote host.
  • sudo (bool) – Run the remote command as root using sudo.
  • run_as (str) – Run the remote command as a different user using sudo -u <run_as>.
  • shell (str) – The remote user’s default shell will be used to run the remote command unless this is set to a different shell.
  • cd (str) – Where to run the command on the remote host.
  • environ (dict) – Extra environment variables to set on the remote host.
  • paths (list) – Additional paths to prepend to the remote $PATH.
  • stdout – See runcommands.commands.local.
  • stderr – See runcommands.commands.local.
  • echo – See runcommands.commands.local.
  • raise_on_error – See runcommands.commands.local.
  • dry_run – See runcommands.commands.local.