Skip to content

CLI Reference

@4f/cli is the official command-line interface for 4F. Trigger scans, manage projects, fetch results, and integrate with CI/CD pipelines - all from your terminal. Uses the same REST API under the hood.

Installation

Install globally to use the 4f command anywhere:

npm install -g @4f/cli

Or run without installing via npx:

npx @4f/cli scan https://example.com

Authentication

Create an API key in Account → API keys and set it as an environment variable:

export FOUREFF_API_KEY=4f_your_key_here

Or pass it inline 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. CI systems that set secrets as-is also accept 4F_API_KEY.

Tab completion

Run once after installing, then restart your terminal:

4f completion setup

Supports bash, zsh, and fish. After setup, partial command and flag names are expanded on Tab. See completion for manual install options.

scan

4f scan [url]

Trigger a scan and wait for results. Exits 0 if no issues were found, 1 if issues were found, 2 on error - making it suitable as a CI gate. Pass a URL to scan directly, or use --project to run against an existing project (which inherits its ignore list, sitemap, and crawl settings).

Example

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

# Use an existing project
4f scan --project PROJECT_ID

# CI/CD: fail build on broken internal links
4f scan https://example.com --skip-external --quiet

# 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

Flags

-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 immediately, printing the scan ID.

--timeout <seconds>default: 600

Max seconds 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>default: json

Output format: json, text, or 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>default: 5

Crawler requests per second. Options: 1, 2, 3, 5, 10, 15 (plan limits apply).

--slow-threshold <ms>default: 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 set - update the project settings instead.

projects

projects list

4f projects list

List all projects on your account.

Example

4f projects list
4f projects list --type personal
4f projects list --format text
--type <type>

Filter by personal or team.

--format <fmt>default: json

Output format: json or text.

projects get

4f projects get <id>

Get details and crawl config for a project.

Example

4f projects get PROJECT_ID
--format <fmt>default: json

Output format: json or text.

projects create

4f projects create

Create a new project. --name and --url are required.

Example

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

Project name. Required.

--url <url>

Root URL to scan. Required.

--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>default: json

Output format: json or text.

projects update

4f projects update <id>

Update a project's name or crawl settings. The root URL is immutable - delete and recreate to change it. Only the fields you pass are updated.

Example

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/"
--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>default: json

Output format: json or text.

projects delete

4f projects delete <id>

Permanently delete a project and all its scan history.

Example

4f projects delete PROJECT_ID

scans

scans list

4f scans list

List scans for a project, newest first. --project is required.

Example

4f scans list --project PROJECT_ID
4f scans list --project PROJECT_ID --limit 5
-p, --project <id>

Project ID to list scans for. Required.

--limit <n>default: 20

Number of scans to return.

--format <fmt>default: json

Output format: json or text.

scans get

4f scans get <id>

Get the status and summary of a scan. Poll every 5-10 seconds until status is completed or failed.

Example

4f scans get SCAN_ID
--format <fmt>default: json

Output format: json or text.

scans delete

4f scans delete <id>

Delete a scan and all its URL records.

Example

4f scans delete SCAN_ID

results

4f results <scan-id>

Fetch all results for a completed scan. By default returns only URLs with issues; pass --all to include clean URLs.

Example

4f results SCAN_ID
4f results SCAN_ID --skip-external --format text
4f results SCAN_ID --format csv > report.csv
--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>default: json

Output format: json, text, or csv.

completion

4f completion <shell>

Output a shell completion script, or pass setup to auto-install for your current shell. Supported shells: bash, zsh, fish.

Example

# 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

# Append manually to shell config
4f completion zsh >> ~/.zshrc

Output formats

json (default)

Machine-readable. Includes full issue details, severity, and the page each issue was found on. Suitable for piping into other tools.

text

Human-readable summary grouped by issue type. Good for reading 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.

Exit codes

The scan command uses structured exit codes, making it easy to use as a CI gate without parsing output:

0Scan completed, no issues found.
1Scan completed, issues were found.
2An error occurred.

CI/CD

Use --skip-external --quiet for a clean CI gate that only fails on broken internal links:

# 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 so the CLI inherits its ignore list, sitemap, and crawl settings:

npx @4f/cli scan --project PROJECT_ID --skip-external --quiet

Plan limits

PublicFreeStarterAgency
Pages/month1,00010,00050,000500,000
Max pages/scan1,0003,00010,00050,000
Max req/s551015
Projects-21050
Scheduled scans--WeeklyDaily

The CLI validates your rate limit flag against plan limits before sending any request. Exceeding your monthly quota returns an API error.