> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nico-jobagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Tool

> Command-line interface for AI agents and automation

# 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](/integrations/api-keys)

## Setup

### 1. Get the CLI

The CLI is included in the [`nico-jobagent/nico-skills`](https://github.com/nico-jobagent/nico-skills) repository:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
# 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`).                                                    |

<Warning>
  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.
</Warning>

**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).

```bash theme={null}
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).

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`.

<Note>
  Created jobs require your approval before they move forward. You'll see them on your kanban board in the Draft column.
</Note>

***

### application add-note

Add a note to a job application.

```bash theme={null}
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`.

```bash theme={null}
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:

```bash theme={null}
# 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
```