How to run arbitrary Borg commands

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 or even a pull request 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 Borg commands with borgmatic takes advantage of the following, all based on your borgmatic configuration files or command-line arguments:

borg action

The way you run Borg with borgmatic is via the borg action. Here's a simple example:

borgmatic borg break-lock

(No borg action in borgmatic? Time to upgrade!)

This runs Borg's break-lock command once on each configured borgmatic repository. Notice how the repository isn't present in the specified Borg options, as that part is provided by borgmatic.

You can also specify Borg options for relevant commands:

borgmatic borg list --progress

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

What if you only want to run Borg on a single configured borgmatic repository when you've got several configured? Not a problem.

borgmatic borg --repository repo.borg break-lock

And what about a single archive?

borgmatic borg --archive your-archive-name list


borgmatic's borg action is not without limitations:

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.

Improve this documentation

Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!