borg2: how does one specify the archive to borg extract?

[tve]

OK, I'm sure this is a case of too dense to grok the manual, but I don't understand how I'm supposed to specify the archive from which to extract files (using borg2's extract, version 2.0.0 HEAD).

Things I tried:

borg extract --stdout daily-full /tvoneicken/.Xresources                           
Command error: ['daily-full'] needed to match precisely one archive, but matched 4. 

borg extract --stdout --last 1 daily-full /tvoneicken/.Xresources
usage: borg [-V] [--cockpit] [-h] [--critical] [--error] [--warning] [--info] [--debug]
            [--debug-topic TOPIC] [-p] [--iec] [--log-json] [--lock-wait SECONDS]
            [--show-version] [--show-rc] [--umask M] [--remote-path PATH]
            [--upload-ratelimit RATE] [--upload-buffer UPLOAD_BUFFER] [--debug-profile FILE]
            [--rsh RSH] [--socket [PATH]] [-r REPO]
            <command> ...
borg: error: unrecognized arguments: --last

borg extract --stdout -a tekke daily-full /tvoneicken/.Xresources
usage: borg [-V] [--cockpit] [-h] [--critical] [--error] [--warning] [--info] [--debug]
            [--debug-topic TOPIC] [-p] [--iec] [--log-json] [--lock-wait SECONDS]
            [--show-version] [--show-rc] [--umask M] [--remote-path PATH]
            [--upload-ratelimit RATE] [--upload-buffer UPLOAD_BUFFER] [--debug-profile FILE]
            [--rsh RSH] [--socket [PATH]] [-r REPO]
            <command> ...
borg: error: unrecognized arguments: -a

> borg repo-list --last 1
tekke         daily-full 2026-03-01 02:33:33  2529894a040ad2063d88380d203032ee105a4055aa6c2cbb6
acbcdf9e6a4e9cd
> borg extract --stdout 2529894a040ad2063d88380d203032ee105a4055aa6c2cbb6acbcdf9e6a4e9cd /tvoneicken/.Xresources
Command error: ['2529894a040ad2063d88380d203032ee105a4055aa6c2cbb6acbcdf9e6a4e9cd'] needed to match precisely one archive, but matched 0.

[infectormp]

related to #9248 #9053

[tve]

thanks! intuitive...

[ThomasWaldmann]

it's not very intuitive. but as the archive parameter defaults to the name, that is a safe way to differentiate archive ids from names. it's also use by the auto completion, which will complete archive ids, if "aid:" is already there.

[tve]

as the archive parameter defaults to the name, that is a safe way to differentiate archive ids from names

Sorry, I don't understand what you mean.

IMHO a place where the NAME options should be documented is in the [help > General > Repository Locations / Archive Names]

I would have found it helpful if the documentation for borg extract either used ARCHIVE instead of NAME and/or the examples included an archive selection. From a practical point of view, the only realistic option for the archive is the ID. Using the series name only works in the special case where the series has only a single archive.

I would find it helpful if extract (and every other command that takes an archive parameter) accepted the -a option as well. As it is one has to run a borg repo-list to get the archive ID, which is somewhat of a bummer.