# Bun Unavailability Fallback Mechanisms in the AI Job Search CLI

> Discover Bun fallback mechanisms in the AI Job Search CLI. Learn how the CLI automatically uses WebSearch to retrieve jobs when Bun is unavailable, ensuring continuous access to opportunities.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: how-to-guide
- Published: 2026-07-12

---

**When the Bun runtime is unavailable, the AI Job Search CLI automatically falls back to a universal WebSearch strategy, bypassing all Bun-dependent portal scrapers while maintaining job retrieval capabilities across all supported platforms.**

The ai-job-search repository by MadsLorentzen implements a robust job-scraper workflow that prioritizes runtime availability before executing portal-specific CLI tools. When the `bun --version` command fails or returns a non-zero exit code, the system gracefully degrades to web-based search methods rather than failing entirely, ensuring continuous job data retrieval regardless of local runtime configuration.

## Detecting Bun Runtime Availability

The fallback mechanism initiates with an explicit availability check defined in the **job-scraper** skill. Before attempting to execute any portal-specific CLI tools, the system validates that the Bun JavaScript runtime is properly installed and accessible in the environment path.

### The Version Check Command

According to the skill definition in [`.claude/skills/job-scraper/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-scraper/SKILL.md), the workflow executes the following validation:

```bash

# Step 1a – Check bun availability (inside the job-scraper skill)

bun --version || echo "bun not installed – falling back to WebSearch"

```

This command serves as the gatekeeper for the entire Bun-dependent execution path. If the command returns a non-zero exit code or the executable is not found in `$PATH`, the skill immediately transitions to the fallback protocol.

## WebSearch Fallback Strategy

When Bun unavailability is detected, the job-scraper abandons all native CLI integrations in favor of a **universal WebSearch approach**. This fallback ensures that job listings remain accessible even when optimized runtime-specific scrapers cannot execute.

### Skipping Bun-Based Portal CLIs

The fallback logic explicitly omits all portal-specific command-line tools that require Bun. These include:

- `linkedin-search` – LinkedIn job search CLI
- `jobbank-search` – Job Bank portal scraper  
- `jobnet-search` – JobNet integration tool

As documented in the skill workflow, these tools are completely bypassed when the runtime check fails, preventing execution errors and dependency-related failures.

### Universal Search Implementation

The system substitutes the native CLIs with generic `WebSearch` tool invocations using portal-specific query templates. The fallback logic operates as follows:

```bash

# Example of invoking the fallback (pseudo-code from the skill)

if ! command -v bun >/dev/null; then
  # Skip all bun CLIs, use generic web search for every portal

  for portal in "${PORTALS[@]}"; do
    WebSearch "search query for $portal"
  done
fi

```

Query templates for these fallback searches are maintained in [`.claude/skills/job-scraper/search-queries.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-scraper/search-queries.md), ensuring that WebSearch queries remain optimized for each portal's specific search syntax even when CLI tools are unavailable.

## Portal-Specific CLI Considerations

Individual portal CLIs in the `.agents/skills/` directory are designed with fallback compatibility in mind. The **linkedin-search** CLI, documented in [`.agents/skills/linkedin-search/cli/README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/linkedin-search/cli/README.md), runs with plain Bun and minimal dependencies, making the fallback transparent when Bun is present but non-critical when it is absent.

Conversely, the **jobbank-search** CLI, detailed in [`.agents/skills/jobbank-search/cli/README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/jobbank-search/cli/README.md), includes explicit documentation regarding Cloudflare blocks and recommends using the WebSearch fallback when the CLI encounters retrieval barriers, reinforcing the reliability of the fallback mechanism.

## Logging and Transparency

The job-scraper workflow includes explicit logging to ensure users understand when fallback mechanisms activate. **Step 5** of the workflow records that a WebSearch fallback occurred, providing clear audit trails showing which data sources switched from native CLI scraping to web-based retrieval.

This transparency ensures that users can differentiate between Bun-optimized data (typically faster and more structured) and WebSearch-derived results (universally accessible but potentially less structured), allowing for appropriate adjustments to search strategies.

## Summary

- **Availability Check**: The system runs `bun --version` before executing any portal CLIs, treating non-zero exits as Bun unavailability.
- **Complete Bypass**: All Bun-dependent tools including `linkedin-search`, `jobbank-search`, and `jobnet-search` are skipped when the runtime is missing.
- **WebSearch Substitution**: Generic `WebSearch` tool calls using templates from [`search-queries.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/search-queries.md) replace native CLI execution for universal compatibility.
- **Audit Logging**: Step 5 of the job-scraper workflow logs fallback activation, ensuring transparent operation tracking.
- **Documentation**: Fallback logic is explicitly defined in [`.claude/skills/job-scraper/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-scraper/SKILL.md) and reinforced in individual portal README files.

## Frequently Asked Questions

### What happens if Bun is partially installed but corrupted?

If `bun --version` returns a non-zero exit code or fails to execute, the job-scraper skill treats this as complete unavailability regardless of installation state. The system does not attempt to diagnose partial installations; it immediately triggers the WebSearch fallback to ensure workflow continuity.

### Does the WebSearch fallback support all job portals equally?

Yes, the fallback mechanism is designed to provide universal coverage. When Bun is unavailable, the skill uses portal-specific query templates from [`.claude/skills/job-scraper/search-queries.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-scraper/search-queries.md) to construct appropriate WebSearch queries for every configured portal, including LinkedIn, Job Bank, and JobNet, ensuring no portal is excluded due to runtime constraints.

### How can I verify if the fallback mechanism activated during a search?

The job-scraper workflow explicitly records fallback activation in **Step 5** of its execution log. Users can review these logs to identify when WebSearch was substituted for Bun-based CLI execution, providing clear visibility into which data retrieval method was used for each portal.

### Can I force the WebSearch fallback even if Bun is installed?

The current implementation automatically detects Bun availability through the `bun --version` check. To force WebSearch usage, you would need to temporarily remove Bun from your system `$PATH` or modify the availability check logic in [`.claude/skills/job-scraper/SKILL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-scraper/SKILL.md), as there is no configuration toggle to override the automatic runtime detection.