{"_id":"@4f/cli","name":"@4f/cli","dist-tags":{"latest":"0.9.0"},"versions":{"0.9.0":{"name":"@4f/cli","version":"0.9.0","description":"CLI for the 4F broken link checker API","type":"module","bin":{"4f":"dist/index.js"},"scripts":{"build":"tsc","dev":"node --import tsx/esm src/index.ts","prepublishOnly":"npm run build"},"engines":{"node":">=18"},"dependencies":{"commander":"^12.0.0"},"devDependencies":{"@types/node":"^26.1.1","tsx":"^4.0.0","typescript":"^5.4.0"},"_id":"@4f/cli@0.9.0","gitHead":"5892f758fc2fe907eac3d431bd5762bd2fc922aa","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-MxhXK8Eq7y6TY67D0LAm5bEMyp2O6/9StF/eRO5ZAXY2PaU9QV7V7VLSkbW3qFqrGmgNoeA72RnUx4j25T7zyQ==","shasum":"0b07fd655f0411849265ce94deae4e0884ba2772","tarball":"https://registry.npmjs.org/@4f/cli/-/cli-0.9.0.tgz","fileCount":20,"unpackedSize":58375,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHueBScVPpBsSaIqMRq8Qm96UZ+SMDhuqhX/BWK3uPHXAiEA6x4fN+AdK9LRv58o9yGkP79AT5uiUtXW/Za152UQOgo="}]},"_npmUser":{"name":"msbt","email":"accounts@bits.at"},"directories":{},"maintainers":[{"name":"msbt","email":"accounts@bits.at"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cli_0.9.0_1783610924389_0.07653485060626353"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-09T15:28:44.241Z","0.9.0":"2026-07-09T15:28:44.556Z","modified":"2026-07-09T15:28:44.873Z"},"maintainers":[{"name":"msbt","email":"accounts@bits.at"}],"description":"CLI for the 4F broken link checker API","readme":"# @4f/cli\n\nCommand-line interface for [4F](https://www.4f.at) – broken link checker and website monitoring.\n\n## Installation\n\n```bash\nnpm install -g @4f/cli\n```\n\n## Authentication\n\nCreate an API key in your [account settings](https://www.4f.at/dashboard/account) and set it as an environment variable:\n\n```bash\nexport FOUREFF_API_KEY=4f_your_key_here\n```\n\nOr pass it with `--key` on any command:\n\n```bash\n4f --key 4f_your_key_here scan https://example.com\n```\n\n> **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.\n\n## Tab completion\n\nRun once after installing, then restart your terminal:\n\n```bash\n4f completion setup\n```\n\nSupports bash, zsh, and fish. After setup, prefix matching works:\n\n```\n4f pro[tab]          → projects\n4f projects cre[tab] → create\n4f scan --ski[tab]   → --skip-external  --skip-seo\n```\n\n---\n\n## Commands\n\n### `4f scan [url]`\n\nTrigger a scan and wait for results.\n\n**Exit codes:** `0` = no issues, `1` = issues found, `2` = error. Ideal for CI/CD pipelines.\n\n```bash\n# Scan a URL directly\n4f scan https://example.com\n\n# Use an existing project (inherits its ignore patterns, sitemap, schedule, etc.)\n4f scan --project <project-id>\n\n# CI/CD: skip external links, suppress progress, fail build on broken internal links\n4f scan https://example.com --skip-external --quiet\necho $?   # 0 = clean, 1 = broken links found\n\n# Export results as CSV\n4f scan https://example.com --format csv > report.csv\n\n# Fire and forget – print scan ID and exit immediately\n4f scan https://example.com --no-wait\n```\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-p, --project <id>` | – | Use an existing project. Inherits all its crawl settings. Crawl flags below are ignored when this is set. |\n| `--no-wait` | – | Trigger the scan and return the scan ID without waiting for completion. |\n| `--timeout <seconds>` | `600` | Max time to wait for the scan to finish. |\n| `--cancel-on-timeout` | – | Cancel the scan on the server if the timeout is reached. Default: leave it running. |\n| `--skip-external` | – | Only report issues on internal URLs. |\n| `--skip-seo` | – | Exclude SEO/quality issues (title, meta description, headings, etc.). |\n| `--all` | – | Include URLs without issues. Default: issues only. |\n| `--format <fmt>` | `json` | Output format: `json`, `text`, `csv`. |\n| `--quiet` | – | Suppress progress output to stderr. Stdout remains clean for piping. |\n| `--cleanup` | – | Delete the created project after scanning. Default: keep it (visible in dashboard). |\n| `--rate-limit <n>` | `5` | Crawler requests per second. Options: `1 2 3 5 10 15` (plan limits apply). |\n| `--slow-threshold <ms>` | `3000` | Flag responses slower than this as slow. |\n| `--no-respect-robots` | – | Ignore robots.txt. |\n| `--sitemap-url <url>` | – | Custom sitemap URL. Starter+ only. |\n\n> **Note:** `--rate-limit`, `--slow-threshold`, `--no-respect-robots`, and `--sitemap-url` are ignored when `--project` is used. Update the project settings instead.\n\n---\n\n### `4f projects list`\n\nList all projects.\n\n```bash\n4f projects list\n4f projects list --type personal\n4f projects list --type team --format text\n```\n\n| Flag | Description |\n|------|-------------|\n| `--type <type>` | Filter by `personal` or `team`. |\n| `--format <fmt>` | `json` (default) or `text`. |\n\n---\n\n### `4f projects get <id>`\n\nGet details and crawl config for a project.\n\n```bash\n4f projects get <project-id>\n4f projects get <project-id> --format text\n```\n\n| Flag | Description |\n|------|-------------|\n| `--format <fmt>` | Output format: `json` (default) or `text`. |\n\n---\n\n### `4f projects create`\n\nCreate a new project.\n\n```bash\n4f projects create --name \"My Site\" --url https://example.com\n4f projects create --name \"My Site\" --url https://example.com --rate-limit 10 --scan-frequency weekly\n4f projects create --name \"My Site\" --url https://example.com --team\n```\n\n| Flag | Description |\n|------|-------------|\n| `--name <name>` | **Required.** Project name. |\n| `--url <url>` | **Required.** Root URL to scan. |\n| `--team` | Create as a team project. Default: personal. |\n| `--rate-limit <n>` | Requests per second: `1 2 3 5 10 15`. |\n| `--slow-threshold <ms>` | Slow response threshold in ms. |\n| `--no-respect-robots` | Ignore robots.txt. |\n| `--sitemap-url <url>` | Custom sitemap URL (Starter+). |\n| `--ignore-patterns <p>` | Comma-separated URL substrings to skip. |\n| `--scan-frequency <f>` | `manual`, `weekly`, or `daily` (plan limits apply). |\n| `--email-alerts <s>` | `always`, `new_issues`, or `disabled`. |\n| `--scheduled-hour <n>` | Hour of day for scheduled scans (0–23). |\n| `--scheduled-weekday <n>` | Day of week for weekly scans (0=Sun, 6=Sat). |\n| `--scheduled-timezone <tz>` | IANA timezone, e.g. `Europe/Vienna`. |\n| `--format <fmt>` | Output format: `json` (default) or `text`. |\n\n---\n\n### `4f projects update <id>`\n\nUpdate a project's name or crawl settings. The root URL is immutable — delete and recreate to change it.\n\n```bash\n4f projects update <project-id> --name \"New Name\"\n4f projects update <project-id> --rate-limit 10 --scan-frequency weekly --scheduled-hour 3\n4f projects update <project-id> --ignore-patterns \"/cdn/,/assets/\"\n```\n\n| Flag | Description |\n|------|-------------|\n| `--name <name>` | New project name. |\n| `--rate-limit <n>` | Requests per second: `1 2 3 5 10 15`. |\n| `--slow-threshold <ms>` | Slow response threshold in ms. |\n| `--no-respect-robots` | Ignore robots.txt. |\n| `--sitemap-url <url>` | Custom sitemap URL (Starter+). |\n| `--ignore-patterns <p>` | Comma-separated URL substrings to skip. |\n| `--scan-frequency <f>` | `manual`, `weekly`, or `daily` (plan limits apply). |\n| `--email-alerts <s>` | `always`, `new_issues`, or `disabled`. |\n| `--scheduled-hour <n>` | Hour of day for scheduled scans (0–23). |\n| `--scheduled-weekday <n>` | Day of week for weekly scans (0=Sun, 6=Sat). |\n| `--scheduled-timezone <tz>` | IANA timezone, e.g. `Europe/Vienna`. |\n| `--format <fmt>` | Output format: `json` (default) or `text`. |\n\n---\n\n### `4f projects delete <id>`\n\nDelete a project and all its scan history.\n\n```bash\n4f projects delete <project-id>\n```\n\n---\n\n### `4f scans list`\n\nList scans for a project, newest first.\n\n```bash\n4f scans list --project <project-id>\n4f scans list --project <project-id> --limit 5 --format text\n```\n\n| Flag | Description |\n|------|-------------|\n| `-p, --project <id>` | **Required.** Project ID to list scans for. |\n| `--limit <n>` | Number of scans to return. Default: `20`. |\n| `--format <fmt>` | Output format: `json` (default) or `text`. |\n\n---\n\n### `4f scans get <id>`\n\nGet the status and summary of a scan.\n\n```bash\n4f scans get <scan-id>\n4f scans get <scan-id> --format text\n```\n\n| Flag | Description |\n|------|-------------|\n| `--format <fmt>` | Output format: `json` (default) or `text`. |\n\n---\n\n### `4f scans delete <id>`\n\nDelete a scan and all its URL records.\n\n```bash\n4f scans delete <scan-id>\n```\n\n---\n\n### `4f completion <shell>`\n\nOutput a shell completion script or auto-install for the current shell.\n\n```bash\n# Auto-detect shell and install (run once, then restart terminal)\n4f completion setup\n\n# Print completion script manually\n4f completion bash\n4f completion zsh\n4f completion fish\n\n# Pipe into your shell config manually\n4f completion zsh >> ~/.zshrc\n```\n\nSupported shells: `bash`, `zsh`, `fish`. The `setup` subcommand appends the appropriate `source` line to your shell's rc file automatically.\n\n---\n\n### `4f results <scan-id>`\n\nFetch results for a completed scan.\n\n```bash\n4f results <scan-id>\n4f results <scan-id> --skip-external --format text\n4f results <scan-id> --format csv > report.csv\n```\n\n| Flag | Description |\n|------|-------------|\n| `--skip-external` | Only show issues on internal URLs. |\n| `--skip-seo` | Exclude SEO/quality issues (title, meta description, headings, etc.). |\n| `--all` | Include URLs without issues. |\n| `--format <fmt>` | `json` (default), `text`, or `csv`. |\n\n---\n\n## CI/CD example\n\n```yaml\n# GitHub Actions\n- name: Check for broken links\n  env:\n    FOUREFF_API_KEY: ${{ secrets.FOUREFF_API_KEY }}\n  run: |\n    npx @4f/cli scan https://example.com --skip-external --quiet\n    # exits 1 if broken internal links found, failing the build\n```\n\nFor recurring checks, use an existing project with your preferred settings pre-configured:\n\n```bash\nnpx @4f/cli scan --project <project-id> --skip-external --quiet\n```\n\n---\n\n## Output formats\n\n### JSON (default)\nMachine-readable. Includes full issue details, severity, and the page each issue was found on.\n\n### Text\nHuman-readable summary grouped by issue type. Good for `--format text` in CI logs.\n\n### CSV\nOne row per issue. Columns: `url, url_type, issue_type, severity, detail, status_code, response_time_ms, found_on_url, final_url`.\nThe `detail` column uses `key:value | key:value` notation for structured data (e.g. `anchor:content | page:https://example.com/shop/`).\n\n---\n\n## Plan limits\n\n| | Public | Free | Starter | Agency |\n|--|--------|------|---------|--------|\n| Pages/month | 1,000 | 10,000 | 50,000 | 500,000 |\n| Max pages/scan | 1,000 | 3,000 | 10,000 | 50,000 |\n| Max req/s | 5 | 5 | 10 | 15 |\n| Scheduled scans | – | – | Weekly | Daily |\n| Projects | – | 2 | 10 | 50 |\n","readmeFilename":"README.md","_rev":"1-e629d9cb9409d9a0a7bdcfe516b20409"}