### Run Local Development Server

Source: https://github.com/dakheera47/job-ops/blob/main/CONTRIBUTING.md

Install dependencies, migrate the database, and start the orchestrator development server.

```bash
npm ci
npm --workspace orchestrator run db:migrate
npm --workspace orchestrator run dev
```

--------------------------------

### Environment Setup

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Copy the example environment file and configure necessary keys. The application supports various LLM providers like OpenAI, GLM, LM Studio, Ollama, and Gemini. API keys can be set via environment variables or the UI.

```bash
cp .env.example .env
# The app is self-configuring. You can add keys via the UI Onboarding.
```

--------------------------------

### Start Local Development Server

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/README.md

Run this command from the repository root to start the local documentation server. The server will be accessible at http://localhost:3006.

```bash
npm run docs:dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Navigate to the orchestrator directory and install project dependencies using npm.

```bash
cd orchestrator
npm install
```

--------------------------------

### Install Playwright Firefox Browser

Source: https://github.com/dakheera47/job-ops/blob/main/extractors/ukvisajobs/README.md

Installs the Firefox browser for Playwright if it was skipped during the initial setup.

```bash
npx playwright install firefox
```

--------------------------------

### Local Run Example for Hiring Cafe Extractor

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/extractors/hiring-cafe.md

This command demonstrates how to run the Hiring Cafe extractor locally. It sets environment variables for search terms, country, and maximum jobs per term, then executes the start script.

```bash
HIRING_CAFE_SEARCH_TERMS='["backend engineer"]' \
HIRING_CAFE_COUNTRY='united kingdom' \
HIRING_CAFE_MAX_JOBS_PER_TERM='50' \
npm --workspace hiringcafe-extractor run start
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/dakheera47/job-ops/blob/main/extractors/ukvisajobs/README.md

Installs the necessary project dependencies using npm.

```bash
npm install
```

--------------------------------

### Run Development Server (Client Only)

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Start only the frontend client for development purposes.

```bash
npm run dev:client
```

--------------------------------

### Run Development Server (Server Only)

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Start only the backend server for development purposes.

```bash
npm run dev:server
```

--------------------------------

### Start Development Server

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Launch the development server to run both the backend API and the frontend client. The backend will be available at http://localhost:3001 and the frontend at http://localhost:5173.

```bash
npm run dev
```

--------------------------------

### Start JobOps Docker Compose Stack

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/getting-started/self-hosting.md

Use this command to pull the pre-built image and start the JobOps API, UI, and scrapers in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Build and Start JobOps Locally

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/getting-started/self-hosting.md

Build the JobOps image locally and start the stack in detached mode. Useful for development or when pre-built images are not suitable.

```bash
docker compose up -d --build
```

--------------------------------

### Start the Extractor

Source: https://github.com/dakheera47/job-ops/blob/main/extractors/ukvisajobs/README.md

Starts the UK Visa Jobs Extractor. Output is saved to storage/datasets/default/ as JSON files.

```bash
npm start
```

--------------------------------

### Example Extractor Manifest

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/workflows/add-an-extractor.md

This is an example of an extractor manifest file. It defines the extractor's ID, display name, provided sources, required environment variables, and the run function.

```typescript
import type { ExtractorManifest } from "@shared/types/extractors";

export const manifest: ExtractorManifest = {
  id: "myextractor",
  displayName: "My Extractor",
  providesSources: ["myextractor"],
  requiredEnvVars: ["MYEXTRACTOR_API_KEY"],
  async run(context) {
    // context.searchTerms, context.settings, context.onProgress, context.shouldCancel
    const jobs = [];
    return { success: true, jobs };
  },
};

export default manifest;
```

--------------------------------

### Start Gmail OAuth API

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/workflows/post-application-workflow.md

Initiate the Gmail OAuth flow by calling this API. Ensure the accountKey parameter is correctly set.

```bash
curl "http://localhost:3001/api/post-application/providers/gmail/oauth/start?accountKey=default"
```

--------------------------------

### Restore Database from Backup File

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/getting-started/database-backups.md

This example demonstrates how to restore the JobOps database by copying a backup file over the main database file. Ensure JobOps is stopped before performing the restore.

```bash
# Example only: adjust paths for your setup
cp /path/to/data/jobs_manual_2026_02_15_10_20_30.db /path/to/data/jobs.db
```

--------------------------------

### Clone and Run JobOps with Docker Compose

Source: https://github.com/dakheera47/job-ops/blob/main/README.md

Quickly set up and run JobOps locally using Docker Compose. This command clones the repository, navigates into the directory, and starts the services.

```bash
git clone https://github.com/DaKheera47/job-ops.git
cd job-ops
docker compose up -d
```

--------------------------------

### Start Gmail OAuth Flow

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/post-application-tracking.md

Initiates the OAuth 2.0 flow for connecting a Gmail account.

```APIDOC
## POST /api/post-application/providers/gmail/oauth/start

### Description
Starts the OAuth 2.0 flow for connecting a Gmail account.

### Method
POST

### Endpoint
/api/post-application/providers/gmail/oauth/start
```

--------------------------------

### Setup Python Virtual Environment for Extractors

Source: https://github.com/dakheera47/job-ops/blob/main/CONTRIBUTING.md

Create and populate a Python virtual environment for extractors that use python-jobspy. The runner automatically detects this venv.

```bash
python3 -m venv extractors/jobspy/.venv
extractors/jobspy/.venv/bin/pip install -r extractors/jobspy/requirements.txt
```

--------------------------------

### n8n Webhook Setup

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Configure an n8n workflow to trigger the Job Ops pipeline via a scheduled HTTP POST request. Ensure the correct URL and a valid `Authorization` header with your `WEBHOOK_SECRET` are used.

```bash
# Schedule Trigger - Every day at 17:00
# HTTP Request:
#   Method: POST
#   URL: http://localhost:3001/api/webhook/trigger
#   Headers: Authorization: Bearer YOUR_WEBHOOK_SECRET
```

--------------------------------

### Get Effective Settings

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/reactive-resume.md

Retrieve the current effective settings, including resolved resume projects and the base resume ID. Useful for understanding the current configuration state.

```bash
# Get effective settings (includes resolved resumeProjects and base resume id)
curl "http://localhost:3001/api/settings"
```

--------------------------------

### Get Effective Settings

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/reactive-resume.md

Retrieves the current effective settings, including resolved resume projects and the base resume ID.

```APIDOC
## GET /api/settings

### Description
Retrieves the current effective settings, including resolved resume projects and the base resume ID.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
- **rxresumeBaseResumeId** (string) - The ID of the base resume.
- **resumeProjects** (object) - Controls for resume projects.
  - **maxProjects** (integer) - The maximum number of projects allowed.
  - **lockedProjectIds** (array of strings) - IDs of projects that are locked.
  - **aiSelectableProjectIds** (array of strings) - IDs of projects selectable by AI.
```

--------------------------------

### Example Visa Sponsor Provider Manifest

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/workflows/add-a-visa-sponsor-provider.md

This manifest defines the country-specific logic for fetching and parsing visa sponsor data. It includes the provider's ID, display name, country key, and an asynchronous function to fetch sponsor information. Ensure the `fetchSponsors` function returns an array of `VisaSponsor` objects or throws an error on failure.

```typescript
import type {
  VisaSponsor,
  VisaSponsorProviderManifest,
} from "../../shared/src/types/visa-sponsors";

export const manifest: VisaSponsorProviderManifest = {
  id: "au",
  displayName: "Australia",
  countryKey: "australia",
  scheduledUpdateHour: 3,

  async fetchSponsors(): Promise<VisaSponsor[]> {
    // Fetch and parse the upstream register here.
    // Return an array of VisaSponsor objects.
    // Throw on failure — the service layer handles error state.
    return [];
  },
};

export default manifest;

```

--------------------------------

### Example Catalog Update for Visa Sponsor Providers

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/workflows/add-a-visa-sponsor-provider.md

This snippet shows how to update the shared catalog in `shared/src/visa-sponsor-providers/index.ts` to include a new provider. It involves adding the provider's ID to `VISA_SPONSOR_PROVIDER_IDS` and providing metadata like a user-friendly label and country key in `VISA_SPONSOR_PROVIDER_METADATA`.

```typescript
export const VISA_SPONSOR_PROVIDER_IDS = ["uk", "au"] as const;

export const VISA_SPONSOR_PROVIDER_METADATA = {
  uk: { label: "United Kingdom", countryKey: "united kingdom" },
  au: { label: "Australia", countryKey: "australia" },
};

```

--------------------------------

### Build Documentation

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/README.md

Execute this command to build the documentation. The output will be placed in the 'docs-site/build' directory.

```bash
npm run docs:build
```

--------------------------------

### Initialize Database

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Migrate the database schema to set up the necessary tables and structures for the application.

```bash
npm run db:migrate
```

--------------------------------

### Build for Production

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Compile the application for production deployment.

```bash
npm run build
npm start
```

--------------------------------

### Build Docs Site

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/troubleshooting/common-problems.md

Run this command to build the documentation site for the job-ops project. Ensure this build artifact is included in your production container.

```bash
npm --workspace docs-site run build
```

--------------------------------

### Get Job Chat Messages

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/ghostwriter.md

Retrieves the chat messages for a specific job.

```APIDOC
## GET /api/jobs/:id/chat/messages

### Description
Retrieves the chat messages for a specific job.

### Method
GET

### Endpoint
/api/jobs/:id/chat/messages

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the job.

### Response
#### Success Response (200)
- **messages** (array) - A list of chat messages.
```

--------------------------------

### Create a Manual Backup

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/getting-started/database-backups.md

Trigger the creation of a manual database backup using the API.

```bash
# Create a manual backup
curl -X POST "http://localhost:3001/api/backups"
```

--------------------------------

### Get Pipeline Status API

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Retrieve the current status of the job application pipeline.

```http
GET /api/pipeline/status
```

--------------------------------

### Get Recent Pipeline Runs API

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Fetch a list of recent pipeline execution runs.

```http
GET /api/pipeline/runs
```

--------------------------------

### Get Single Job API

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Retrieve details for a specific job using its unique identifier.

```http
GET /api/jobs/:id
```

--------------------------------

### Get Effective Settings

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/settings.md

Retrieves the current effective settings, which include defaults and any applied overrides.

```APIDOC
## GET /api/settings

### Description
Retrieves the current effective settings, which include defaults and any applied overrides.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
- **settings** (object) - The effective settings configuration.
```

--------------------------------

### Get Provider Status

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/visa-sponsors.md

This cURL command retrieves the current status of all registered visa sponsor providers.

```bash
# Get status of all registered providers
curl "http://localhost:3001/api/visa-sponsors/status"
```

--------------------------------

### Build Orchestrator Client

Source: https://github.com/dakheera47/job-ops/blob/main/AGENTS.md

Compile the client-side code for the orchestrator.

```bash
npm --workspace orchestrator run build:client
```

--------------------------------

### Initiate Gmail OAuth Flow API

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/README.md

Start the OAuth 2.0 authorization process for connecting a Gmail account.

```http
GET /api/post-application/providers/gmail/oauth/start
```

--------------------------------

### List Available Reactive Resume Resumes

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/reactive-resume.md

Fetches a list of all available resumes from the Reactive Resume instance.

```APIDOC
## GET /api/settings/rx-resumes

### Description
Fetches a list of all available resumes from the Reactive Resume instance.

### Method
GET

### Endpoint
/api/settings/rx-resumes

### Response
#### Success Response (200)
- **resumes** (array of objects) - A list of available resumes.
  - **id** (string) - The unique identifier for the resume.
  - **name** (string) - The name of the resume.
```

--------------------------------

### Get Effective Settings

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/settings.md

Retrieves the current effective settings, combining defaults and overrides. Useful for verifying configuration.

```bash
# Get effective settings (defaults + overrides)
curl "http://localhost:3001/api/settings"
```

--------------------------------

### Create Manual Backup

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/getting-started/database-backups.md

Manually triggers the creation of a new database backup.

```APIDOC
## POST /api/backups

### Description
Manually triggers the creation of a new database backup. This operation is restricted to system admins.

### Method
POST

### Endpoint
/api/backups

### Troubleshooting
- Confirm the data directory and `jobs.db` are writable/readable.
- Confirm `jobs.db` exists.
- In demo mode, manual backup creation is blocked.
```

--------------------------------

### Get Organization Sponsor Entries

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/visa-sponsors.md

Retrieve all licensed route entries for a specific organization using its name. Ensure the organization name is URL-encoded.

```bash
# Get one organization's entries (all licensed routes)
curl "http://localhost:3001/api/visa-sponsors/organization/Monzo%20Bank%20Ltd"
```

--------------------------------

### Configure Optional Hosted Capabilities

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/getting-started/self-hosting.md

Set these optional flags to enable or disable specific capabilities within hosted mode, such as signups, platform LLM, and quotas.

```bash
JOBOPS_HOSTED_SIGNUPS_ENABLED=false
JOBOPS_HOSTED_PLATFORM_LLM_ENABLED=false
JOBOPS_HOSTED_QUOTAS_ENABLED=false
```

--------------------------------

### Manual Stage Transition API

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/workflows/post-application-workflow.md

Use this API to manually transition a job to a new stage. Specify the target stage and provide metadata about the update event.

```bash
curl -X POST "http://localhost:3001/api/jobs/<jobId>/stages" \
  -H "content-type: application/json" \
  -d '{
    "toStage": "technical_interview",
    "metadata": {
      "actor": "user",
      "eventType": "status_update",
      "eventLabel": "Moved to Technical Interview"
    }
  }'
```

--------------------------------

### List Available Reactive Resume Resumes

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/reactive-resume.md

Fetch a list of all available resumes from your Reactive Resume instance. This is useful for populating dropdowns or selection interfaces.

```bash
# List available Reactive Resume resumes
curl "http://localhost:3001/api/settings/rx-resumes"
```

--------------------------------

### List Backups and Next Scheduled Run Time

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/getting-started/database-backups.md

Use this command to list all available backups and view the scheduled time for the next automatic backup.

```bash
# List backups + next scheduled run time
curl "http://localhost:3001/api/backups"
```

--------------------------------

### Initialize Job Ops Orchestrator

Source: https://github.com/dakheera47/job-ops/blob/main/orchestrator/index.html

Initializes the Job Ops orchestrator with API URL, client ID, and tracking options. This setup is crucial for enabling all tracking features.

```javascript
window.op = window.op || (() => {
  const queue = [];
  const track = (...args) => {
    if (args.length > 0) {
      queue.push(args);
    }
  };
  return new Proxy(track, {
    get: (_target, property) => {
      if (property === "q") {
        return queue;
      }
      return (...args) => {
        queue.push([property, ...args]);
      };
    },
    has: (_target, property) => property === "q",
  });
})();
```

```javascript
window.op("init", {
  apiUrl: "https://openpanel.dakheera47.com/api",
  clientId: "6a953241-309b-4e5a-be1b-412c5d7b6544",
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});
```

--------------------------------

### Manage Backups

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/settings.md

Lists existing backups and creates a new backup. This is used for managing data backups within the system.

```bash
# List and create backups (used by the Backup section)
curl "http://localhost:3001/api/backups"
curl -X POST "http://localhost:3001/api/backups"
```

--------------------------------

### Set API Token for Apify

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/extractors/seek.md

Add your Apify API token to your .env file to enable the Seek source in your pipeline. Ensure the token is valid and the application is restarted after setting it.

```bash
APIFY_TOKEN=apify_api_xxxxxxxxxxxx
```

--------------------------------

### Run Biome CI Check

Source: https://github.com/dakheera47/job-ops/blob/main/AGENTS.md

Execute Biome's CI check from the repository root to ensure code quality and consistency.

```bash
./orchestrator/node_modules/.bin/biome ci .
```

--------------------------------

### Cut a Docs Version

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/README.md

Use this command to create a new documentation version corresponding to a specific release tag. Replace '1.0.0' with your desired version number.

```bash
npm run docs:version -- 1.0.0
```

--------------------------------

### Enable Hosted Mode in JobOps

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/getting-started/self-hosting.md

Configure JobOps to run in hosted mode by setting the JOBOPS_APP_MODE and JOBOPS_HOSTED_TENANT_ID environment variables. Hosted mode requires a pre-existing tenant ID.

```bash
JOBOPS_APP_MODE=hosted
JOBOPS_HOSTED_TENANT_ID=tenant_hosted
```

--------------------------------

### Save Base Resume and Project Controls

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/reactive-resume.md

Update the base resume ID and project control settings. This includes maximum projects, locked project IDs, and AI-selectable project IDs.

```bash
# Save base resume and project controls
curl -X PATCH "http://localhost:3001/api/settings" \
  -H "content-type: application/json" \
  -d '{
    "rxresumeBaseResumeId": "resume_id_here",
    "resumeProjects": {
      "maxProjects": 4,
      "lockedProjectIds": ["proj_a"],
      "aiSelectableProjectIds": ["proj_b","proj_c","proj_d"]
    }
  }'
```

--------------------------------

### Fetch Camoufox Assets

Source: https://github.com/dakheera47/job-ops/blob/main/extractors/ukvisajobs/README.md

Fetches missing Camoufox assets if required.

```bash
npx camoufox-js fetch
```

--------------------------------

### Rebuild better-sqlite3 Native Module

Source: https://github.com/dakheera47/job-ops/blob/main/AGENTS.md

Rebuild the 'better-sqlite3' native module for the orchestrator workspace to resolve Node ABI mismatches.

```bash
npm --workspace orchestrator rebuild better-sqlite3
```

--------------------------------

### Trigger Manual Refresh for All Providers

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/visa-sponsors.md

Use this POST request to manually trigger an immediate refresh of all visa sponsor providers.

```bash
# Trigger manual refresh for all providers
curl -X POST http://localhost:3001/api/visa-sponsors/update
```

--------------------------------

### Configure Gmail OAuth Credentials

Source: https://github.com/dakheera47/job-ops/blob/main/docs-site/docs/features/post-application-tracking.md

Set these environment variables to configure Gmail OAuth. Ensure the redirect URI matches your application's callback endpoint.

```bash
GMAIL_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_OAUTH_CLIENT_SECRET=your-client-secret
GMAIL_OAUTH_REDIRECT_URI=https://your-domain.com/oauth/gmail/callback
```