CLI Tool & Standalone Scripts

The official figranium NPM package is retired and is not supported from v0.13 onward. Install and run Figranium via Docker or from source instead. The npm/npx commands below are kept for reference for users on older releases.

Figranium can be run entirely from the command line, either as a persistent web server or in standalone modes for one-off scraping and automation tasks.

Installation

npm install -g figranium

npx figranium

Usage

figranium [options]
figranium --scrape --url <url> [--selector <css>]
figranium --agent --task <id>
figranium --headful --url <url>

Modes

Start Web Dashboard (Default)

Running figranium with no arguments starts the full web dashboard at http://localhost:11345.

figranium
figranium --port 8080   # Start on a custom port

Scraper Mode (--scrape)

Runs a fast, one-off page scrape without full agent logic. Ideal for simple text extraction tasks.

figranium --scrape --url "https://example.com" --selector ".product-price"

Flags for --scrape:

Flag	Description
`--url <url>`	Required. Target URL to scrape.
`--selector <css>`	CSS selector to extract text from.
`--output <file>`	Optional file path to write the JSON result.
`--wait <seconds>`	Seconds to wait after page load before extracting.
`--task <id>`	Load a saved scrape task by ID (merged with other flags).

Example — Save to file:

figranium --scrape --url "https://quotes.toscrape.com" --selector ".quote" --output quotes.json

Agent Mode (--agent)

Executes the full block-based automation engine for a saved task.

figranium --agent --task "my-task-id"

Flags for --agent:

Flag	Description
`--task <id>`	Required. Run a saved task by its ID.
`--url <url>`	Override the task’s starting URL.

What gets printed:

All step-by-step execution logs
Final data output as formatted JSON

Example output:

Figranium: Initializing standalone execution...
Loaded task: Scrape Products (agent)
Mode: Agent | URL: https://shop.example.com

--- Agent Execution Finished ---
Logs:
  Navigated to https://shop.example.com
  Clicked #accept-cookies
  Found 24 product cards

Data Output:
[
  { "name": "Widget A", "price": "$9.99" },
  ...
]

Headful Mode (--headful)

Launches a visible Chromium browser for manual inspection and debugging.

figranium --headful --url "https://example.com"

The browser opens on your display (requires a graphical environment). On a headless server, use the VNC integration instead — see Headful Browser.

All Flags Reference

Flag	Default	Description
`--scrape`	—	Run in scrape mode
`--agent`	—	Run in agent mode
`--headful`	—	Open a visible browser
`--url <url>`	—	Target URL
`--task <id>`	—	Load a saved task by ID
`--selector <css>`	—	CSS selector (scrape mode)
`--wait <seconds>`	—	Seconds to wait after load
`--port <number>`	`11345`	Web server port
`--help`, `-h`	—	Show help message

Environment Variables

All CLI modes respect the same environment variables as the server. Set them in your shell or a .env file:

Variable	Description	Default
`PORT`	Web dashboard port	`11345`
`SESSION_SECRET`	Session cookie signing key	Auto-generated
`ALLOWED_IPS`	Comma-separated IP allowlist	Open
`ALLOW_PRIVATE_NETWORKS`	Allow scraping private IPs	`true`
`TRUST_PROXY`	Honor `X-Forwarded-*` headers	`false`
`SESSION_COOKIE_SECURE`	HTTPS-only session cookies	`false`
`HEADLESS`	Set to `false` to see the browser (non-Docker)	`true`
`LOG_LEVEL`	Logging verbosity	—
`DB_TYPE`	Set to `postgres` for PostgreSQL storage	—

Scripting and Automation

Combine CLI modes with shell scripts for automated pipelines:

#!/bin/bash
# Run a scrape and pipe results to a processor
figranium --scrape --url "https://api.example.com/data" \
  --selector ".data-row" \
  --output /tmp/scraped.json

python3 process_data.py /tmp/scraped.json

# Crontab: run every hour at the top of the hour
0 * * * * /usr/local/bin/figranium --agent --task "my-hourly-task"

Exit Codes

Code	Meaning
`0`	Success
`1`	Error (task not found, scrape/agent failed)

Troubleshooting

Task not found

Error: Task "my-task-id" not found.

The task ID must match exactly as stored in data/tasks.json. Retrieve the correct ID from the web dashboard URL or the REST API (GET /api/tasks).

Playwright browsers not installed

Error: browserType.launch: Failed to launch chromium

Run npx playwright install chromium to download the required browser binaries.

REST API

Programmatically trigger tasks and manage executions via HTTP.

Task Scheduling

Automate recurring runs with cron and frequency-based schedules.

Configuration

Environment variables and server configuration reference.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

CLI Tool & Standalone Scripts

Installation

Usage

Modes

All Flags Reference

Environment Variables

Scripting and Automation

Exit Codes

Troubleshooting

REST API

Task Scheduling

Configuration

​Installation

​Usage

​Modes

​All Flags Reference

​Environment Variables

​Scripting and Automation

​Exit Codes

​Troubleshooting

REST API

Task Scheduling

Configuration

Installation

Usage

Modes

All Flags Reference

Environment Variables

Scripting and Automation

Exit Codes

Troubleshooting