⚙️ it-pracuj-cli

Terminal access to Poland's largest IT job board — JSON output, smart filters, and AI agent support.

Installation • Quick Start • Commands • MCP Integration

👋 Hello there!

it-pracuj-pl gives you fast, scriptable access to it.pracuj.pl — Poland's largest IT job board — directly from your terminal. Search job offers, compare technology demand, explore available filters, and sync data locally for offline use.

The tool ships two binaries: it-pracuj-pl (the CLI) and it-pracuj-pp-mcp (a Model Context Protocol server for use with Claude Desktop and other MCP-compatible AI agents).

✨ Features

📊 Market Intelligence

📈 filters — Show available filters and live offer counts for any keyword — work modes, position levels, contract types, IT specializations
⚖️ compare — Compare job offer counts for multiple technologies side-by-side; runs all queries in parallel

🔌 Full API Access

📋 job-offers — List, count, and group IT job offers with rich filtering (keyword, work mode, employment type, tech category, position level, salary range)
🏢 companies — Fetch company profile metadata by ID
🌟 recommended-job-offers — Retrieve recommended job offers grouped by category
📦 subservices — Get total job counts across all categories (IT, engineering, sales, blue-collar)

🗄️ Local Data & Offline Use

🔄 sync — Pull live API data into a local SQLite store with FTS5 full-text search
🔍 search — Full-text search across synced local data — works without network
📥 import — Import data from a file into the local store

🤖 AI Agent Integration

🧩 MCP server — Exposes all API operations as MCP tools for Claude Desktop and compatible agents
⚡ Agent mode — --agent flag enables JSON + compact + non-interactive output in one flag
📡 agent-context — Prints a machine-readable JSON description of all capabilities for AI agents
🔎 which — Natural language capability resolver (which "find remote react jobs")

🛠️ Developer Experience

📤 Output delivery — Route output to stdout (default), file:<path>, or webhook:<url>
💾 Named profiles — Save and reuse flag combinations with profile save / profile apply
📝 Multiple formats — JSON, CSV, plain tab-separated, or human-friendly table
🏥 doctor — Health check that verifies configuration and API connectivity
🌐 Browser-compatible transport — Chrome-like HTTP headers handle Cloudflare-protected endpoints automatically

📦 Installation

Pre-built binaries (recommended)

Download the latest binary for your platform from the Releases page.

Platform	Archive
macOS Apple Silicon	`it-pracuj-pl_darwin_arm64.tar.gz`
macOS Intel	`it-pracuj-pl_darwin_amd64.tar.gz`
Linux amd64	`it-pracuj-pl_linux_amd64.tar.gz`
Linux arm64	`it-pracuj-pl_linux_arm64.tar.gz`
Windows amd64	`it-pracuj-pl_windows_amd64.zip`
Windows arm64	`it-pracuj-pl_windows_arm64.zip`

On macOS, clear the Gatekeeper quarantine after download:

xattr -d com.apple.quarantine it-pracuj-pl
chmod +x it-pracuj-pl

Homebrew (macOS / Linux)

brew install JanSzewczyk/homebrew-tap/it-pracuj-pl

go install

Requires Go 1.22+:

go install github.com/JanSzewczyk/it-pracuj-cli/cmd/it-pracuj-pl@latest

Build from source

git clone https://github.com/JanSzewczyk/it-pracuj-cli.git
cd it-pracuj-cli
make build
# Binary at bin/it-pracuj-pl

🚀 Quick Start

# Health check — verify API connectivity
it-pracuj-pl doctor

# Total job offer counts across all categories
it-pracuj-pl subservices

# Count offers for a keyword
it-pracuj-pl job-offers list-count --keyword "backend developer"

# List remote React job offers as JSON
it-pracuj-pl job-offers list-offers --keyword react --work-mode home-office --json

# Show available filters for a technology
it-pracuj-pl filters golang

# Compare demand across technologies
it-pracuj-pl compare react vue angular --sort

⚙️ Commands

📋 Job Offers

Command	Description
`job-offers list-count`	Count job offers matching search criteria
`job-offers list-grouped`	Get grouped counts by filter category (work mode, position level, contract type, IT specialization)
`job-offers list-offers`	List job offers — scrapes `it.pracuj.pl` and returns structured offer data

list-offers filters:

Flag	Description
`--keyword <kw>`	Search keyword (required)
`--city <name>`	City name, e.g. `warszawa`, `kraków`
`--radius <km>`	Search radius in km from city
`--work-mode <modes>`	Comma-separated: `full-office`, `hybrid`, `home-office`, `mobile`
`--it-spec <spec>`	IT specialization: `frontend`, `backend`, `fullstack`, `devops`, `mobile`, `data-analytics-and-bi`, `ai-ml`, and 14 more
`--it-tech <ids>`	Technology IDs, comma-separated (e.g. `76,33,42` = React, JavaScript, TypeScript). See full list
`--position-level <codes>`	`17`=Junior, `4`=Mid, `18`=Senior, `19`=Expert, `5`=Manager
`--contract-type <codes>`	`0`=UoP, `3`=B2B, `2`=zlecenie, `1`=o dzieło
`--with-salary`	Only offers with disclosed salary range
`--no-agency`	Direct employer offers only
`--posted-within <days>`	`1`, `3`, `7`, `14`, or `30` days

See docs/filters.md for the complete filter and technology ID reference.

📊 Market Intelligence

Command	Description
`filters <keyword>`	Show live offer counts for all available filters — work modes, position levels, contract types, IT specializations
`compare <kw1> [kw2...]`	Compare job offer counts for multiple keywords side-by-side (parallel queries)

compare flags:

Flag	Description
`--sort`	Sort results by offer count (descending)
`--subservice <n>`	Limit to a specific job category (default: IT)

🏢 Companies & Categories

Command	Description
`companies --ids <ids>`	Get company profile metadata by ID (comma-separated)
`subservices`	Get total job counts across all categories (IT, engineering, sales, blue-collar)
`recommended-job-offers`	Get recommended job offers grouped by category

🗄️ Data Management

Command	Description
`sync`	Pull live API data into the local SQLite store
`search <query>`	Full-text search across synced local data
`import <file>`	Import data from a file into the local store

🤖 Agent & Utility

Command	Description
`agent-context`	Print machine-readable JSON description of all capabilities
`which <description>`	Natural language capability resolver
`doctor`	Verify configuration and API connectivity
`profile`	Manage named flag profiles (`save`, `apply`, `list`, `delete`)
`feedback`	Submit feedback (stored locally by default)
`version`	Print version

Run it-pracuj-pl --help or it-pracuj-pl <command> --help for the complete flag reference.

🎛️ Global Flags

These flags work on every command:

Flag	Default	Description
`--json`	`false`	Output as JSON
`--compact`	`false`	Return only key fields (reduces token usage for agents)
`--csv`	`false`	Output as CSV
`--plain`	`false`	Output as plain tab-separated text
`--quiet`	`false`	Bare output, one value per line
`--agent`	`false`	Set all agent-friendly defaults (`--json --compact --no-input --no-color --yes`)
`--dry-run`	`false`	Show request details without sending
`--no-cache`	`false`	Bypass response cache
`--data-source`	`auto`	Data source: `auto` (live + local fallback), `live` (API only), `local` (synced only)
`--select <fields>`	—	Comma-separated fields to include in output (e.g. `--select id,name`)
`--deliver <sink>`	—	Route output: `stdout`, `file:<path>`, `webhook:<url>`
`--profile <name>`	—	Apply a saved named profile
`--rate-limit <n>`	`2`	Max requests per second (`0` to disable)
`--timeout <dur>`	`30s`	Request timeout
`--human-friendly`	`false`	Enable colored output and rich formatting
`--no-color`	`false`	Disable colored output
`--no-input`	`false`	Disable all interactive prompts (for CI and agents)
`--yes`	`false`	Skip confirmation prompts

Exit codes: 0 success · 2 usage error · 3 not found · 5 API error · 7 rate limited · 10 config error

🔧 Configuration

Config file: ~/.config/it-pracuj-pl/config.toml

[headers]
# Static request headers applied to every request.
# Per-command overrides take precedence.
# User-Agent = "my-scraper/1.0"

Path	Purpose
`~/.config/it-pracuj-pl/config.toml`	Static headers and global settings
`~/.cache/it-pracuj-pl/http/`	HTTP response cache (SHA256-keyed)
`~/.local/share/it-pracuj-pl/data.db`	Local SQLite store (FTS5)

🧩 MCP Integration

it-pracuj-cli ships an MCP server (it-pracuj-pp-mcp) that exposes all API operations as tools for Claude Desktop and other MCP-compatible AI agents.

Install the MCP binary

go install github.com/JanSzewczyk/it-pracuj-cli/cmd/it-pracuj-pp-mcp@latest

Or download the pre-built binary from the Releases page.

Configure Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "it-pracuj": {
      "command": "it-pracuj-pp-mcp"
    }
  }
}

Available MCP tools

Tool	Description
`job_offers_list_count`	Count job offers matching criteria
`job_offers_list_grouped`	Get grouped counts by filter category
`job_offers_list_offers`	List job offers with full filter support
`companies_list_metadata`	Get company profile metadata by ID
`subservices_list_counts`	Get job counts by service category
`recommendedJobOffers_list_grouped`	Get recommended job offers grouped by category

The MCP server also mirrors the full Cobra command tree at runtime — every user-facing CLI command becomes an additional MCP tool automatically.

💡 Examples

Compare technology demand

# Which backend language has the most IT job offers in Poland?
it-pracuj-pl compare go python java rust --sort --json

Find remote senior React jobs

it-pracuj-pl job-offers list-offers \
  --keyword react \
  --work-mode home-office \
  --position-level 18 \
  --contract-type 3 \
  --json

Export company data to a file

it-pracuj-pl companies --ids 42 --json --deliver file:company.json

Offline workflow — sync then search

# Pull all IT offers to local store
it-pracuj-pl sync

# Search locally (no network required)
it-pracuj-pl search "golang kubernetes" --data-source local --json

Agent-safe one-liner

# All agent-friendly flags in a single --agent shortcut
it-pracuj-pl job-offers list-count --keyword typescript --agent \
  | jq '.results.offersCount'

Saved profile for recurring checks

# Save a profile once
it-pracuj-pl profile save daily --json --compact --quiet

# Reuse it later
it-pracuj-pl job-offers list-count --keyword react --profile daily

📁 Project Structure

it-pracuj-cli/
├── cmd/
│   ├── it-pracuj-pl/        # CLI binary entry point
│   └── it-pracuj-pp-mcp/    # MCP server binary entry point
├── internal/
│   ├── cache/               # SHA256-keyed HTTP response cache
│   ├── cli/                 # All CLI commands (~25 files, Cobra)
│   ├── client/              # HTTP client — browser-compatible headers, retries, rate limiting
│   ├── cliutil/             # Shared utilities: concurrent fanout, adaptive rate limiter
│   ├── config/              # TOML config loader
│   ├── mcp/                 # MCP tool registration
│   │   └── cobratree/       # Reflects Cobra command tree → MCP tools at runtime
│   ├── scraper/             # Next.js __NEXT_DATA__ extraction + 270+ IT tech ID lookup
│   └── store/               # SQLite store — FTS5, WAL mode, schema versioning
├── docs/
│   └── filters.md           # Complete filter reference (343 IT technologies with IDs)
├── .golangci.yml            # Linter configuration
├── .goreleaser.yaml         # Cross-platform release automation (6 targets)
├── go.mod                   # Go module (github.com/JanSzewczyk/it-pracuj-cli)
├── Makefile                 # Build targets
└── spec.yaml                # API specification (captured from browser traffic)

Key Directories

cmd/ — Minimal entry points; all business logic lives in internal/
internal/cli/ — Cobra command tree; each file maps to one command or command group
internal/store/ — SQLite persistence with FTS5 full-text search, WAL mode, and schema version migrations
internal/scraper/ — Extracts structured offer data from it.pracuj.pl SSR HTML and maps 270+ IT technologies to their API IDs
internal/mcp/cobratree/ — Reflects the entire Cobra command tree into MCP tools at runtime — new CLI commands become MCP tools automatically

🤝 Contributing

Contributions are welcome!

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes using Conventional Commits
Run tests: go test ./...
Open a Pull Request

📜 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

🙏 Acknowledgments

CLI Printing Press — toolchain used to scaffold this CLI
Cobra — CLI framework
mark3labs/mcp-go — MCP server library for Go
enetx/surf — Browser-compatible HTTP client
modernc.org/sqlite — Pure-Go SQLite driver (no CGO required)

📧 Contact & Support

🐛 Open an issue
⭐ Star this repository

Made with ❤️ by JanSzewczyk

If this CLI helped you, please consider giving it a ⭐ on GitHub!

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
cmd		cmd
docs		docs
internal		internal
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
.printing-press.json		.printing-press.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
SKILL.md		SKILL.md
dogfood-results.json		dogfood-results.json
go.mod		go.mod
go.sum		go.sum
manifest.json		manifest.json
research.json		research.json
spec.yaml		spec.yaml
workflow-verify-report.json		workflow-verify-report.json

Folders and files

Latest commit

History

Repository files navigation

⚙️ it-pracuj-cli

👋 Hello there!

✨ Features

📊 Market Intelligence

🔌 Full API Access

🗄️ Local Data & Offline Use

🤖 AI Agent Integration

🛠️ Developer Experience

📖 Table of Contents

📦 Installation

Pre-built binaries (recommended)

Homebrew (macOS / Linux)

go install

Build from source

🚀 Quick Start

⚙️ Commands

📋 Job Offers

📊 Market Intelligence

🏢 Companies & Categories

🗄️ Data Management

🤖 Agent & Utility

🎛️ Global Flags

🔧 Configuration

🧩 MCP Integration

Install the MCP binary

Configure Claude Desktop

Available MCP tools

💡 Examples

Compare technology demand

Find remote senior React jobs

Export company data to a file

Offline workflow — sync then search

Agent-safe one-liner

Saved profile for recurring checks

📁 Project Structure

Key Directories

🤝 Contributing

📜 License

🙏 Acknowledgments

📧 Contact & Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages