@4f/cli

Command-line interface for 4F – broken link checker and website monitoring.

Installation

npm install -g @4f/cli

Authentication

Create an API key in your account settings and set it as an environment variable:

export FOUREFF_API_KEY=4f_your_key_here

Or pass it with --key on any command:

4f --key 4f_your_key_here scan https://example.com

Note: The env var is FOUREFF_API_KEY — bash variable names cannot start with a digit. In CI systems that set secrets as-is, both FOUREFF_API_KEY and 4F_API_KEY are accepted.

Tab completion

Run once after installing, then restart your terminal:

4f completion setup

Supports bash, zsh, and fish. After setup, prefix matching works:

4f pro[tab]          → projects
4f projects cre[tab] → create
4f scan --ski[tab]   → --skip-external  --skip-seo

Commands

4f scan [url]

Trigger a scan and wait for results.

Exit codes: 0 = no issues, 1 = issues found, 2 = error. Ideal for CI/CD pipelines.

# Scan a URL directly
4f scan https://example.com

# Use an existing project (inherits its ignore patterns, sitemap, schedule, etc.)
4f scan --project <project-id>

# CI/CD: skip external links, suppress progress, fail build on broken internal links
4f scan https://example.com --skip-external --quiet
echo $?   # 0 = clean, 1 = broken links found

# Export results as CSV
4f scan https://example.com --format csv > report.csv

# Fire and forget – print scan ID and exit immediately
4f scan https://example.com --no-wait

| Flag | Default | Description | |------|---------|-------------| | -p, --project <id> | – | Use an existing project. Inherits all its crawl settings. Crawl flags below are ignored when this is set. | | --no-wait | – | Trigger the scan and return the scan ID without waiting for completion. | | --timeout <seconds> | 600 | Max time to wait for the scan to finish. | | --cancel-on-timeout | – | Cancel the scan on the server if the timeout is reached. Default: leave it running. | | --skip-external | – | Only report issues on internal URLs. | | --skip-seo | – | Exclude SEO/quality issues (title, meta description, headings, etc.). | | --all | – | Include URLs without issues. Default: issues only. | | --format <fmt> | json | Output format: json, text, csv. | | --quiet | – | Suppress progress output to stderr. Stdout remains clean for piping. | | --cleanup | – | Delete the created project after scanning. Default: keep it (visible in dashboard). | | --rate-limit <n> | 5 | Crawler requests per second. Options: 1 2 3 5 10 15 (plan limits apply). | | --slow-threshold <ms> | 3000 | Flag responses slower than this as slow. | | --no-respect-robots | – | Ignore robots.txt. | | --sitemap-url <url> | – | Custom sitemap URL. Starter+ only. |

Note: --rate-limit, --slow-threshold, --no-respect-robots, and --sitemap-url are ignored when --project is used. Update the project settings instead.

4f projects list

List all projects.

4f projects list
4f projects list --type personal
4f projects list --type team --format text

| Flag | Description | |------|-------------| | --type <type> | Filter by personal or team. | | --format <fmt> | json (default) or text. |

4f projects get <id>

Get details and crawl config for a project.

4f projects get <project-id>
4f projects get <project-id> --format text

| Flag | Description | |------|-------------| | --format <fmt> | Output format: json (default) or text. |

4f projects create

Create a new project.

4f projects create --name "My Site" --url https://example.com
4f projects create --name "My Site" --url https://example.com --rate-limit 10 --scan-frequency weekly
4f projects create --name "My Site" --url https://example.com --team

| Flag | Description | |------|-------------| | --name <name> | Required. Project name. | | --url <url> | Required. Root URL to scan. | | --team | Create as a team project. Default: personal. | | --rate-limit <n> | Requests per second: 1 2 3 5 10 15. | | --slow-threshold <ms> | Slow response threshold in ms. | | --no-respect-robots | Ignore robots.txt. | | --sitemap-url <url> | Custom sitemap URL (Starter+). | | --ignore-patterns <p> | Comma-separated URL substrings to skip. | | --scan-frequency <f> | manual, weekly, or daily (plan limits apply). | | --email-alerts <s> | always, new_issues, or disabled. | | --scheduled-hour <n> | Hour of day for scheduled scans (0–23). | | --scheduled-weekday <n> | Day of week for weekly scans (0=Sun, 6=Sat). | | --scheduled-timezone <tz> | IANA timezone, e.g. Europe/Vienna. | | --format <fmt> | Output format: json (default) or text. |

4f projects update <id>

Update a project's name or crawl settings. The root URL is immutable — delete and recreate to change it.

4f projects update <project-id> --name "New Name"
4f projects update <project-id> --rate-limit 10 --scan-frequency weekly --scheduled-hour 3
4f projects update <project-id> --ignore-patterns "/cdn/,/assets/"

| Flag | Description | |------|-------------| | --name <name> | New project name. | | --rate-limit <n> | Requests per second: 1 2 3 5 10 15. | | --slow-threshold <ms> | Slow response threshold in ms. | | --no-respect-robots | Ignore robots.txt. | | --sitemap-url <url> | Custom sitemap URL (Starter+). | | --ignore-patterns <p> | Comma-separated URL substrings to skip. | | --scan-frequency <f> | manual, weekly, or daily (plan limits apply). | | --email-alerts <s> | always, new_issues, or disabled. | | --scheduled-hour <n> | Hour of day for scheduled scans (0–23). | | --scheduled-weekday <n> | Day of week for weekly scans (0=Sun, 6=Sat). | | --scheduled-timezone <tz> | IANA timezone, e.g. Europe/Vienna. | | --format <fmt> | Output format: json (default) or text. |

4f projects delete <id>

Delete a project and all its scan history.

4f projects delete <project-id>

4f scans list

List scans for a project, newest first.

4f scans list --project <project-id>
4f scans list --project <project-id> --limit 5 --format text

| Flag | Description | |------|-------------| | -p, --project <id> | Required. Project ID to list scans for. | | --limit <n> | Number of scans to return. Default: 20. | | --format <fmt> | Output format: json (default) or text. |

4f scans get <id>

Get the status and summary of a scan.

4f scans get <scan-id>
4f scans get <scan-id> --format text

| Flag | Description | |------|-------------| | --format <fmt> | Output format: json (default) or text. |

4f scans delete <id>

Delete a scan and all its URL records.

4f scans delete <scan-id>

4f completion <shell>

Output a shell completion script or auto-install for the current shell.

# Auto-detect shell and install (run once, then restart terminal)
4f completion setup

# Print completion script manually
4f completion bash
4f completion zsh
4f completion fish

# Pipe into your shell config manually
4f completion zsh >> ~/.zshrc

Supported shells: bash, zsh, fish. The setup subcommand appends the appropriate source line to your shell's rc file automatically.

4f results <scan-id>

Fetch results for a completed scan.

4f results <scan-id>
4f results <scan-id> --skip-external --format text
4f results <scan-id> --format csv > report.csv

| Flag | Description | |------|-------------| | --skip-external | Only show issues on internal URLs. | | --skip-seo | Exclude SEO/quality issues (title, meta description, headings, etc.). | | --all | Include URLs without issues. | | --format <fmt> | json (default), text, or csv. |

CI/CD example

# GitHub Actions
- name: Check for broken links
  env:
    FOUREFF_API_KEY: ${{ secrets.FOUREFF_API_KEY }}
  run: |
    npx @4f/cli scan https://example.com --skip-external --quiet
    # exits 1 if broken internal links found, failing the build

For recurring checks, use an existing project with your preferred settings pre-configured:

npx @4f/cli scan --project <project-id> --skip-external --quiet

Output formats

JSON (default)

Machine-readable. Includes full issue details, severity, and the page each issue was found on.

Text

Human-readable summary grouped by issue type. Good for --format text in CI logs.

CSV

One row per issue. Columns: url, url_type, issue_type, severity, detail, status_code, response_time_ms, found_on_url, final_url. The detail column uses key:value | key:value notation for structured data (e.g. anchor:content | page:https://example.com/shop/).

Plan limits

| | Public | Free | Starter | Agency | |--|--------|------|---------|--------| | Pages/month | 1,000 | 10,000 | 50,000 | 500,000 | | Max pages/scan | 1,000 | 3,000 | 10,000 | 50,000 | | Max req/s | 5 | 5 | 10 | 15 | | Scheduled scans | – | – | Weekly | Daily | | Projects | – | 2 | 10 | 50 |