![]() |
Command line control |
Welcome to DROID |
DROID can be controlled via the command line. Command line control allows DROID to be scripted into batch processes or automated work-flows, or used interactively to quickly explore file type identifications.
To obtain a list of help for command line options, run: | droid -h |
To obtain the version of DROID, run: | droid -v |
droid “C:\Files\A Folder” "C:\Files\A File” |
This will output the results of identification as Comma Separated Values (CSV) directly to the console. This is equivalent to using the -a option - add resources for identification. However, you don't need to specify -a unless you want to be explicit.
droid -a “C:\Files\A Folder” "C:\Files\A File” |
If you want to process sub-folders and the files inside them, specify the -R option to recurse into sub-folders:
droid “C:\Files\A Folder” "C:\Files\A File” -R |
droid “C:\Files\A Folder” "C:\Files\A File” -R -o "C:\Results\identifications.csv" |
Note: if you specify "stdout" as the filename for the -o option, it will also write to the console. But it's easier to simply not specify the -o option.
droid “C:\Files\A Folder” "C:\Files\A File” -R -p "C:\Results\identifications.droid" |
If you don't want to see DROID log messages to the console, you can use quiet mode: -q:
droid “C:\Files\A Folder” "C:\Files\A File” -R -p "C:\Results\identifications.droid" -q |
If you want to keep exploring the results of identifying files, saving the results to a database is the most flexible, as you can run different queries on it.
droid “C:\Files\A Folder” "C:\Files\A File” -R -ff "file_size > 1000" "file_ext any txt pdf" |
droid “C:\Files\A Folder” "C:\Files\A File” -R -ff "file_size > 1000" "file_ext any txt pdf" -f "type none folder" |
The command above would only identify files whose file size was bigger than 1000 bytes, and whose file extensions are .txt or .pdf. Filtering files before they are identified (rather than afterwards) can speed up the process, particularly when processing inside archive files like zip, as DROID doesn't need to read the data inside the files.
There is another option to only process files with particular extensions, using the -Nx option:
droid “C:\Files\A Folder” "C:\Files\A File” -R -Nx txt pdf |
The -Nx option was provided in earlier versions of DROID, before the more flexible file filtering options above were added, but it's still available.
droid “C:\Files\A Folder” "C:\Files\A File” -R -f "puid any fmt/111 fmt/121 fmt/132 fmt/145" "format_count > 1" |
Note: Specifying this option if writing to a database with the -p option will have no effect, as the database requires all identifications made to be written out. This is because the database can be in an inconsistent state otherwise, if folders or archive files are filtered out, but the children in them are still present. You can still filter a database after it has been saved using these options, but not during the file identification process itself. See Filtering Exports for more details.
droid -k |
droid “C:\Files\A Folder” "C:\Files\A File” -R -Ns "C:\Signatures\binarysig.xml" -Nc "C:\Signatures\containersig.xml" |
droid “C:\Files\A Folder” "C:\Files\A File” -R -A -W |
You can also specify individual archive types you want to process using -At and -Wt, followed by the types you want to process. Any not specified will not be processed:
droid “C:\Files\A Folder” "C:\Files\A File” -R -At zip 7zip -Wt warc |
droid “C:\Files\A Folder” "C:\Files\A File” -R -Pr "maxBytesToScan=10000" "matchAllExtensions=true" |
If you have a common set of properties you want to apply each time, you can place them in a text file, and use the -Pf option to specify the property file to use:
droid “C:\Files\A Folder” "C:\Files\A File” -R -Pf "C:\Config\config.properties" |
Note: When specifying properties in a property file, each property must have the prefix "profile.". For example:
profile.maxBytesToScan=10000 |
profile.matchAllExtensions=true |
You can also combine the -Pr and -Pf options on the command line. In this case, properties specified on the command line directly will take precedence over those in the file, if the same property is specified in both.
A complete list of profile properties can be found in the profile property table.
This mode is retained in DROID for backwards compatibility, but it is now re-implemented to use standard identification code. The output will not be completely identical to the previous mode, but will be more accurate and in-line with all other identification modes. Differences include:
droid -Nr “C:\Files\A Folder” "C:\Files\A File” -R -Ns "C:\Signatures\binarysig.xml" -Nc "C:\Signatures\containersig.xml" |
In general, there is little reason to use this mode unless it is required for backwards compatibility with existing scripts. The standard identification mode writing to the console or file gives much greater control over the output and configuration.
droid “C:\Files\A Folder” "C:\Files\A File" -ri |
droid “C:\Files\A Folder” "C:\Files\A File" -qc |
droid “C:\Files\A Folder” "C:\Files\A File" -co FILE_PATH NAME METHOD PUID |
A list of all valid column headers can be found in the Column Name table
To work with previously saved profiles, we again use the -p option to specify where the profile files are to be loaded from. You can specify more than one profile when working with saved profiles.
droid -p "C:\Results\myprofile1.droid" "C:\Results\myprofile2.droid" -e "C:\Exports\myprofiles.csv" |
If you want to export directly to the console, not to a file, simply don't specify a file name after the -e or -E options:
droid -p "C:\Results\myprofile1.droid" "C:\Results\myprofile2.droid" -e |
A final option for export is to control whether a Byte Order Mark (BOM) is written at the beginning of the file. To write a BOM, use the -B option:
droid -p "C:\Results\myprofile1.droid" "C:\Results\myprofile2.droid" -e "C:\Exports\myprofiles.csv" -B |
droid -p "C:\Results\myprofile1.droid" "C:\Results\myprofile2.droid" -E "C:\Exports\myprofiles.csv" -F "file_size > 100000" "puid any fmt/110 fmt/111 fmt/112" |
To obtain a full list of the available filtering fields and operators, use the -k option, or see the Filtering Parameters Table
droid –p “C:\Results\result1.droid” –n “File count and sizes” –r “C:\Reports\result1Report.pdf” |
This command would load the profile from the "C:\Results\result1.droid" file, run the "File count and sizes" report, and save the results to a PDF file: " C:\Reports\result1Report.pdf":
To obtain a list of available reports on the command line, use the -l option, or see Available reports.
droid -l |
droid –p “C:\Results\result1.droid” –n “Comprehensive breakdown” -t "Planets XML" –r “C:\Reports\result1Report.xml” |
See output file formats for a list of report output formats.
Note: The "Comprehensive Breakdown" report has a special output type: "Planets XML" which writes out the results of identification in the Planets XML format.
droid –p “C:\Results\result1.droid” –n “File count and sizes” -t "DROID Report XML" –r “C:\Reports\result1Report.xml” -F "format_count > 2" "file_ext any pdf txt doc" |
To obtain a full list of the available filtering fields and operators, use the -k option, or see the Filtering Parameters Table
droid –c |
droid –d |
droid –X |
To list the default signatures a profile will use, unless overridden, use the -x option:
droid –x |
droid –s 97 |
This would set the DROID signature file version 97 - a binary signature - as the default. If we instead specified the version number of a container signature, then the container signature default would be set instead. The version numbers of all installed signatures can be obtained using the list signature command -X.
Field | Description | Operators | Examples |
---|---|---|---|
file_name | The filename of the file. The value to compare with must be surrounded with single quotes. | =, <>, starts, ends, contains, not starts, not ends, not contains |
file_name starts 'Invoice'
file_name = 'xxx' file_name not contains 'temp' |
file_size | The size of a file in bytes. | <, <=, =, <>, >, >= |
file_size > 100000
file_size <= 99999 |
file_ext | The file extension of the file name | =, <>, any, none |
file_ext = bmp
file_ext none tmp temp ignore |
last_modified | The date/time on which the file was last modified ( yyyy-MM-dd ) | <, <=, =, <>, >, >= | last_modified < 2020-01-31
last_modified >= 2000-01-01 |
format_count | The number of format identifications made | <, <=, =, <>, >, >= | format_count > 2
format_count = 1 |
type | The type of resource ( file | folder | container ) | any, none | type none folder
type any file container |
status | The identification job status ( not_done | done | access_denied | not_found | error ) | any, none |
status none done
status any access_denied not_found error |
method | How the file was identified ( extension | signature | container ) | any, none |
method none extension
method any signature container |
format_name | The file format description (text) | =, <>, starts, ends, contains, not starts, not ends, not contains |
format_name contains Microsoft
format_name not starts Adobe |
puid | The PUID identified (e.g. x-fmt/101) | any, none |
puid any fmt/111 fmt/112 fmt/113 fmt/114 fmt/115
puid none fmt/245 fmt/235 fmt/222 |
mime_type | The mime-type of the identification | any, none |
mime_type any text/plain text/html
mime_type none image/tiff image/jpeg image/gif |
extension_mismatch | Whether or not there is a mismatch between the PRONOM Unique Identifier and the file extension | =, <> |
extension_mismatch=true
extension_mismatch=false |
Note: If you want to filter on a list of values using any or none, and a value contains a space, then you can quote the value using single quotes.
Property | Value | Description | Notes |
---|---|---|---|
maxBytesToScan | Number | The maximum number of bytes DROID scans at the start and end of each file it attempts to identify. | Set to 65536 by default. If it is set to a negative number, DROID will scan the entire file. |
matchAllExtensions | true/false | Whether to match extensions even if a better signature-based identification exists. | If matches are made on extensions when there are better options, there may be more erroneous identifications. |
defaultBinarySigFileVersion | Filename | The filename of a binary signature to use to identify formats. | The binary signature file already exist in the standard path where binary signatures are stored by DROID. |
defaultContainerSigFileVersion | Filename | The filename of a container signature to use to identify formats. | The container signature file already exist in the standard path where binary signatures are stored by DROID. |
processTar | true/false | Whether to identify files inside tar files. | This is similar to the -At tar option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
processZip | true/false | Whether to identify files inside zip files. | This is similar to the -At zip option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
processGzip | true/false | Whether to identify files inside gzip files. | This is similar to the -At gzip option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
processRar | true/false | Whether to identify files inside rar files. | This is similar to the -At rar option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
process7zip | true/false | Whether to identify files inside tar files. | This is similar to the -At tar option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
processIso | true/false | Whether to identify files inside iso files. | This is similar to the -At iso option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
processBzip2 | true/false | Whether to identify files inside bzip2 files. | This is similar to the -At bzip2 option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
processArc | true/false | Whether to identify files inside arc files. | This is similar to the -Wt arc option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
processWarc | true/false | Whether to identify files inside warc files. | This is similar to the -Wt warc option, but this will only turn on or off processing for this type; not turn off other types of archive processing. |
generateHash | true/false | Whether to generate a hash for each file processed. | Generating hashes forces another scan of each file, so it affects performance. Only turn this on if you need hash values. |
hashAlgorithm | String | The hash algorithm to use if generating hashes. | Values can be md5, sha1 or sha256 |
defaultThrottle | Number | A delay in milliseconds between processing each file. | This can help to minimise the impact of DROID scanning a large volume of files, although it will make the results take longer to obtain. |
Column | Description |
---|---|
ID | A unique id for each resource identified. |
PARENT_ID | The id of the parent resource |
URI | A URI for the resource, including locations inside archive files. |
FILE_PATH | The path to the resource in the file system |
NAME | The name of the resource |
METHOD | The method used to identify the resource. |
STATUS | The identification status of the resource. |
SIZE | The size in bytes of the resource. |
TYPE | The type of the resource |
EXT | The file extension of the resource |
LAST_MODIFIED | The last modified date/time of the resource. |
EXTENSION_MISMATCH | Whether there is a mismatch between the extension of the resource and its identification by signature |
HASH | The hash value of the resource. |
FORMAT_COUNT | The number of identifications made to the resource. |
PUID | The PRONOM Unique Identifier of the resource, which identifies the format |
MIME_TYPE | The mime type of the resource where known. |
FORMAT_NAME | The name of the format the resource was identified as |
FORMAT_VERSION | The version of the format the resource was identified as |
Short name | Long name | Parameters | Description | Example |
---|---|---|---|---|
-h | --help | {none} | Prints the command line option help to the console. | droid -h |
-v | --version | {none} | Prints the version of DROID to the console. | droid -v |
-a | --profile-resources | One or more quoted paths to files and folders | Adds the resources listed to a profile for identification and runs identification. If not specified, DROID assumes any unbound parameters are -a options, so writing -a is optional. | droid -a "C:\Files\" "C:\More\spreadsheet.xls" |
-R | --recurse | {none} | Processes all sub-folders and the files and folders within them, recursively. | droid "C:\Files\" "C:\More\spreadsheet.xls" -R |
-q | --quiet | {none} | Suppresses log messages and other metadata sent to the console. | droid "C:\Files\" "C:\More\spreadsheet.xls" -q |
-o | --output-file | Quoted path to the CSV file to write to. | Writes identification results out to a CSV file, instead of to the console | droid "C:\Files\" "C:\More\spreadsheet.xls" -o "C:\Results\myresults.csv" |
-p | --profile(s) | One or more quoted paths to database files (.droid) | When used with the -a option, this specifies a single profile .droid file to write to. When used with exporting and reporting options, it specifies one or more profiles to load. |
droid "C:\Files\" "C:\More\spreadsheet.xls" -p "C:\Results\myresults.droid"
droid -p "C:\Results\myresults.droid" "C:\Results\myresults2.droid" -E "C:\Exports\export.csv" |
-ff | --filter-all-file | One or more quoted filter criteria. | Filters out files before any identification is made. Only file name, file size, file extensions or last modified date can be filtered with this option. All filter criteria specified must be fulfilled to pass the filter. This can increase performance, as opposed to filtering results after identification is made (see -f option). It can be used when writing to CSV or to a profile database. | droid "C:\Files\" "C:\More\spreadsheet.xls" -ff "file_size > 1000" "file_ext any jpg bmp txt" |
-FF | --filter-any-file | One or more quoted filter criteria. | Filters out files before any identification is made. Only file name, file size, file extensions or last modified date can be filtered with this option. At least one filter criteria specified must be fulfilled to pass the filter. This can increase performance, as opposed to filtering results after identification is made (see -F option). It can be used when writing to CSV or to a profile database. | droid "C:\Files\" "C:\More\spreadsheet.xls" -FF "file_size > 1000" "file_ext any jpg bmp txt" |
-Nx | --extension-list | One or more file extensions. | Filters out files to identify based on a list of file extensions. This is equivalent to using the -ff or -FF options above, which are more flexible. It is now provided only for backwards compatibility. | droid "C:\Files\" "C:\More\spreadsheet.xls" -Nx jpg bmp txt |
-f | --filter-all | One or more quoted filter criteria. | Filters out files from the results when exporting or reporting on previously saved profiles, or outputting to CSV. All filter criteria must be met to pass the filter. Note: it cannot filter out results while writing to a database (-a with -p option) as the database could end up in an inconsistent state. |
droid -p "C:\Results\myresults.droid" "C:\Results\myresults2.droid" -E "C:\Exports\export.csv" -f "file_size > 1000" "file_ext any jpg bmp txt"
droid "C:\Files\" "C:\More\spreadsheet.xls" -f "file_size > 1000" "file_ext any jpg bmp txt" |
-F | --filter-any | One or more quoted filter criteria. | Filters out files from the results when exporting or reporting on previously saved profiles, or outputting to CSV. At least one filter criteria must be met to pass the filter. Note: it cannot filter out results while writing to a database (-a with -p option) as the database could end up in an inconsistent state. |
droid -p "C:\Results\myresults.droid" "C:\Results\myresults2.droid" -E "C:\Exports\export.csv" -F "file_size > 1000" "file_ext any jpg bmp txt"
droid "C:\Files\" "C:\More\spreadsheet.xls" -F "file_size > 1000" "file_ext any jpg bmp txt" |
-Nr | --no-profile-resource | A quoted path to file or folder to scan. | Runs a simple profile outputting only the name and PUID to the console. Older versions of DROID also require the signature and container files to be specified using the -Ns and -Nc options. | droid -Nr “C:\Files\A Folder” -R |
-Ns | --signature-file | A quoted path to a binary signature file. | Sets the binary signature file to use when identifying files for this profile run only. | droid “C:\Files\A Folder” "C:\Files\A File” -Ns "C:\Signatures\binarysig.xml" |
-Nc | --container-file | A quoted path to a container signature file. | Sets the container signature file to use when identifying files for this profile run only. | droid “C:\Files\A Folder” "C:\Files\A File” -Nc "C:\Signatures\containersig.xml" |
-A | --open-all-archives | {none} | Instructs DROID to open all archive types (zip, tar, gzip, rar, 7zip, bzip2, fat and iso) | droid “C:\Files\A Folder” "C:\Files\A File” -A |
-W | --open-all-webarchives | {none} | Instructs DROID to open all web archive types (arc, warc) | droid “C:\Files\A Folder” "C:\Files\A File” -W |
-At | --open-archive-types | One or more archive types | Instructs DROID to open only the archive types specified (zip, tar, gzip, rar, 7zip, bzip2, fat and iso) | droid “C:\Files\A Folder” "C:\Files\A File” -At zip gzip 7zip bzip2 |
-Wt | --open-webarchive-types | One or more web archive types | Instructs DROID to open only the web archive types specified (arc, warc) ( | droid “C:\Files\A Folder” "C:\Files\A File” -Wt warc |
-Pr | --profile-property | One or more profile properties. | Sets the properties that a profile is run with. These will override the default properties for a profile or those specified with the -Pf option. | droid “C:\Files\A Folder” "C:\Files\A File” -Pr "maxBytesToScan=100000" "matchAllExtensions=true" |
-Pf | --property-file | A quoted path to a file containing properties. | Sets the properties contained in the property file specified for a profile run. Properties recorded in a file must have the prefix .profile before each property. These will override the default properties for a profile. If properties are also specified using the -Pr option, they will override any specified in the file. | droid “C:\Files\A Folder” "C:\Files\A File” -Pf "C:\Properties\config.properties" |
-ri | --row-per-id | {none} | Specifies that CSV output should write a row for each identification made. If a file has more than one identification, then more than one row will be output for that file. The default for CSV output is to write a row for each file, with multiple identifications being written as additional columns. | droid “C:\Files\A Folder” "C:\Files\A File” -ri |
-qc | --quote-commas | {none} | Specifies that CSV output should only quote fields that contain a comma. The default is for all fields to be quoted. | droid “C:\Files\A Folder” "C:\Files\A File” -qc |
-co | --columns | One or more column names to output | Specifies that CSV output should only write the columns specified. | droid “C:\Files\A Folder” "C:\Files\A File” -co FILE_PATH STATUS HASH PUID |
-e | --export-file | A quoted file path to the CSV file to write. | Exports one or more profiles (specified with the -p option) to a CSV file, writing one row per file. | droid -p "C:\Results\profile1.droid" "C:\Results\profile2.droid" -e "C:\Exports\export.csv" |
-E | --export-format | A quoted file path to the CSV file to write. | Exports one or more profiles (specified with the -p option) to a CSV file, writing one row per format identification. | droid -p "C:\Results\profile1.droid" "C:\Results\profile2.droid" -E "C:\Exports\export.csv" |
-n | --report-name | A quoted report name | Specifies what report to run on profiles selected with the -p option, written to a file specified with the -r option. | droid –p “C:\Results\result1.droid” –n “File count and sizes” –r “C:\Reports\result1Report.pdf” |
-r | --report | A quoted path to a file to write a report to. | Specifies the file that a report is written to. | droid –p “C:\Results\result1.droid” –n “File count and sizes” –r “C:\Reports\result1Report.pdf” |
-l | --list-reports | {none} | Lists the available report names and the output formats which are supported for them. | droid -l |
-t | --report-type | A quoted report type | Sets the type of report format to generate. By default, reports will be written as a PDF file. You can select either "PDF", "Text", "Web page", or "DROID Report XML". Some reports can have additional export options - the Comprehensive Breakdown report also supports the "Planets XML" format. | droid –p “C:\Results\result1.droid” –n “File count and sizes” –r “C:\Reports\result1Report.xml” -t "DROID Report XML" |
-c | --check-signature-update | {none} | Checks for signature updates, without downloading them. | droid -c |
-d | --download-signature-update | {none} | Downloads available signature updates. | droid -d |
-X | --list-signature-files | {none} | Lists all locally available signature files. | droid -X |
-x | --display-signature-file | {none} | Lists the current default signature files to use for identification. | droid -x |
-s | --set-signature-file | A version number | Sets either a binary or container signature to be the default for its type from the locally available signatures, using its version number to identify it. |
droid -s 97
droid -s 20200121 |
Welcome to DROID |