CLI Usage

The rmagic command-line tool identifies file types using magic rules, serving as a pure-Rust alternative to the GNU file command.

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