Skip to main content

Documentation Index

Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Global Installation

npm install -g figranium
Or use without installing globally via npx: 
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:
FlagDescription
--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:
FlagDescription
--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

FlagDefaultDescription
--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>11345Web 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:
VariableDescriptionDefault
PORTWeb dashboard port11345
SESSION_SECRETSession cookie signing keyAuto-generated
ALLOWED_IPSComma-separated IP allowlistOpen
ALLOW_PRIVATE_NETWORKSAllow scraping private IPstrue
TRUST_PROXYHonor X-Forwarded-* headersfalse
SESSION_COOKIE_SECUREHTTPS-only session cookiesfalse
HEADLESSSet to false to see the browser (non-Docker)true
LOG_LEVELLogging verbosity—
DB_TYPESet 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
Run on a schedule with cron: 
# Crontab: run every hour at the top of the hour
0 * * * * /usr/local/bin/figranium --agent --task "my-hourly-task"

​
Exit Codes

CodeMeaning
0Success
1Error (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.