CLI Tool

Nico provides a zero-dependency Python 3 command-line tool that any AI agent can use to search Nico’s job index and manage your applications.

Prerequisites

Python 3 (no additional packages needed)
A Nico API key

Setup

1. Get the CLI

The CLI is included in the nico-jobagent/nico-skills repository:

git clone https://github.com/nico-jobagent/nico-skills.git

The CLI script is at nico-skills/skills/nico-jobagent/scripts/nico_client.py.

2. Configure

Quick setup (recommended). Run the interactive setup.sh from the repository root:

cd nico-skills
./setup.sh

It prompts for your NICO_API_KEY (and, optionally, NICO_API_URL), detects installed AI agents (Claude Code, OpenClaw, Cursor, GitHub Copilot), symlinks the skill for each, and writes the environment variables to your shell profile. Open a new terminal (or source your profile) afterward so the variables take effect. Manual setup. If you’d rather configure it yourself, set the environment variables:

export NICO_API_KEY="your-api-key-here"
export NICO_API_URL="api.nico-jobagent.com"  # optional; https:// is added if you omit it

Variable	Required	Default	Description
`NICO_API_KEY`	Yes	—	Your API key for authentication
`NICO_API_URL`	No	`api.nico-jobagent.com`	Nico API base URL. The scheme is optional — `https://` is added if omitted.

Command groups

Commands come in two groups:

Group	Purpose
`posting`	Job posting search — discover openings in Nico’s index (read-only).
`application`	Job application management — your own tracked applications.

All commands print JSON to stdout. Run python3 nico_client.py --help for the full list.

posting — job posting search

posting search

Search Nico’s job postings index. Pass employer and city names — the CLI resolves them for you. --country is required. Results are compact (no url or description — use posting get for those) and paged.

# In a specific state
python3 nico_client.py posting search --title "backend engineer" --country US --region California

# At a specific employer (each name must resolve to exactly one employer)
python3 nico_client.py posting search --employers "Anthropic" --country US --work-mode remote

# Radius search around a city (region required for US/CA cities)
python3 nico_client.py posting search --city "Berlin" --country DE --radius-km 25 --title designer

# Walk further pages
python3 nico_client.py posting search --country US --limit 100 --page 2

Flag	Required	Description
`--country`	Yes	ISO 3166-1 alpha-2 country code, e.g. `US`, `NL`, `FR`
`--title`	No	Title phrase (case-insensitive substring). Repeat to OR several.
`--employers`	No	Employer name. Repeat for several. Each must resolve to exactly one employer.
`--region`	No	State/province name. Required with `--city` when `--country` is `US` or `CA`.
`--city`	No	City name for radius search (resolved against Nico’s geocoded index).
`--radius-km`	No	Radius in km around `--city` (default `25`, max `250`).
`--work-mode`	No	`remote` or `onsite`. Repeat for several.
`--limit`	No	Results per page (default `20`, max `100`).
`--page`	No	Page number (default `1`).

Don’t combine --region/--city with --work-mode remote. Remote postings aren’t pinned to a location, so a geographic filter plus remote almost always returns nothing. Search remote roles by country, and use --region/--city for on-site or hybrid roles.

Output: JSON with job_postings (compact — no url/description), count, and a pagination block (current_page, total_pages, total_count, per_page). Errors are returned as { "error": "…" } — e.g. unknown/ambiguous employer, unknown location, country_code is required, or job search not enabled for the account.

posting get

Fetch one posting’s full detail by the id from a posting search result. Adds the application url and the full description (the two fields the search list omits).

python3 nico_client.py posting get --id "019e5132-627d-799e-963e-3c24f72a9dd5"

Flag	Required	Description
`--id`	Yes	The posting `id` from `posting search` results.

Output: JSON with the full posting, including url and description. Returns { "error": "Job posting not found" } for an unknown id.

application — job application management

application search

Check whether a job is already in your applications (duplicate check by URL, or search by company name).

# Search by URL (exact match) — the duplicate check
python3 nico_client.py application search --url "https://company.com/jobs/123"

# Search by company name (case-insensitive)
python3 nico_client.py application search --company-name "Acme Inc"

Flag	Required	Description
`--url`	No*	Search by exact job posting URL
`--company-name`	No*	Search by company name
`--status`	No	Filter by status: `draft`, `applied`, `interviewing`, `offer`, `finished`, `active`

*At least one of --url or --company-name is required. Output: For a URL search, { "exists": true|false, "count": N, "job_applications": [...] }.

application list

List your job applications.

python3 nico_client.py application list --status active
python3 nico_client.py application list --status draft --per-page 50 --page 2

Flag	Required	Description
`--status`	No	Filter by status group
`--per-page`	No	Items per page (default `25`, max `100`)
`--page`	No	Page number (default `1`)

Output: JSON with job_applications and a pagination block.

application get

Fetch one application’s full detail, including its notes and interviews.

python3 nico_client.py application get --id "019e1e40-1234-7000-9abc-1111aaaa2222"

Flag	Required	Description
`--id`	Yes	The job application id

Output: JSON with the full application, plus notes and interviews arrays.

application create

Create a new proposed job application.

python3 nico_client.py application create \
  --title "Software Engineer" \
  --company "Acme Inc" \
  --url "https://company.com/jobs/123" \
  --location "Berlin, Germany" \
  --work-mode remote

Flag	Required	Description
`--title`	Yes	Job title
`--company`	Yes	Company name
`--url`	No	Job posting URL
`--location`	No	Job location
`--work-mode`	No	One of: `remote`, `remote-optional`, `hybrid`, `on-site`
`--employment-type`	No	One of: `full-time`, `part-time`, `contract`, `internship`, `temporary`

Output: JSON with the created application. Status is always proposed.

Created jobs require your approval before they move forward. You’ll see them on your kanban board in the Draft column.

application add-note

Add a note to a job application.

python3 nico_client.py application add-note \
  --id "019e1e40-1234-7000-9abc-1111aaaa2222" \
  --body "Recruiter replied — call scheduled for Friday"

Flag	Required	Description
`--id`	Yes	The job application id
`--body`	Yes	The note text (max 10,000 characters)

application parse-url

Parse a job posting URL to extract structured data you can pass to application create.

python3 nico_client.py application parse-url --url "https://company.com/jobs/123"

Flag	Required	Description
`--url`	Yes	Job posting URL to parse

Output: JSON with parsed job details (title, company, location, work mode, salary).

Authentication

The CLI sends your API key as a Bearer token in the Authorization header:

Authorization: Bearer your-api-key-here
Content-Type: application/json
User-Agent: NicoJobAgentClient/1.0

Typical AI agent workflow

Search Nico’s index first — it already holds hundreds of thousands of postings — then track the interesting ones:

# 1. Search Nico's index for openings
python3 nico_client.py posting search --title "senior backend engineer" --city "Berlin" --country DE

# 2. Pull the application url + description for a result
python3 nico_client.py posting get --id "<posting_id>"

# 3. Check it isn't already tracked
python3 nico_client.py application search --url "<application_url>"

# 4. Add it as a proposed application
python3 nico_client.py application create \
  --title "Senior Backend Engineer" \
  --company "Example Corp" \
  --url "<application_url>" \
  --location "Berlin, Germany" \
  --work-mode hybrid

Overview

AI Agents

Authentication

External Tools

CLI Tool

CLI Tool

Prerequisites

Setup

1. Get the CLI

2. Configure

Command groups

posting — job posting search

posting search

posting get

application — job application management

application search

application list

application get

application create

application add-note

application parse-url

Authentication

Typical AI agent workflow

​CLI Tool

​Prerequisites

​Setup

​1. Get the CLI

​2. Configure

​Command groups

​posting — job posting search

​posting search

​posting get

​application — job application management

​application search

​application list

​application get

​application create

​application add-note

​application parse-url

​Authentication

​Typical AI agent workflow

CLI Tool

Prerequisites

Setup

1. Get the CLI

2. Configure

Command groups

posting — job posting search

posting search

posting get

application — job application management

application search

application list

application get

application create

application add-note

application parse-url

Authentication

Typical AI agent workflow