npm package: @openjobs-ai/cli
Description: OpenJobs AI CLI — AI-powered talent intelligence from the command line
Author: OpenJobs AI
Latest version: 0.2.0

# OpenJobs CLI

AI-powered talent intelligence from the command line. Search candidates, jobs, and scholars. Grade resumes. Compare profiles. Unlock contacts.

Built on the [Mira API](https://platform.openjobs-ai.com/docs/api).

## Install

```bash
npm install -g @openjobs-ai/cli
```

Or run directly with npx:

```bash
npx @openjobs-ai/cli search people --skills Python
```

The installed command remains:

```bash
openjobs
```

## Setup

Get your API key from the [OpenJobs AI Dashboard](https://platform.openjobs-ai.com).

```bash
# Option 1: Environment variable (recommended)
export MIRA_KEY=mira_your_api_key

# Option 2: .env file in your project
echo "MIRA_KEY=mira_your_api_key" > .env

# Option 3: Pass directly
openjobs search people --skills Python --api-key mira_your_api_key
```

## Usage

### Search Candidates

```bash
openjobs search people --skills Python,AWS --country "United States"

openjobs search people \
  --title "Senior Engineer" \
  --company Google \
  --min-exp 60 \
  --city "San Francisco"
```

### Search Jobs

```bash
openjobs search jobs --title "Python Engineer" --country "United States" --type Full-time
```

### Search Scholars

```bash
openjobs search scholars --areas "Machine Learning","NLP" --h-index-min 20
```

### Look Up Profiles

```bash
openjobs lookup https://linkedin.com/in/janedoe

# Multiple profiles
openjobs lookup https://linkedin.com/in/janedoe https://linkedin.com/in/johnsmith

# From file
openjobs lookup --file urls.txt
```

### Grade Resume vs Job Description

```bash
openjobs grade \
  --cv "10 years Python backend, AWS certified" \
  --jd "Senior Python engineer with cloud experience"

# From files
openjobs grade --cv-file resume.txt --jd-file job.txt
```

### Bulk Grade

```bash
openjobs grade bulk \
  https://linkedin.com/in/alice \
  https://linkedin.com/in/bob \
  --jd-file job.txt
```

### Compare Candidates

```bash
openjobs compare \
  https://linkedin.com/in/alice \
  https://linkedin.com/in/bob \
  https://linkedin.com/in/carol
```

### Talent Analytics

```bash
openjobs stats --country "United States" --skills Python --group-by management_level
```

### Unlock Contacts

```bash
# Prompts for confirmation (consumes quota)
openjobs unlock https://linkedin.com/in/janedoe

# Skip confirmation
openjobs unlock https://linkedin.com/in/janedoe --yes
```

## Result References (`@N`)

Search results are automatically numbered. Use `@N` to reference them in subsequent commands:

```bash
openjobs search people --skills Rust --country Germany
# Results: @1 through @20

openjobs lookup @1 @5
openjobs grade bulk @1 @2 @3 --jd-file job.txt
openjobs compare @1 @3
openjobs unlock @1 --yes
```

## Output Formats

```bash
# Auto-detect: terminal → table, pipe → JSON
openjobs search people --skills Python
openjobs search people --skills Python | jq '.[0]'

# Explicit format
openjobs search people --skills Python --format json
openjobs search people --skills Python --format csv
openjobs search people --skills Python --format table

# Write to file
openjobs search people --skills Python --output results.csv

# Select fields
openjobs search people --skills Python --fields full_name,skills,address

# Quiet mode (no spinners, no extra output)
openjobs search people --skills Python --quiet --format json
```

## Configuration

```bash
openjobs config list               # Show all settings
openjobs config set default_format json
openjobs config get default_format
openjobs config reset              # Reset to defaults
```

Settings are stored in `~/.openjobs/config.json`.

## Release

Publishing is automated with GitHub Actions via [`.github/workflows/publish.yml`](.github/workflows/publish.yml).

```bash
npm version patch
git push origin main --follow-tags
```

This workflow:

- publishes automatically when a `v*` tag is pushed
- can also be started manually from the GitHub Actions tab
- keeps the package public with the `openjobs` binary name
- uses npm trusted publishing for tag-based releases
- supports manual `token` mode for diagnostics when a repository secret named `NPM_TOKEN` is configured

For manual runs:

- choose `trusted` to publish with npm trusted publishing
- choose `token` to publish with `NPM_TOKEN` for access debugging

## Commands

| Command | Description |
|---------|-------------|
| `search people` | Search for candidates with 30+ filters |
| `search jobs` | Search for job positions |
| `search scholars` | Search for academic scholars |
| `lookup` | Look up full LinkedIn profiles (1–50) |
| `grade` | Grade a resume against a job description |
| `grade bulk` | Bulk grade candidates (up to 20) |
| `compare` | Compare candidates side by side (2–10) |
| `stats` | Talent pool analytics and aggregations |
| `unlock` | Unlock contact information (consumes quota) |
| `config` | Manage CLI configuration |

## API Reference

This CLI wraps the [Mira API](https://platform.openjobs-ai.com/docs/api). See the full API documentation for details on available filters and response formats.

## License

MIT