Appendix B: Command Reference

Command-line interface documentation for the rmagic file identification tool.

Overview

rmagic is a pure-Rust implementation of the file command for file type identification using magic rules.

Installation

# From source
git clone https://github.com/EvilBit-Labs/libmagic-rs
cd libmagic-rs
cargo install --path .

Synopsis

rmagic [OPTIONS] <FILE>...
rmagic [OPTIONS] -

Description

rmagic analyzes files and determines their types based on magic rules. It examines file contents rather than relying on file extensions, providing accurate identification for binary files, archives, executables, images, and more.

Arguments

Options

Output Format

Note: --json and --text are mutually exclusive.

Magic File Selection

Note: --magic-file and --use-builtin are mutually exclusive.

Behavior

Help

Exit Codes

Output Formats

Text Format (Default)

One line per file in the format:

filename: description

Examples:

document.pdf: PDF document
image.png: PNG image data
binary.exe: PE32 executable

JSON Format

Single file: Pretty-printed JSON with full details.

{
  "matches": [
    {
      "message": "ELF 64-bit LSB executable",
      "offset": 0,
      "length": 4,
      "value": "7f454c46",
      "rule_path": [
        "elf",
        "executable"
      ],
      "confidence": 90,
      "mime_type": "application/x-executable"
    }
  ]
}

Multiple files: JSON Lines format (compact, one JSON object per line).

{"filename":"file1.bin","matches":[...]}
{"filename":"file2.bin","matches":[...]}

Magic File Discovery

When no --magic-file is specified and --use-builtin is not used, rmagic searches for magic files in this order (OpenBSD-style, text-first):

Text Directories (Highest Priority)

1. /usr/share/file/magic/Magdir
2. /usr/share/file/magic

Text Files

3. /usr/share/misc/magic
4. /usr/local/share/misc/magic
5. /etc/magic
6. /opt/local/share/file/magic

Binary Files (Fallback)

7. /usr/share/file/magic.mgc
8. /usr/local/share/misc/magic.mgc
9. /opt/local/share/file/magic.mgc
10. /etc/magic.mgc
11. /usr/share/misc/magic.mgc

Development Fallbacks

12. missing.magic (current directory)
13. third_party/magic.mgc

Note: Binary .mgc files are currently unsupported. Use --use-builtin or a text magic file.

Built-in Rules

The --use-builtin flag uses pre-compiled rules for common file types:

Examples

Basic Usage

# Identify a single file
rmagic document.pdf

# Identify multiple files
rmagic *.bin

# Use built-in rules
rmagic --use-builtin image.png

# Read from stdin
cat unknown.bin | rmagic -

JSON Output

# Single file with pretty JSON
rmagic --json executable.elf

# Multiple files with JSON Lines
rmagic --json file1.bin file2.bin file3.bin

# Parse JSON output with jq
rmagic --json binary.exe | jq '.matches[0].text'

Custom Magic File

# Use specific magic file
rmagic --magic-file /path/to/custom.magic files/*

# Use magic directory (Magdir style)
rmagic --magic-file /usr/share/file/magic files/*

Error Handling

# Strict mode - fail on first error
rmagic --strict *.bin

# With timeout protection
rmagic --timeout-ms 5000 large-file.bin

# Combine options
rmagic --strict --timeout-ms 10000 --json *.bin

Pipeline Usage

# Find all ELF files
find . -type f -exec rmagic --use-builtin {} + | grep ELF

# Process files and output JSON
for f in *.bin; do
    rmagic --json "$f" >> results.jsonl
done

# Use with xargs
find . -name "*.dat" -print0 | xargs -0 rmagic --use-builtin

Scripting

#!/bin/bash
# Check if file is an image

if rmagic --use-builtin "$1" | grep -q "image"; then
    echo "File is an image"
    exit 0
else
    echo "File is not an image"
    exit 1
fi

Environment Variables

Platform-Specific Behavior

Unix (Linux, macOS, BSD)

• Full magic file discovery
• Memory-mapped file access
• Standard Unix exit codes

Windows

• Limited magic file locations
• Falls back to %APPDATA%\Magic\magic
• Uses third_party/magic.mgc in CI

Troubleshooting

Common Issues

“Magic file not found”

# Solution 1: Use built-in rules
rmagic --use-builtin file.bin

# Solution 2: Specify magic file path
rmagic --magic-file /path/to/magic file.bin

# Solution 3: Check available locations
ls -la /usr/share/misc/magic /usr/share/file/magic* 2>/dev/null

“Unsupported format: binary .mgc”

# Binary .mgc files are not supported
# Use --use-builtin or a text magic file

rmagic --use-builtin file.bin

“Evaluation timeout”

# Increase timeout
rmagic --timeout-ms 30000 large-file.bin

# Or use simpler rules
rmagic --use-builtin large-file.bin

“Permission denied”

# Check file permissions
ls -la file.bin

# Fix permissions if needed
chmod +r file.bin

Debug Tips

# Check which magic file is being used
rmagic --help  # Shows version

# Test with built-in rules first
rmagic --use-builtin test-file.bin

# Verbose error with strict mode
rmagic --strict file.bin

Comparison with GNU file

Migration from file

# Before (GNU file)
file document.pdf

# After (rmagic)
rmagic document.pdf

# With options
file -i document.pdf      # MIME type
rmagic --json document.pdf | jq '.matches[0].mime_type'

See Also

• API Reference - Library API documentation
• Architecture Overview - Internal design documentation
• file(1) - GNU file command
• magic(5) - Magic file format