ThomasWaldmann · Nov 1, 2026 · Oct 10, 2026 · Oct 12, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/docs/man/borg-known-repos.1 b/docs/man/borg-known-repos.1
@@ -0,0 +1,97 @@
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.4 manpage writer.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "borg-known-repos" "1" "2026-11-01" "" "borg backup tool"
+.SH Name
+borg-known-repos \- List repositories Borg has local state for (security info and/or cache).
+.SH SYNOPSIS
+.sp
+borg [common options] known\-repos [options]
+.SH DESCRIPTION
+.sp
+Lists the repositories this local Borg installation currently has state for \-
+security info (key type, last known location), a local repository cache, and/or key
+files \- without accessing any repository itself (\-r/\-\-repo has no effect). \(dqLayout\(dq
+is which state was found in (not the on\-disk repository format, see \(dqborg repo\-info\(dq
+for that) \- a security\-only repo gets \(dqunknown\(dq when $BORG_SECURITY_DIR makes the
+borg2 and legacy security roots coincide.
+.sp
+\(dqLast written\(dq is a best\-effort last\-used proxy, not an exact timestamp and not a
+staleness check on its own. It is the newest mtime found among the repository\(aqs
+security info file (which records the repository\(aqs last known location) and, if a
+local cache exists, any regular file in that cache \- whichever of the two is more
+recent.
+A mismatch between a legacy repo\(aqs known location and its cache\(aqs last location is
+flagged. A key file\(aqs presence does not by itself mean the repository is still
+openable. Use \-\-json for a machine\-readable version.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS options
+.INDENT 0.0
+.TP
+.B  \-\-json
+format output as JSON
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+$ borg known\-repos
+Repository ID                                                    Layout Cache Security           Key files Last written        Location
+401606173d54eab22cd98de67278d093e3bae7b187da3af8c6430f18fa1112bb borg2  180 B aes256\-ocb, sha256 \-         2026\-10\-12T17:15:19 /path/to/repo
+
+$ borg known\-repos \-\-json
+{
+    \(dqrepositories\(dq: [
+        {
+            \(dqcache_size\(dq: 180,
+            \(dqhas_cache\(dq: true,
+            \(dqhas_security_info\(dq: true,
+            \(dqid\(dq: \(dq401606173d54eab22cd98de67278d093e3bae7b187da3af8c6430f18fa1112bb\(dq,
+            \(dqkey_file_count\(dq: 0,
+            \(dqkey_type\(dq: \(dqaes256\-ocb, sha256\(dq,
+            \(dqlast_written\(dq: \(dq2026\-10\-12T17:15:19.785785+09:00\(dq,
+            \(dqlayout\(dq: \(dqborg2\(dq,
+            \(dqlocation\(dq: \(dq/path/to/repo\(dq,
+            \(dqlocation_mismatch\(dq: false
+        }
+    ]
+}
+.EE
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH Author
+The Borg Collective
+.\" End of generated man page.
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -44,6 +44,7 @@ Usage
    usage/repo-delete
    usage/serve
    usage/version
+   usage/known-repos
    usage/compact
    usage/lock
    usage/key

diff --git a/docs/usage/known-repos.rst b/docs/usage/known-repos.rst
@@ -0,0 +1,27 @@
+.. include:: known-repos.rst.inc
+
+Examples
+~~~~~~~~
+::
+
+    $ borg known-repos
+    Repository ID                                                    Layout Cache Security           Key files Last written        Location
+    401606173d54eab22cd98de67278d093e3bae7b187da3af8c6430f18fa1112bb borg2  180 B aes256-ocb, sha256 -         2026-10-12T17:15:19 /path/to/repo
+
+    $ borg known-repos --json
+    {
+        "repositories": [
+            {
+                "cache_size": 180,
+                "has_cache": true,
+                "has_security_info": true,
+                "id": "401606173d54eab22cd98de67278d093e3bae7b187da3af8c6430f18fa1112bb",
+                "key_file_count": 0,
+                "key_type": "aes256-ocb, sha256",
+                "last_written": "2026-10-12T17:15:19.785785+09:00",
+                "layout": "borg2",
+                "location": "/path/to/repo",
+                "location_mismatch": false
+            }
+        ]
+    }
diff --git a/docs/usage/known-repos.rst.inc b/docs/usage/known-repos.rst.inc
@@ -0,0 +1,61 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_known-repos:
+
+borg known-repos
+----------------
+.. code-block:: none
+
+    borg [common options] known-repos [options]
+
+.. only:: html
+
+    .. class:: borg-options-table
+
+    +-------------------------------------------------------+------------+-----------------------+
+    | **options**                                                                                |
+    +-------------------------------------------------------+------------+-----------------------+
+    |                                                       | ``--json`` | format output as JSON |
+    +-------------------------------------------------------+------------+-----------------------+
+    | .. class:: borg-common-opt-ref                                                             |
+    |                                                                                            |
+    | :ref:`common_options`                                                                      |
+    +-------------------------------------------------------+------------+-----------------------+
+
+    .. raw:: html
+
+        <script type='text/javascript'>
+        $(document).ready(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+
+
+    options
+        --json     format output as JSON
+
+
+    :ref:`common_options`
+        |
+
+Description
+~~~~~~~~~~~
+
+Lists the repositories this local Borg installation currently has state for -
+security info (key type, last known location), a local repository cache, and/or key
+files - without accessing any repository itself (-r/--repo has no effect). "Layout"
+is which state was found in (not the on-disk repository format, see "borg repo-info"
+for that) - a security-only repo gets "unknown" when $BORG_SECURITY_DIR makes the
+borg2 and legacy security roots coincide.
+
+"Last written" is a best-effort last-used proxy, not an exact timestamp and not a
+staleness check on its own. It is the newest mtime found among the repository's
+security info file (which records the repository's last known location) and, if a
+local cache exists, any regular file in that cache - whichever of the two is more
+recent.
+A mismatch between a legacy repo's known location and its cache's last location is
+flagged. A key file's presence does not by itself mean the repository is still
+openable. Use --json for a machine-readable version.
diff --git a/src/borg/archiver/__init__.py b/src/borg/archiver/__init__.py
@@ -79,6 +79,7 @@
 from .help_cmd import HelpMixIn
 from .info_cmd import InfoMixIn
 from .key_cmds import KeysMixIn
+from .known_repos_cmd import KnownReposMixIn
 from .list_cmd import ListMixIn
 from .lock_cmds import LocksMixIn
 from .mount_cmds import MountMixIn
@@ -116,6 +117,7 @@ class Archiver(
     HelpMixIn,
     InfoMixIn,
     KeysMixIn,
+    KnownReposMixIn,
     ListMixIn,
     LocksMixIn,
     MountMixIn,
@@ -310,6 +312,7 @@ def build_parser(self):
         self.build_parser_help(subparsers, common_parser, mid_common_parser, parser)
         self.build_parser_info(subparsers, common_parser, mid_common_parser)
         self.build_parser_keys(subparsers, common_parser, mid_common_parser)
+        self.build_parser_known_repos(subparsers, common_parser, mid_common_parser)
         self.build_parser_list(subparsers, common_parser, mid_common_parser)
         self.build_parser_locks(subparsers, common_parser, mid_common_parser)
         self.build_parser_mount_umount(subparsers, common_parser, mid_common_parser)