trackly-cli

[![npm](https://img.shields.io/npm/v/trackly-cli.svg)](https://www.npmjs.com/package/trackly-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node 20+](https://img.shields.io/badge/node-20+-brightgreen.svg)](https://nodejs.org/)
[![MCP Server](https://img.shields.io/badge/MCP-Server-blue.svg)](https://modelcontextprotocol.io/)

# trackly-cli

The only job tracking CLI built for AI agents.

Search 128,000+ jobs across 1,900+ companies and 40+ ATS types. Track applications, get AI-powered recommendations, and manage your job search -- from the terminal or through Claude, ChatGPT, Cursor, and other MCP-compatible AI agents.

## Two ways to connect

### 🚀 Option 1: One-click in Claude co-work, Claude Desktop, ChatGPT (no install)

Use Trackly directly inside your AI — zero config:

1. Open Settings → Connectors → **Add custom connector**
2. URL: `https://mcp.usetrackly.app/api/mcp`
3. Click **Add** → sign in with Google → done

**[Full setup guide with screenshots →](https://usetrackly.app/connector)**

Works in: Claude co-work (web), Claude Desktop, ChatGPT Connectors, and any MCP client that supports remote/streamable-http connectors.

### 💻 Option 2: CLI install (for Cursor, Windsurf, or terminal use)

```bash
npm install -g trackly-cli    # may need: sudo npm install -g trackly-cli
trackly login
trackly jobs --function product
```

> **Prerequisites:** [Node.js 20+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.

## At a Glance

1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 36 local MCP tools

## CLI Commands

```bash
trackly jobs                          # List jobs
trackly jobs --remote                 # Filter remote jobs (sets usStates=REMOTE)
trackly jobs --region us              # Filter by region (us, non_us, all, or a region tag: europe, canada, remote, ...)
trackly jobs --job-type internship    # Filter by employment type (full_time, internship, all)
trackly jobs --work-arrangement hybrid,remote  # Filter by work arrangement independently
trackly jobs --function product       # Filter by function
trackly jobs --company 243            # Filter by company ID
trackly job 1234                      # Get job details
trackly jobs 1234                     # Alias for job details
trackly companies                     # List companies
trackly companies search "fintech"    # Semantic company search
trackly search "fintech"              # Alias for semantic company search
trackly stats                         # Show metrics
trackly status                        # Alias for stats
trackly preferences                   # Show discovery preferences and experience limits
trackly preferences experience product=2 strategy=5  # Replace role-specific limits
trackly preferences experience clear # Turn role-specific experience filtering off
trackly apply 1234                    # Mark as applied
trackly save 1234                     # Save a job
trackly dismiss 1234                  # Dismiss a job
trackly ask "PM jobs in SF"           # Natural language search (20/day)
trackly contacts "Stripe"             # Search contacts at a company
trackly brief 1234                    # Get network brief for a job
trackly referral start 1234           # Start a referral campaign
trackly referral status 1234          # Check referral campaign status
trackly company-brief 243             # Get company brief (--refresh to regenerate)
trackly company-workspace 243         # Full company workspace view
trackly request-company "eBay"        # Request a company be added (--url, --notes optional)
trackly api-key create                # Generate API key
trackly api-key list                  # List API keys
trackly config                        # Show current CLI config
trackly config --api-key trk_xxx      # Save an API key for future commands
trackly version                       # Show installed version
trackly whoami                        # Show current user
trackly logout                        # Clear credentials
trackly agent setup --client both    # Install Trackly Apply for Codex + Claude Code
trackly agent doctor                 # Verify setup, profile, resume, and compatibility
```

Add `--json` to any command for JSON output. Use `--api-key <key>` or `--base-url <url>` as one-off global flags when needed.

`trackly preferences --json` returns only `success`, `experienceFilterV2Available`, and `preferences`. The availability flag controls whether this client may edit role-specific limits; it does not claim that feed or alert enforcement is active. Every update checks that flag and the latest preference revision before writing.

## MCP Server Setup

### Hosted (Claude co-work, Claude Desktop, ChatGPT)

No install. In your AI tool, open **Settings → Connectors → Add custom connector** and enter:

```text
https://mcp.usetrackly.app/api/mcp
```

Sign in with Google when prompted. [Full visual guide →](https://usetrackly.app/connector)

### Local (CLI via stdio, for Cursor / Windsurf / Claude Code)

For agent-assisted form filling on macOS, install the public skill and local MCP together:

```bash
trackly agent setup --client codex    # or claude / both
trackly agent doctor
```

The skill uses the profile and default resume in your Trackly account, asks only missing questions, fills user-approved saved jobs, and always stops before Submit. Support is fetched from Trackly at the start of every run: Greenhouse is full, Ashby and Lever are best effort, and 27 additional named ATS/provider classes use constrained guided mode. Employer-hosted unknown forms run only when Trackly binds them to a verified company domain. LinkedIn-hosted forms and unverified origins remain manual-only; a separately stored external application URL is evaluated under its own ATS and origin policy.

Guided mode is deliberately fail-closed. The agent stops on credential entry, OTP/email verification, CAPTCHA/human verification, an unexpected employer or origin, a submit-only transition, or any field whose committed state cannot be observed. `trackly agent doctor` checks the local skill, MCP registration, protocol compatibility, declared browser/computer-use configuration, profile completeness, and default-resume metadata. Live semantic browser capability and the exact resume bytes are verified at the start of a real run.

#### Claude Code one-liner

```bash
claude mcp add --scope user trackly -- trackly mcp
```

Or equivalently:

```bash
claude mcp add-json --scope user trackly '{"command":"trackly","args":["mcp"]}'
```

#### Claude Code manual config

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "trackly": {
      "command": "trackly",
      "args": ["mcp"]
    }
  }
}
```

#### Cursor / Windsurf

Add to `.cursor/mcp.json` or `~/.cursor/mcp.json` (same schema works for Windsurf):

```json
{
  "mcpServers": {
    "trackly": {
      "command": "trackly",
      "args": ["mcp"]
    }
  }
}
```

Then use natural language in any of these clients:

- "Find me PM jobs at fintech companies"
- "What remote engineering roles are available?"
- "Mark job 1234 as applied"

## MCP Tools Reference

| Tool | Description |
|------|-------------|
| trackly_search_jobs | Search and filter jobs by function, company, region, employment type, work arrangement, and status |
| trackly_get_job | Get full details for a specific job |
| trackly_search_companies | Semantic company search |
| trackly_list_companies | List all tracked companies |
| trackly_get_stats | Job tracker metrics and status counts |
| trackly_get_preferences | Read bounded discovery preferences, edit availability, and save revision |
| trackly_update_experience_limits | Atomically replace role-specific limits on a job's stated minimum years |
| trackly_update_status | Mark jobs as applied, saved, or dismissed |
| trackly_ask | Natural language job search (20/day) |
| trackly_get_job_brief | Get network brief for a job (company signal, top contact, actions) |
| trackly_contacts_at_company | Search contacts at a specific company |
| trackly_get_company_workspace | Full company workspace (jobs, contacts, hiring managers, campaigns) |
| trackly_request_company | Request a company be added to Trackly (rate-limited to 5 pending) |
| trackly_get_apply_queue | Get user-approved jobs ready for execution |
| trackly_get_application_profile | Get versioned profile answers and provenance |
| trackly_get_profile_onboarding | Get schema plus missing questions |
| trackly_update_application_profile | Save scoped answers with optimistic concurrency |
| trackly_create_apply_batch | Freeze an exact recent-first approved batch |
| trackly_get_active_apply_batch | Recover the newest unexpired active batch after context loss |
| trackly_get_apply_batch | Read frozen membership with opaque pagination |
| trackly_claim_apply_batch | Acquire or renew a batch mutation lease |
| trackly_checkpoint_apply_batch | Bulk-record redacted inspection checkpoints and human actions |
| trackly_bind_apply_surface | Bind an initial or recovered browser surface to the existing run and exact requisition URL |
| trackly_record_apply_surface_evidence | Record current-epoch inventory, missing-tab, close-receipt, and post-close absence evidence |
| trackly_record_apply_submission_evidence | Record redacted submit-request, success-page, user-confirmation, or provider-receipt evidence |
| trackly_approve_apply_batch_resume | Approve one exact default resume for the current frozen run set |
| trackly_certify_apply_batch_truth | Certify final answer and wording fingerprints after every other review-readiness gate |
| trackly_start_apply_run | Start or reuse a manual-submit browser run |
| trackly_get_apply_evidence | Get aggregate, value-free beta evidence and release readiness |
| trackly_get_apply_protocol | Get current workflow and compatibility rules |
| trackly_report_apply_observa