Documentation

Quick Start
Installation
CLI Reference
Scripting
Environment Functions
PDF Functions
Demo Script (AI-generated)
License Activation

---

Quick Start

Follow these steps to generate your first PDF report with AlfaReport.

Step 1: Download the executable

Choose the appropriate binary for your system architecture from the download page, then download AlfaReport:

wget -O alfareport https://alfareport.com/download/v1.0/x64/alfareport

Supported architectures: x64, x86, arm, riscv, mips, mipsel. Replace x64 with your architecture if needed.

Step 2: Set execute permission

chmod +x alfareport

Step 3: Add to PATH

To run alfareport from any location, add it to your PATH:

# For current session
export PATH="$PATH:$(pwd)"

# Make permanent
echo 'export PATH="$PATH:'$(pwd)'"' >> ~/.bashrc

Step 4: Create a "Hello World" script

Create a script named hello.js:

const pdf = new PDF();
pdf.text("Hello, World!");
pdf.save("hello.pdf");

Step 5: Run the script

alfareport hello.js

Or if you didn't add to PATH:

./alfareport hello.js

Result

You should see hello.pdf created in your current directory. Open it to view your first generated report!

---

Installation

Step 1: Download the executable

Choose the appropriate binary for your system architecture from the download page, then use wget to download AlfaReport to your current directory:

Supported architectures: x64, x86, arm, riscv, mips, mipsel.

wget -O alfareport https://alfareport.com/download/v1.0/x64/alfareport

If you encounter SSL certificate issues, use:

wget --no-check-certificate -O alfareport https://alfareport.com/download/v1.0/x64/alfareport

Alternatively, with curl:

curl -L -o alfareport https://alfareport.com/download/v1.0/x64/alfareport

Step 2: Set execute permission

Make the downloaded file executable:

chmod +x alfareport

Step 3: Add to PATH (optional but recommended)

To run alfareport from any location without specifying the full path, add the executable directory to your system PATH:

# Add to PATH for current session
export PATH="$PATH:/path/to/alfareport/directory"

# Make permanent (add to ~/.bashrc, ~/.zshrc, or ~/.profile)
echo 'export PATH="$PATH:/path/to/alfareport/directory"' >> ~/.bashrc

---

CLI Reference

Usage

alfareport js_script [options]

Arguments

• js_script - One or more input JavaScript files to process in one context

• Options

  • -v, --version - Show version
  • -s, --silent - Suppress all console output
  • -t, --timeout - Timeout for script execution (milliseconds)
  • -p, --param - Pass parameter to script. Format: key=value. In script use: params.key
  • -l, --license - License key
  • -h, --help - Display this help

Examples

alfareport script.js
alfareport script.js -s
alfareport script.js -p title="My Report" -p format=A4
alfareport mylib.js report.js -t 1000
alfareport script.js -l XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX
alfareport --version

---

Scripting

AlfaReport supports JavaScript syntax up to ES2020, including:

• Promises
• Async/await functions
• Proxies
• Arrow functions
• Destructuring assignment
• Template literals
• And more (classes, modules, optional chaining, nullish coalescing, etc.)

To generate a PDF document, you must create an instance of the built-in PDF class and use its methods. The available methods are described in the following sections.

Basic Example

const pdf = new PDF();
pdf.text("Hello, World!");
pdf.save("output.pdf");

Using async/await

AlfaReport does not support await at the top-level of a script (top-level await). If you use await—for example, when calling fetch—all code containing it must be inside an async function. The simplest way is to wrap the entire script body in the main function and call it.

async function main() {
    const res = await fetch("https://api.example.com/data");
    const data = await res.json();

    const pdf = new PDF();
    pdf.text(data.title);
    pdf.save("output.pdf");
}

main();

---

Environment Functions

readText(path)
readJSON(path)
fetch(url, options)

---

readText(path)

Reads a file and returns its contents as a string.

Parameters

• path (string) — path to the file

Returns (string) — file contents, or null if the file does not exist. Throws an error if the file could not be read.

Example

const text = readText("template.txt");

---

readJSON(path)

Reads a file and parses its contents as JSON.

Parameters

• path (string) — path to the file

Returns (object) — parsed JSON value, or undefined if the file does not exist. Throws an error if the file could not be read or contains invalid JSON.

Example

const data = readJSON("config.json");

---

fetch(url, options)

Performs an HTTP request. Returns a Promise, similar to the browser Fetch API.

Parameters

• url (string) — request URL
• options (object) — optional configuration:
  • method (string) — HTTP method. Default: "GET"
  • headers (object) — request headers as key-value pairs
  • body (string|object) — request body. If an object is passed, it is serialized to JSON and Content-Type: application/json is set automatically unless already specified
  • timeout (number) — request timeout in ms. Default: 10000
  • insecure (boolean) — disable SSL certificate verification. Default: false

Returns (Promise) — resolves with the response object. Rejects on network error or timeout.

Example

const res = await fetch("https://api.example.com/data", {
    method: "POST",
    headers: { "Authorization": "Bearer TOKEN" },
    body: { key: "value" },
    timeout: 5000,
});

---

PDF Functions

new PDF(pageSize, pageDirection, defaultFont)
pdf.text(text, x, y, width, lineSpacing, align)
pdf.font(name, size)
pdf.fontSize(size)
pdf.textColor(color)
pdf.fillColor(color)
pdf.strokeColor(color)
pdf.strokeWidth(width)
pdf.pageColor(color)
pdf.line(x1, y1, x2, y2)
pdf.rect(x, y, width, height, border)
pdf.ellipse(x, y, width, height, border)
pdf.image(file, x, y, width, height)
pdf.link(url, x, y, width, height, k)
pdf.textBounds(text, width, lineSpacing)
pdf.getMetrics()
pdf.resetBounds()
pdf.padding(left, right, top, bottom)
pdf.newPage()
pdf.gotoPage(pageNumber)
pdf.getPageCount()
pdf.paginate(options)
pdf.table(table, cells)
pdf.sign(options, callback)
pdf.save(path)

---

new PDF(pageSize, pageDirection, defaultFont)

Creates a new PDF document with a single blank page.

Parameters

• pageSize (string) — page size: "LETTER" "LEGAL" "A3" "A4" "A5" "B4" "B5" "EXECUTIVE" "US4x6" "US4x8" "US5x7" "COMM10". Default: "A4"
• pageDirection (string) — page orientation: "portrait" "landscape". Default: "portrait"
• defaultFont (string) — default font name. Default: "sans"

Example

const pdf = new PDF("A4", "portrait", "sans");

---

pdf.text(text, x, y, width, lineSpacing, align)

Renders text on the current page.

Parameters

• text (string) — text to render
• x (number) — horizontal position. Default: 0
• y (number) — vertical position. Default: current position
• width (number) — text block width. Default: page width − x
• lineSpacing (number) — line spacing. Default: 1
• align (string) — text alignment: "left" "center" "right". Default: "left"

Example

pdf.text("Hello, World!", 0, 100, 400, 1, "center");

---

pdf.font(name, size)

Sets the font for subsequent text rendering.

Parameters

• name (string) — the name of a preinstalled font (sans,sans_bold,sans_italic,sans_bold_italic) or the path to a font file (.ttf). Pass null to keep the current font.
• size (number) — font size in points. Default: 0 (keep current size)

Example

pdf.font("sans_bold", 12);

---

pdf.fontSize(size)

Sets the font size without changing the font family.

Parameters

• size (number) — font size in points

Example

pdf.fontSize(14);

---

pdf.textColor(color)

Sets the text color.

Parameters

• color (string) — CSS-style color value (e.g. "#ff0000")

Example

pdf.textColor("#333333");

---

pdf.fillColor(color)

Sets the fill color for shapes.

Parameters

• color (string) — CSS-style color value

Example

pdf.fillColor("#f0f0f0");

---

pdf.strokeColor(color)

Sets the stroke color for shapes and lines.

Parameters

• color (string) — CSS-style color value

Example

pdf.strokeColor("#000000");

---

pdf.strokeWidth(width)

Sets the stroke width for shapes and lines.

Parameters

• width (number) — stroke width in points. Default: 1

Example

pdf.strokeWidth(2);

---

pdf.pageColor(color)

Sets the background color for current page.

Parameters

• color (string) — CSS-style color value

Example

pdf.pageColor("#ffffcc");

---

pdf.line(x1, y1, x2, y2)

Draws a line between two points.

Parameters

• x1 (number) — start X. Default: 0
• y1 (number) — start Y. Default: current position
• x2 (number) — end X. Default: page width
• y2 (number) — end Y. Default: y1

Example

pdf.line(0, 200, 500, 200);

---

pdf.rect(x, y, width, height, border)

Draws a rectangle.

Parameters

• x (number) — horizontal position. Default: 0
• y (number) — vertical position. Default: current position
• width (number) — rectangle width. Default: page width − x
• height (number) — rectangle height. Default: 100
• border (number) — border width. Default: 0

Example

pdf.rect(0, 100, 400, 50);

---

pdf.ellipse(x, y, width, height, border)

Draws an ellipse.

Parameters

• x (number) — horizontal position. Default: 0
• y (number) — vertical position. Default: current position
• width (number) — ellipse width. Default: 100
• height (number) — ellipse height. Default: equals width
• border (number) — border width. Default: 0

Example

pdf.ellipse(100, 200, 80, 80);

---

pdf.image(file, x, y, width, height)

Places an image on the current page.

Parameters

• file (string) — path to the image file
• x (number) — horizontal position. Default: 0
• y (number) — vertical position. Default: current position
• width (number) — image width. Default: 0 (natural size)
• height (number) — image height. Default: 0 (natural size)

Example

pdf.image("logo.png", 0, 100, 200, 50);

---

pdf.link(url, x, y, width, height, k)

Places a clickable hyperlink area on the current page.

Parameters

• url (string) — target URL
• x (number) — horizontal position. Default: 0
• y (number) — vertical position. Default: 0
• width (number) — link area width. Default: 100
• height (number) — link area height. Default: 100
• border (number) — border width (for debugging). Default: 0

Example

pdf.link("https://example.com", 0, 100, 200, 20);

---

pdf.textBounds(text, width, lineSpacing)

Calculates the bounding box of a text block without rendering it.

Parameters

• text (string) — text to measure
• width (number) — maximum text block width. Default: 1000000
• lineSpacing (number) — line spacing. Default: 0

Returns an object:

• width (number) — actual text width
• height (number) — actual text height
• lines (number) — number of lines

Example

const bounds = pdf.textBounds("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", 200);
console.log(bounds);

---

pdf.getMetrics()

Returns layout metrics for the current page.

Returns an object:

• pageNumber (number) — current page number
• outerWidth / outerHeight (number) — full page dimensions
• innerWidth / innerHeight (number) — page dimensions minus padding
• paddingTop / paddingBottom / paddingLeft / paddingRight (number) — page padding values
• lineHeight (number) — current line height
• fontHeight (number) — current font height
• boundsTop / boundsBottom / boundsLeft / boundsRight (number) — current affected bounds

Example

const m = pdf.getMetrics();
console.log(m.innerWidth, m.innerHeight);

---

pdf.resetBounds()

Resets the affected bounds tracking (left, right, top, bottom) to zero.

Example

pdf.resetBounds();

---

pdf.padding(left, right, top, bottom)

Sets the page padding.

Parameters

• left (number) — left padding. Default: current value
• right (number) — right padding. Default: current value
• top (number) — top padding. Default: current value
• bottom (number) — bottom padding. Default: current value

Example

pdf.padding(20, 20, 40, 40);

---

pdf.newPage()

Adds a new page to the document.

Example

pdf.newPage();

---

pdf.gotoPage(pageNumber)

Switches the current drawing context to an existing page.

Parameters

• pageNumber (number) — 1-based page index

Example

pdf.gotoPage(1);

---

pdf.getPageCount()

Returns the total number of pages in the document.

Returns (number)

Example

const count = pdf.getPageCount();

---

pdf.paginate(options)

Adds page numbers to all pages.

Parameters

• options (object) — optional configuration:
  • halign (string) — horizontal alignment: "left" "center" "right". Default: "center"
  • valign (string) — vertical alignment: "top" "bottom". Default: "bottom"
  • format (string) — number format, use {PAGE} as placeholder. Default: "{PAGE}"
  • lineSpacing (number) — line spacing. Default: 1
  • skipFirst (number) — number of pages to skip. Default: 0
  • startNumber (number) — starting page number. Default: 1
  • marginX (number) — horizontal margin. Default: 0
  • marginY (number) — vertical margin. Default: 0

Example

pdf.paginate({ format: "Page {PAGE}", halign: "right", valign: "bottom" });

---

pdf.table(table, cells)

Renders a table on the current page. Supports flexible configuration of structure, dimensions, padding, borders, and styles for both the whole table and individual cells.

Parameters

• table (object) — table configuration:

  • x (number) — horizontal position in points
  • y (number) — vertical position in points. Default: current position
  • width (number) — table width in points. Default: page width
  • cols (number) — number of columns
  • rows (number) — number of rows. If neither cols nor rows is set, the table renders as a single row. If only one is set, the other is calculated automatically.
  • padding (number) — cell padding in points. Default: 5
  • paddingTop / paddingBottom / paddingLeft / paddingRight (number) — per-side cell padding
  • border (number) — border width. Default: 0.5
  • outerBorder / outerBorderTop / outerBorderBottom / outerBorderLeft / outerBorderRight (number) — outer border widths in points
  • cellBorder / cellBorderTop / cellBorderBottom / cellBorderLeft / cellBorderRight (number) — inner cell border widths in points
  • headerBorder (number) — border width for the header row (first row)
  • headerCellBorderTop / headerCellBorderBottom / headerCellBorderLeft / headerCellBorderRight (number) — border widths for header cells
  • headerOuterBorderTop / headerOuterBorderBottom / headerOuterBorderLeft / headerOuterBorderRight (number) — outer border widths for the header row
  • fontSize (number) — font size for table cells
  • headerFontSize (number) — font size for the header row
  • font (string) — font for table cells
  • headerFont (string) — font for the header row
  • bgColor / textColor / borderColor (string) — colors for table cells
  • outerBorderColor / cellBorderColor (string) — colors for outer and inner borders
  • headerBgColor / headerTextColor / headerBorderColor / headerOuterBorderColor / headerCellBorderColor (string) — colors for the header row

• cells (array) — array of cells, filled left to right, row by row. Each element can be a plain string or an object:

  • text (string) — cell text. If it contains \n, multiline mode is enabled automatically
  • width / height (number) — cell dimensions
  • padding / paddingTop / paddingBottom / paddingLeft / paddingRight (number) — cell padding
  • border / borderTop / borderBottom / borderLeft / borderRight (number) — cell border widths
  • fontSize (number) — font size
  • lineSpacing (number) — line spacing
  • multiline (boolean) — enable multiline mode
  • halign (string) — horizontal alignment: "left" "center" "right" "justify"
  • valign (string) — vertical alignment: "top" "center" "bottom"
  • bgColor / textColor / borderColor (string) — cell colors
  • font (string) — cell font

Notes

• The first row is treated as a header and styled with header* parameters.
• If neither cols nor rows is specified, all cells are placed in a single row.

Example

pdf.table(
    { cols: 3, border: 0.5, headerBgColor: "#eeeeee" },
    [
        { text: "Name", halign: "center" },
        { text: "Age",  halign: "center" },
        { text: "City", halign: "center" },
        "Alice", "30", "New York",
        "Bob",   "25", "London",
    ]
);

---

pdf.sign(options, callback)

Signs the document with a digital certificate. The operation is asynchronous — result is delivered via callback.

Parameters

• options (object) — signing configuration:

  General:

  • sigName (string) — signature field name. Default: "Signature1"
  • signer (string) — signer name
  • reason (string) — reason for signing
  • location (string) — signing location
  • contact (string) — signer contact info
  • certPath (string) — path to certificate file. Default: "cert.pem"
  • keyPath (string) — path to private key file. Default: "key.pem"
  • chainPath (string) — path to certificate chain file. Default: "chain.pem"

  Timestamp authority (TSA):

  • tsaEnabled (boolean) — enable TSA timestamp. Default: false
  • tsaUrl (string) — TSA server URL. Default: "http://timestamp.digicert.com"
  • tsaTimeout (number) — TSA request timeout in ms. Default: 1000
  • tsaAuthType (string) — TSA authentication type: "none" "basic" "bearer" "custom". Default: "none"
  • tsaBasicUsername (string) — username for basic auth. Default: "user"
  • tsaBasicPassword (string) — password for basic auth. Default: "password"
  • tsaBearerToken (string) — token for bearer auth. Default: "TOKEN"
  • tsaCustomHeader (string) — custom HTTP header for TSA request

  Visible signature rectangle:

  • rectEnabled (boolean) — show visible signature rectangle. Default: false
  • rectX / rectY (number) — rectangle position in points
  • rectWidth / rectHeight (number) — rectangle dimensions in points
  • rectFillColor (string) — rectangle fill color
  • rectStrokeColor (string) — rectangle stroke color. Default: "#000000"
  • rectStrokeWidth (number) — rectangle stroke width in points. Default: 0
  • rectText (string) — text inside the rectangle
  • rectTextX / rectTextY (number) — text position inside the rectangle
  • rectTextWidth / rectTextHeight (number) — text block dimensions
  • rectTextColor (string) — text color
  • rectTextLineSpacing (number) — text line spacing. Default: 1.0
  • rectTextHalign (string) — text horizontal alignment: "left" "center" "right". Default: "left"
  • rectTextValign (string) — text vertical alignment: "top" "middle" "bottom". Default: "top"
  • rectImage (string) — path to image inside the rectangle
  • rectImageX / rectImageY (number) — image position inside the rectangle
  • rectImageWidth / rectImageHeight (number) — image dimensions

• callback (function) — called when signing completes. Receives an error argument on failure, or no arguments on success.

Example

pdf.sign(
    {
        certPath: "cert.pem",
        keyPath: "key.pem",
        chainPath: "chain.pem",
        tsaEnabled: true,
        tsaUrl: "http://timestamp.digicert.com",
        rectEnabled: true,
        rectX: 50, rectY: 700, rectWidth: 200, rectHeight: 50,
        rectText: "Signed by Alice",
        rectFillColor: "#f0f0f0",
    },
    (err) => {
        if (err) throw err;
        pdf.save("signed.pdf");
    }
);

---

pdf.save(path)

Saves the document to disk. If the document has not been signed, a watermark may be applied depending on the library configuration.

Parameters

• path (string) — output file path

Example

pdf.save("output.pdf");

---

Demo Script (AI-generated)

The demo.js file is a complete working example covering every available API function — environment utilities (readText, readJSON, fetch), all PDF drawing and layout methods, tables, pagination.

It was generated entirely by an AI assistant based solely on this documentation, without any manual coding. This demonstrates that AlfaReport's API is straightforward enough to be used by AI agents out of the box: you can describe the report you need in plain language and let an AI write the script for you.

You can download demo.js and execute it:

alfareport demo.js

See result in demo_output.pdf.

License Activation

AlfaReport requires a valid license key.
You can provide it in two ways:

Option 1: Command line argument

Pass the license key directly using the -l or --license option:

alfareport report.js -l XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX

Option 2: License file

Place a plain text file named alfareport.lic in the same directory as the alfareport executable. The file should contain only the license key:

XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX

The license file is automatically detected at startup. This method is useful for automation scripts or when you don't want to type the key every time.

Note: If both the license file and command line parameter are provided, the command line parameter takes precedence.