borgmatic/docs/how-to/run-arbitrary-borg-commands.md

---
title: How to run arbitrary Borg commands
eleventyNavigation:
  key: 🔧 Run arbitrary Borg commands
  parent: How-to guides
  order: 11
---
## Running Borg with borgmatic

Borg has several commands and options that borgmatic does not currently
support. Sometimes though, as a borgmatic user, you may find yourself wanting
to take advantage of these off-the-beaten-path Borg features. You could of
course drop down to running Borg directly. But then you'd give up all the
niceties of your borgmatic configuration. You could file a [borgmatic
ticket](https://torsion.org/borgmatic/#issues) or even a [pull
request](https://torsion.org/borgmatic/#contributing) to add the feature. But
what if you need it *now*?

That's where borgmatic's support for running "arbitrary" Borg commands comes
in. Running these Borg commands with borgmatic can take advantage of the
following, all based on your borgmatic configuration files or command-line
arguments:

 * configured repositories, running your Borg command once for each one
 * local and remote Borg binary paths
 * SSH settings and Borg environment variables
 * lock wait settings
 * verbosity


### borg action

<span class="minilink minilink-addedin">New in version 1.5.15</span> The way
you run Borg with borgmatic is via the `borg` action. Here's a simple example:

```bash
borgmatic borg break-lock '$REPOSITORY'
```

This runs Borg's `break-lock` command once on each configured borgmatic
repository, passing the repository path in as an environment variable named
`REPOSITORY`. The single quotes are necessary in order to pass in a literal
`$REPOSITORY` string instead of trying to resolve it from borgmatic's shell
where it's not yet set.

<span class="minilink minilink-addedin">Prior to version 1.8.0</span>borgmatic
provided the repository name implicitly, attempting to inject it into your
Borg arguments in the right place (which didn't always work). So your
command-line in these older versions looked more like:

```bash
borgmatic borg break-lock
```

You can also specify Borg options for relevant commands. In borgmatic 1.8.0+,
that looks like:

```bash
borgmatic borg rlist --short '$REPOSITORY'
```

This runs Borg's `rlist` command once on each configured borgmatic repository.
However, the native `borgmatic rlist` action should be preferred for most uses.

What if you only want to run Borg on a single configured borgmatic repository
when you've got several configured? Not a problem. The `--repository` argument
lets you specify the repository to use, either by its path or its label:

```bash
borgmatic borg --repository repo.borg break-lock '$REPOSITORY'
```

### Specifying an archive

For borg commands that expect an archive name, you have a few approaches.
Here's one:

```bash
borgmatic borg --archive latest list '$REPOSITORY::$ARCHIVE'
```

Or if you don't need borgmatic to resolve an archive name like `latest`, you
can just do:

```bash
borgmatic borg list '$REPOSITORY::your-actual-archive-name'
```

<span class="minilink minilink-addedin">Prior to version 1.8.0</span>borgmatic
provided the archive name implicitly along with the repository, attempting to
inject it into your Borg arguments in the right place (which didn't always
work). So your command-line in these older versions of borgmatic looked more
like:

```bash
borgmatic borg --archive latest list
```

<span class="minilink minilink-addedin">With Borg version 2.x</span> Either of
these will list an archive:

```bash
borgmatic borg --archive latest list --repo '$REPOSITORY' '$ARCHIVE'
```

```bash
borgmatic borg list --repo '$REPOSITORY' your-actual-archive-name
```

### Limitations

borgmatic's `borg` action is not without limitations:

 * The Borg command you want to run (`create`, `list`, etc.) *must* come first
   after the `borg` action (and any borgmatic-specific arguments). If you have
   other Borg options to specify, provide them after. For instance,
   `borgmatic borg list --progress ...` will work, but
   `borgmatic borg --progress list ...` will not.
 * Do not specify any global borgmatic arguments to the right of the `borg`
   action. (They will be passed to Borg instead of borgmatic.) If you have
   global borgmatic arguments, specify them *before* the `borg` action.
 * Unlike other borgmatic actions, you cannot combine the `borg` action with
   other borgmatic actions. This is to prevent ambiguity in commands like
   `borgmatic borg list`, in which `list` is both a valid Borg command and a
   borgmatic action. In this case, only the Borg command is run.
 * Unlike normal borgmatic actions that support JSON, the `borg` action will
   not disable certain borgmatic logs to avoid interfering with JSON output.
 * <span class="minilink minilink-addedin">Prior to version 1.8.0</span>
   borgmatic implicitly supplied the repository/archive name to Borg for you
   (based on your borgmatic configuration or the
   `borgmatic borg --repository`/`--archive` arguments)—which meant you couldn't
   specify the repository/archive directly in the Borg command. Also, in these
   older versions of borgmatic, the `borg` action didn't work for any Borg
   commands like `borg serve` that do not accept a repository/archive name.
 * <span class="minilink minilink-addedin">Prior to version 1.7.13</span> Unlike
   other borgmatic actions, the `borg` action captured (and logged) all output,
   so interactive prompts and flags like `--progress` dit not work as expected.
   In new versions, borgmatic runs the `borg` action without capturing output,
   so interactive prompts work.

In general, this `borgmatic borg` feature should be considered an escape
valve—a feature of second resort. In the long run, it's preferable to wrap
Borg commands with borgmatic actions that can support them fully.