ASN Label Generator

A command-line tool for generating PDF sheets of labels with ASN (Archive Serial Number) numbers and corresponding QR codes, designed to work with the paperless-ngx document management system. This tool helps you create labels that can be attached to physical documents before scanning, allowing paperless-ngx to automatically assign unique identifiers to your scanned documents.

What it's used for

When you scan a document with a label generated by this tool, paperless-ngx will read the QR code and use the ASN number as the document's identifier. This creates a reliable link between your physical and digital documents, making it easier to:

• Track the relationship between physical and digital documents
• Quickly locate physical documents when needed
• Maintain a consistent naming scheme across your document management system
• Automate document processing workflows in paperless-ngx

The generated labels include both human-readable ASN numbers and QR codes.

Prerequisites

• Node.js >= 22.0.0
• pnpm (recommended) or npm
• Compatible label sheets (Avery L4731 or equivalent)

Installation & Setup

There are several ways to use this tool:

Method 1: Local Development Setup

# Clone the repository
git clone https://github.com/eikowagenknecht/asn-label-generator.git
cd asn-label-generator

# Install dependencies
pnpm install

# Run in development mode
pnpm dev -- [options]

Method 2: Production Build

# Clone and install as above, then build
pnpm build

# Run the built version
node dist/main.js [options]

Method 3: Global Installation

# From the project directory
pnpm build
pnpm link --global

# Now you can run from anywhere using
asn-label-generator [options]

Method 4: npx Usage

This is not available yet! I will publish this to npm soon.

# Run directly using npx
npx asn-label-generator [options]

Usage

Basic Usage

Generate a single page of labels starting with ASN00001:

asn-label-generator

Generate labels for a specific batch of documents:

asn-label-generator --num-labels 50

Common Examples

Generate labels for a large batch of documents:

asn-label-generator --pages 3 --start-asn 1000

Use custom prefixes for different document types so you can easily distinguish the labels:

asn-label-generator --prefixPrint "P" --digits 6  # For private documents
asn-label-generator --prefixPrint "B" --digits 6  # For business documents

The QR code itself will still contain ASN followed by the number, you can set this indivuidally with the --prefixQR option.

Continue from a partially used sheet:

asn-label-generator --skip 10

Advanced Options

Test label alignment with visible borders:

asn-label-generator --border

Adjust label positioning for your printer (offset values in millimeters):

asn-label-generator --offset-x 0.5 --offset-y -0.2 --scale-x 0.98

As an example, my Brother HL-L2350DW printer requires the following adjustments to manage to print the label content in the middle of each label:

asn-label-generator --offset-x 0 --offset-y -0.5 --scale-x 1.0 --scale-y 0.994475

All Available Options

Options:
  -p, --pages <number>     number of pages (default: 1)
  -n, --num-labels <number> number of labels (overrides --pages)
  -o, --output-file <file> output file path (default: "labels.pdf")
  -s, --start-asn <number> starting ASN number (default: 1)
  -b, --border            draw borders for testing
  -t, --top-down          order labels by column instead of by row
  -d, --digits <number>   digits in number (default: 5)
  --prefixQR <text>       prefix for labels embedded in the QR code (default: "ASN")
  --prefixPrint <text>    prefix for labels printed on the label (default: "ASN")
  --skip <number>         skip first N labels (default: 0)
  --format <format>       label format (default: "averyL4731")
  --offset-x <mm>         x offset in mm (default: 0)
  --offset-y <mm>         y offset in mm (default: 0)
  --scale-x <factor>      x scale factor (default: 1)
  --scale-y <factor>      y scale factor (default: 1)
  --margin-x <mm>         x margin in mm (default: 1)
  --margin-y <mm>         y margin in mm (default: 1)
  -h, --help             display help information

Label Format Support

Currently supports Avery L4731 labels with the following specifications:

• 7 columns × 27 rows on A4 paper
• Label size: 25.4mm × 10mm
• Gutter size: 2.5mm horizontal, 0mm vertical
• Page margins: 13.5mm top, 9mm left

These labels are chosen for their optimal size for document management - large enough to be easily readable but small enough to not obscure important document content.

Need support for a different label format? Please open an issue with the label specifications.

Development

# Run in development mode
pnpm dev

# Run linting
pnpm lint

# Build for production
pnpm build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the terms of the MIT license.

Acknowledgments

Built with:

• Commander.js for CLI parsing
• PDFKit for PDF generation
• node-qrcode for QR code generation
• Zod for runtime type checking

Special thanks to the paperless-ngx community for inspiration and feedback.

If this project is not exactly what you're looking for, you might also be interested in the alternatives:

• tmiaier/asn-qr-code-label-generator
  • A web-based version with less customization options
• entropia/paperless-asn-qr-codes
  • A similar tool built with Python with support for more label formats but no custom prefixes or offsets
• aborelis/ASN-Label-Generator
  • A similar tool built with Python with support for colored labels, based on gitolicious/averyasn based on timrprobocom/AveryLabels.py