AA(1) General Commands Manual AA(1)

aa — Manipulate Apple Archives

aa command [options]

aa creates and manipulates Apple Archives

archive           Archive the contents of the target directory
append            Archive the contents of the target directory, append to an existing archive file
extract           Extract the contents of an archive to the target directory
list              List the contents of an archive
convert           Convert an archive into another archive
manifest          Alias for 'archive -manifest'
verify            Compare the contents of the target directory with a manifest
check-and-fix     Verify and fix the contents of the target directory using an error correcting manifest

Increase verbosity. Default is silent operation.
Print usage and exit.
-dir
Target directory for archive/extract. Default is the current directory.
-input_file
Input file. Default is stdin.
-output_file
Output file. Default is stdout.
-subdir
Path to archive under dir. subdir will be included in the archived paths, and extracted. Default is empty.
-dir_and_subdir
Set both dir to `dirname dir_and_subdir` and subdir to `basename dir_and_subdir`.
Do not cross volume boundaries when archiving.
Generate destination path automatically based on source path. For example 'aa archive -d foo -p' becomes 'aa archive -d foo -o foo.aar'.
-algorithm
Compression algorithm used when creating archives. One of lzfse, lzma, lz4, zlib, raw. Default is lzfse.
-block_size
Block size used when compressing archives, a number with optional b, k, m, g suffix (bytes are assumed if no suffix is specified). Default is 4m for archive and 1m for the other commands.
-worker_threads
Number of worker threads compressing/decompressing data. Default is the number of physical CPU on the running machine.
-writer_threads
Number of writer threads extracting archive content. Default is to match worker_threads.
-(-no-enable-dedup)
If set, and SLC fields (the SLC field identifies a cluster of regular files with identical content) are present in the archive, files with same data will be extracted as clones.

Note that to create such an archive, you have to manually add the SLC field, for example `aa archive -o archive.aa -include-field SLC ...`. In this case, aa marks files with identical content as a cluster and shows a summary at the end.

There is no way to deduplicate the data in the archive (by storing the data only once) from the command line. To achieve this, use the API and pass the `AA_FLAG_ARCHIVE_DEDUPLICATE_DAT` flag.

-(-no-enable-holes)
If set, and the filesystem supports it, detect and create holes in files to store 0-filled segments
-(-no-ignore-eperm)
If set, ignore EPERM (operation not permitted) errors when setting files attributes
Alias for the following options:
-exclude-field dat
-include-field sh2,siz,idx,idz
-a lzfse -b 1m
-input_manifest_file
Manifest matching the input archive. Can be used in conjonction with the entry selection options to accelerate processing
-output_manifest_file
Receives a manifest of the output archive
-format
Output format for the list command, one of text, json. Default is text

-include-path and -include-path-list options are applied first to select an initial set of entries, then -exclude-path, -exclude-path-list, -exclude-name, -exclude-regex are applied to remove entries from this set.

If no -include-path or -include-path-list option is given, all entries are included in the initial set. If a directory is included/excluded, the entire sub-tree is included/excluded.

-path
Include entry paths having path as a prefix. This option can be given multiple times.
-path
Exclude entry paths having path as a prefix. This option can be given multiple times.
-path_list_file
File containing a list of paths to include, one entry per line. This option can be given multiple times.
-path_list_file
File containing a list of paths to exclude, one entry per line. This option can be given multiple times.
-expr
Include entry paths matching regular expression expr, see re_format(7). This option can be given multiple times.
-expr
Exclude entry paths matching regular expression expr, see re_format(7). This option can be given multiple times.
-name
Exclude entry paths where a single component of the path matches exactly name. This option can be given multiple times.
-<type_spec>
Include only entries matching the given types. <type_spec> is a word containing one or more of the entry type characters listed below.
-<type_spec>
Include only entries not matching the given types. <type_spec> is a word containing one or more of the entry type characters listed below.
-<field_spec>
Add the given fields to the set of field keys. This option can be given multiple times. <field_spec> is a comma separated list of entry field keys listed below.
-<field_spec>
Remove the given fields from the set of field keys. This option can be given multiple times. <field_spec> is a comma separated list of entry field keys listed below.

When archiving, encryption is selected by one of the -password..., -key..., or -recipient-pub options.

The archive will be signed if a private key is specified with -sign-priv.

With the currently available profiles, public/private keys are on the Elliptic Curve P-256, and symmetric keys are 256-bit long.

Use Keychain to load/store symmetric keys and passwords
-file
File containing encryption password. When encrypting, and if -password-gen is passed, receives the generated password. Can be - to print the password to standard output.
-password
Password.
When encrypting, generate a new random password. It is recommended to always use this option, in conjonction with -keychain to store the password in the Keychain, or -password to store the password in a file or print it.
-file
File containing encryption symmetric key. When encrypting, and if -key-gen is passed, receives the generated key.
-key
Symmetric key, either "hex:<64 hex digits>" or "base64:<32 bytes encoded using base64>".
When encrypting, generate a new random symmetric key.
-file
Recipient public key for encryption. The corresponding private key is required to decrypt the archive.
-file
Recipient private key for decryption. The archive must have been encrypted against the corresponding public key.
-file
Signing public key for decryption. The archive must have been signed with the corresponding private key.
-file
Signing private key for encryption. The corresponding public key is required to decrypt and authenticate the archive.

b block special
c character special
d directory
f regular file
l symbolic link
m metadata
p fifo
s socket

typ entry type
pat path
lnk link path
dev device id
uid user id
gid group id
mod access permissions
flg flags
mtm modification time
ctm creation time
btm backup time
xat extended attributes
acl access control list
cks CRC32 checksum
sh1 SHA1 digest
sh2 SHA2-256 digest
dat file contents
siz file size
duz disk usage
idx entry index in main archive
yec file data error correcting codes
yaf Apple Archive fields (in metadata entry)
all alias for all fields (exclude only)
attr alias for uid,gid,mod,flg,mtm,btm,ctm

Archive the contents of directory foo into archive foo.aar, using LZMA compression with 8 MB blocks

 aa archive -d foo -o foo.aar -a lzma -b 8m

Extract the contents of foo.aar in directory dst

 aa extract -d dst -i foo.aar

Create a manifest of the contents of directory foo into foo.manifest, using LZFSE compression with 1 MB blocks

 aa manifest -d foo -o foo.manifest -a lzfse -b 1m

Verify the contents of dst match the manifest foo.manifest

 aa verify -i foo.manifest -d dst -v

Print all entry paths in foo.manifest

 aa list -i foo.manifest

Print all entry paths, uid, gid for regular files in foo.manifest

 aa list -v -i foo.manifest -include-type f -exclude-field all -include-field uid,gid,pat

Create a manifest of the contents of archive foo.aar in foo.manifest

 aa convert -manifest -v -i foo.aar -o foo.manifest

Extract a subset of entries matching prefix Applications/Mail.app from archive foo.aar in directory dst

 aa extract -i foo.aar -include-path Applications/Mail.app -d dst

Archive and encrypt directory foo to archive foo.aea, generating a random password and storing it in the Keychain

 aa archive -d foo -o foo.aea -keychain -password-gen

Decrypt and extract archive foo.aea to directory dst, obtaining the password from the Keychain (requires local authentication)

 aa extract -o foo.aea -d dst -keychain

Archive directory foo to archive foo.aar

 aa archive -p -d foo

Extract archive foo.aar to directory foo

 aa extract -p -i foo.aar

March 9, 2020 macOS