scoutica jobs

jobs is the discovery side of the network. It searches a Scoutica registry index — a public list of published candidate cards or open roles — and filters it by skills and seniority. It is read-only: nothing is written, no card is fetched in full, and no personal data leaves your machine.

Command Syntax

scoutica jobs search [options]

Running scoutica jobs with no subcommand (or an unknown one) prints the built-in help for the command.

`scoutica jobs search`

Fetches a registry index and filters its entries client-side.

Options

Option	Behavior
`--type <candidates\|roles>`	What to search for. Defaults to `candidates`.
`--skills <list>`	Comma-separated skills to filter on. An entry matches if any listed skill is present (case-insensitive). For candidates this matches the card’s `skills`; for roles it matches the role’s `hard_skills`.
`--seniority <level>`	Keep only entries whose seniority matches exactly (case-insensitive), e.g. `senior`, `staff`.
`--registry <url>`	HTTPS base URL of the registry to query. Defaults to the public Scoutica registry on GitHub. Redirects and non-public destinations are refused.
`--local <path>`	Read a bounded local `index.json` instead of the network. The registry URL is never contacted; a missing or invalid file fails.
`--json`	Emit results as JSON (`{ "results": [...], "count": N }`) instead of the formatted list.

How the index is resolved

Local index (if provided)

The local file is limited to 2 MiB and must be UTF-8 JSON with an object root and an entries list of objects. Missing or invalid input fails without any network request.

Remote registry

Otherwise the CLI fetches <registry>/<type>/index.json through one pinned HTTPS boundary: public DNS answers only, no credentials, no proxy, no redirects, 10-second connect timeout, 30-second total timeout, and a 2 MiB response limit.

Bundled examples (fallback)

A plain transport failure or an absent (404) registry index may use example cards bundled under protocol/examples/. URL/DNS policy, redirect, other HTTP status, content-type, UTF-8, size, and JSON-shape failures return nonzero and never fall back.

Output

By default the results are printed as a numbered, human-readable list.

For a candidate search, each entry shows the name, title, seniority, availability, up to six skills, and the card location:

  Found 1 candidates:

  1. Alice Developer — Senior Backend Engineer
     Seniority: senior | Availability: 2_weeks
     Skills: Python, Go, PostgreSQL, Kubernetes, gRPC, Terraform
     Card: https://example.com/cards/alice-developer

For a roles search, each entry shows the title and status, up to six hard skills, the compensation range, and the location type:

  Found 1 roles:

  1. Senior Platform Engineer [open]
     Skills: Python, Kubernetes, Terraform, AWS, Go
     Compensation: 90000-120000 EUR | Location: remote
     Role: https://example.com/roles/senior-platform-engineer

JSON output

With --json, stdout is exactly one machine-readable object with no ANSI/header text. Warnings go to stderr; failures return nonzero with empty stdout.

{
  "results": [
    {
      "name": "Alice Developer",
      "title": "Senior Backend Engineer",
      "seniority": "senior",
      "skills": ["Python", "Go", "PostgreSQL"],
      "availability": "2_weeks",
      "card_url": "https://example.com/cards/alice-developer"
    }
  ],
  "count": 1
}

The exact fields per entry come straight from the registry index; role entries carry title, hard_skills, seniority, compensation_range, location, status, and role_url instead.

Examples

# Find senior candidates who list Python
scoutica jobs search --skills "Python" --seniority senior

# Search open roles instead of candidates
scoutica jobs search --type roles --skills "Kubernetes,Terraform"

# Query a self-hosted registry
scoutica jobs search --registry https://registry.example.com/scoutica

# Search a local index and emit JSON for scripting
scoutica jobs search --local ./registry/candidates/index.json --json