> ## 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.

# CLI Tool & Standalone Scripts

<Warning>
  **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.
</Warning>

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**

```bash theme={null}
npm install -g figranium
```

Or use without installing globally via `npx`:

```bash theme={null}
npx figranium
```

## **Usage**

```text theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
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:**

```text theme={null}
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.

```bash theme={null}
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](/docs/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:

```bash theme={null}
#!/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:**

```bash theme={null}
# 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:**

```text theme={null}
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:**

```text theme={null}
Error: browserType.launch: Failed to launch chromium
```

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