CLI Usage#

rmagic is a Rust-native alternative to the GNU file command. It identifies file types by evaluating magic rules against a file's contents.

Basic Usage#

# Identify a single file
rmagic document.pdf

# Identify multiple files
rmagic file1.bin file2.exe file3.pdf

# Read from stdin
cat unknown.bin | rmagic -

# Use built-in rules (no external magic file required)
rmagic --use-builtin archive.tar.gz

# Get help
rmagic --help

Arguments and Flags#

Positional Arguments#

Output Format Flags#

These two flags are mutually exclusive. Passing both --json and --text produces an error.

Magic File Flags#

The built-in rules cover common file types: ELF, PE/DOS, ZIP, TAR, GZIP, JPEG, PNG, GIF, BMP, and PDF. They are compiled at build time and require no external files.

Behavior Flags#

Output Formats#

Text Output (Default)#

Text output prints one line per file in the format filename: description:

$ rmagic image.png document.pdf
image.png: PNG image data
document.pdf: PDF document

When a file type cannot be determined, the description is data:

$ rmagic unknown.bin
unknown.bin: data

JSON Output#

JSON output varies based on the number of files being analyzed.

Single file -- pretty-printed JSON with a matches array:

rmagic --json image.png

{
  "matches": [
    {
      "description": "PNG image data",
      "offset": 0,
      "tags": [
        "image",
        "png"
      ],
      "mime_type": "image/png",
      "score": 90
    }
  ]
}

Multiple files -- JSON Lines format with one compact JSON object per line:

$ rmagic --json file1.bin file2.txt
{"filename":"file1.bin","matches":[...]}
{"filename":"file2.txt","matches":[...]}

Each line is a self-contained JSON object, making it straightforward to parse with line-oriented tools such as jq.

Stdin Support#

Use - as the filename to read input from stdin:

cat sample.bin | rmagic -

Stdin input is truncated to the configured max_string_length (8192 bytes by default). When truncation occurs, a warning is printed to stderr:

Warning: stdin input truncated to 8192 bytes

Output for stdin uses stdin as the filename:

$ echo "hello" | rmagic -
stdin: data

Stdin can be combined with regular file arguments:

rmagic --use-builtin file1.bin - file2.txt < input.dat

Exit Codes#

Strict Mode and Exit Codes#

Without --strict, processing errors for individual files are printed to stderr but do not affect the exit code. The tool continues processing remaining files and exits 0 if at least the overall invocation succeeded.

With --strict, the first processing error (I/O, parse, or evaluation) causes a non-zero exit code. The tool still processes all files and prints errors as they occur, but returns the exit code corresponding to the first error.

A "data" result (unknown file type) is never treated as an error, even in strict mode.

# Without strict: exits 0 even if some files fail
$ rmagic file1.bin nonexistent.bin file2.txt
file1.bin: data
Error processing nonexistent.bin: ...
file2.txt: data
$ echo $?
0

# With strict: exits with error code from first failure
$ rmagic --strict file1.bin nonexistent.bin file2.txt
file1.bin: data
Error processing nonexistent.bin: ...
file2.txt: data
$ echo $?
3

Magic File Discovery#

When --use-builtin is not specified and no --magic-file is provided, rmagic searches for a magic file in standard system locations. The search follows an OpenBSD-inspired approach, preferring human-readable text files over compiled binary .mgc files.

Search Order (Unix)#

Text directories and files are checked first. If a text-format file or directory is found, it is used immediately. If only binary .mgc files exist, the first one found is used as a fallback.

If none of these paths exist, rmagic falls back to /usr/share/file/magic.mgc.

Windows#

On Windows, the tool checks %APPDATA%\Magic\magic first, then falls back to the bundled third_party/magic.mgc.

Timeout Configuration#

The --timeout-ms flag sets a per-file timeout for magic rule evaluation. Each file gets its own independent timeout window. If evaluation exceeds the specified duration, the file is skipped with an error.

# Set a 500ms timeout per file
$ rmagic --timeout-ms 500 large_file.bin

# Combine with strict mode to fail on timeout
$ rmagic --strict --timeout-ms 1000 *.bin

Valid values range from 1 to 300000 (5 minutes).

Multiple File Processing#

When multiple files are provided, each file is processed sequentially with independent error handling. A failure in one file does not prevent processing of subsequent files.

$ rmagic --use-builtin image.png archive.zip README.md
image.png: PNG image data
archive.zip: Zip archive data
README.md: data

Errors for individual files are printed to stderr with the filename for context:

$ rmagic --use-builtin good.png /nonexistent bad_perms.bin
good.png: PNG image data
Error processing /nonexistent: ...
Error processing bad_perms.bin: ...

Examples#

Identify files with built-in rules#

$ rmagic --use-builtin photo.jpg
photo.jpg: JPEG image data, JFIF standard

JSON output for scripting#

$ rmagic --use-builtin --json binary.elf | jq '.matches[0].mime_type'
"application/x-executable"

Process files from a directory listing#

ls *.bin | xargs rmagic --use-builtin --strict

Custom magic file#

$ rmagic --magic-file /path/to/custom.magic firmware.img
firmware.img: ARM firmware image

Pipeline with stdin#

$ curl -sL https://example.com/file | rmagic --use-builtin -
stdin: Zip archive data

Strict mode in CI#

#!/bin/bash
rmagic --use-builtin --strict --json artifacts/*.bin
if [ $? -ne 0 ]; then
    echo "File identification failed" >&2
    exit 1
fi

Related Chapters#

• Getting Started -- installation and first steps
• Configuration -- evaluation configuration options
• Error Handling -- detailed error type documentation
• Command Reference -- complete flag and option reference