Trackly CLI

[npm] [License: MIT] [Node 20.20+ or 22.22+] [MCP Server]

trackly-cli

The only job tracking CLI built for AI agents.

Search 250K+ jobs across 5,400+ 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 →

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)

npm install -g trackly-cli    # may need: sudo npm install -g trackly-clitrackly logintrackly jobs --function product

Prerequisites: Node.js 20.20+ or 22.22+ (LTS recommended). On macOS with the official .pkg installer, global npm installs may require sudo.

At a Glance

5,400+ companies | 250K+ jobs | 40+ ATS types | CLI + MCP | 58 local + 55 hosted MCP tools

CLI Commands

trackly jobs                          # List jobstrackly 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 independentlytrackly jobs --function product       # Filter by functiontrackly jobs --sponsorship exclude_no # Visa sponsorship filter (all, exclude_no, only_yes)trackly jobs --company 243            # Filter by company IDtrackly job 1234                      # Get job detailstrackly jobs 1234                     # Alias for job detailstrackly companies                     # List companiestrackly companies search "fintech"    # Semantic company searchtrackly search "fintech"              # Alias for semantic company searchtrackly stats                         # Show metricstrackly status                        # Alias for statstrackly preferences                   # Show discovery preferences and experience limitstrackly preferences experience product=2 strategy=5  # Replace role-specific limitstrackly preferences experience clear # Turn role-specific experience filtering offtrackly apply 1234                    # Mark as appliedtrackly save 1234                     # Save a jobtrackly dismiss 1234                  # Dismiss a jobtrackly ask "PM jobs in SF"           # Natural language search (20/day)trackly contacts "Stripe"             # Search contacts at a companytrackly brief 1234                    # Get network brief for a jobtrackly referral start 1234           # Start a referral campaigntrackly referral status 1234          # Check referral campaign statustrackly company-brief 243             # Get company brief (--refresh to regenerate)trackly company-workspace 243         # Full company workspace viewtrackly request-company "eBay"        # Request a company be added (--url, --notes optional)trackly api-key create                # Generate API keytrackly api-key list                  # List API keystrackly config                        # Show current CLI configtrackly config --api-key trk_xxx      # Save an API key for future commandstrackly version                       # Show installed versiontrackly whoami                        # Show current usertrackly logout                        # Clear credentialstrackly agent setup --client both    # Install Trackly Apply for Codex + Claude Codetrackly agent doctor                 # Verify setup, profile, resume, and compatibilitytrackly agent diagnose-path /path/to/upload.pdf --errno ENOSPC --json  # Diagnose one exact local path

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:

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

Sign in with Google when prompted. Full visual guide →

Claude Code can use the same hosted server over OAuth:

claude mcp add --transport http trackly https://mcp.usetrackly.app/api/mcp

OAuth sign-in is the default for every client. An API key is optional and only needed for headless clients that cannot complete an interactive sign-in: send Authorization: Bearer trk_... with a key from Settings → API Keys.

Remote connections get 55 hosted tools. They share the search, company, status, and Apply tools with the local server and add trackly_chat; the 4 local-only tools listed below are not available remotely. Hosted setup and tool details are at 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:

trackly agent setup --client codex    # or claude / bothtrackly agent doctor

For an existing MCP configuration or a Cloud harness, use trackly agent setup --client both --skills-only. This installs the same checksummed skill for both native clients without invoking their MCP commands or changing authentication. CLI 0.20.1 carries universal skill 4.9.1; its policy revision is the same numeric version, superseding the personal revisions. The policy accepts a documented markHandoff() guarantee with awaited calls, exact current tab checks, and revalidation on later turns. These observations are never reported as returned persistence receipts. Browser capabilities and manual Submit remain separate requirements; installation does not make a Linux browser supported. The separately installed trackly:trackly-apply plugin is updated through its plugin manager; plugin 1.1.1 carries the same browser and profile lookup policies. This setup command does not patch plugin caches.

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. “Fill the next N” continues through the original recent-first Check Later snapshot until N unauthenticated forms are durably ready for your manual review; authentication walls and exclusions are reported separately and do not consume the target. An explicit “inspect the next N records” request still uses one fixed immutable batch. 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

claude mcp add --scope user trackly -- trackly mcp

Or equivalently:

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

Claude Code manual config

Add to a project-scoped .mcp.json:

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

Cursor / Windsurf

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

{  "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"

Search filters and updates

trackly_search_jobs supports multiple roles and regions, US states and Canadian provinces, internship education levels, favorite companies, posting windows, annual USD salary floors, incremental sync, work arrangement, sponsorship and pipeline status. Exact values and examples. Search returns 20 jobs by default; request up to 100 and use offset to page.

For sponsorship, “exclude no” keeps yes and not mentioned. Use exclude_no; only_yes excludes jobs with unknown sponsorship. Ask the user when intent is ambiguous. Salary floors also keep unknown and non-comparable salaries visible. Unsupported industry/specialization/literal-search controls are rejected.

For a local server without a global package install, run npx -y trackly-cli mcp. For Codex, use codex mcp add trackly -- npx -y trackly-cli mcp; Cursor and Windsurf can use "command": "npx", "args": ["-y", "trackly-cli", "mcp"]. Authenticate with npx -y trackly-cli login first, or configure TRACKLY_API_KEY.

Existing global installs require npm install --global trackly-cli@latest. Restart the MCP process/client and refresh tool discovery after updating. For native skills and marketplace plugin updates, follow the release and update guide. Hosted and local releases are separate: the current client schema is authoritative.

MCP Tools Reference

The local stdio server (trackly mcp) registers the 58 tools below. Four are local-only because they run their checks on your machine: trackly_diagnose_local_path, trackly_lint_application_text, trackly_validate_apply_resume_upload, and trackly_validate_apply_tab_keep_set. The hosted server omits those four and adds trackly_chat, for 55 hosted tools.

Authentication

Option 1: Google OAuth (recommended)

trackly login

Opens your browser for Google sign-in. Tokens are stored locally at ~/.trackly/config.json.

Trackly is currently opening new memberships through a limited, invite-based rollout. Existing members can keep using OAuth and API keys normally. If a new account is not yet eligible, the CLI returns an invitation-specific message instead of suggesting repeated login attempts; request a future seat at usetrackly.app/early-access.

Option 2: API Key

Existing members can use an API key for firewalls, headless servers, or CI:

1. Sign in at usetrackly.app
2. Go to Settings → API Keys → Create
3. Save the key:

trackly config --api-key trk_xxxxxxxxxxxxxxxxxxxx

Or pass it per-command:

trackly --api-key trk_xxxxxxxxxxxxxxxxxxxx jobs --json

Or set it as an environment variable:

export TRACKLY_API_KEY=trk_xxxxxxxxxxxxxxxxxxxxtrackly jobs

Generate a key from the CLI

If you're already logged in via OAuth, you can create a key without visiting the web app:

trackly api-key create --name "my-script"trackly api-key list

Other config

trackly config --clear-api-key           # Clear stored API keytrackly config --base-url http://127.0.0.1:3000  # Point at a different backend

Comparison

Web: usetrackly.app | API docs: usetrackly.app/developers

Frequently Asked Questions

How do I track job applications from the terminal?

Install trackly-cli (npm install -g trackly-cli), authenticate with trackly login or configure an API key, then use trackly jobs to browse openings and trackly apply <id> to mark applications. All data syncs with the Trackly web app at usetrackly.app.

What MCP servers exist for job searching?

trackly-cli includes a built-in MCP server with 58 tools: the complete Trackly job-search and application set plus get_more_tools, which lets agents report a missing capability. Run trackly mcp or use trackly agent setup --client claude.

MCP usage analytics are part of the free Trackly service and relay through Trackly so it can be debugged and improved; there is no account-level opt-out. They exclude résumé text, profile answers, demographic or work-authorization answers, and application notes. Client attribution uses a fixed family label; errors use categories, and search text is retained only as length. Raw queries and conversation text are excluded.

How do I use Claude Code for job hunting?

Add trackly as an MCP server in Claude Code. Then ask questions naturally: "Find PM jobs at fintech companies in SF", "What companies are hiring for engineering?", or "Mark job 1234 as applied." Claude will use trackly's MCP tools to search and manage your applications.

What are the best CLI tools for job search?

trackly-cli is the first dedicated job tracking CLI. It provides direct terminal access to 250K+ jobs across 5,400+ companies, with filters for job function, location, and work modality. It also integrates with AI agents via the Model Context Protocol (MCP).

Security

• OAuth tokens stored in ~/.trackly/config.json with 0600 permissions
• API keys can be stored in the same config file or passed per-command
• OAuth callback bound to 127.0.0.1 only
• Authenticated requests require HTTPS unless you are pointing at localhost
• HTTP requests time out instead of hanging indefinitely
• CSRF protection on login flow
• See SECURITY.md for vulnerability reporting

License

MIT -- see LICENSE