nordvpn

# NordVPN CLI Skill (Linux)

A ClawBot skill for controlling the **NordVPN Linux CLI** (`nordvpn`) to connect/disconnect, select locations, verify status, and adjust settings from automations and workflows.

## Assumptions / Compatibility

* Works with the official `nordvpn` CLI (example shown: **4.3.1 [snap]**).
* Requires the NordVPN daemon running (usually `nordvpnd`) and sufficient permissions.
* Some commands may require elevated privileges depending on distro + install method (snap vs deb).

## Installation

### Option A: Snap (common on Ubuntu)

```bash
sudo snap install nordvpn
nordvpn --version
```

### Option B: Distro package / repo (varies)

If you installed via Nord’s repo or a package manager, just verify:

```bash
which nordvpn
nordvpn --version
```

### Verify daemon is running

```bash
# systemd installs usually
systemctl status nordvpnd --no-pager || true

# snap installs may not expose systemd unit the same way
nordvpn status || true

# or may require the full patch to be specified like so
/snap/bin/nordvpn status || true
```

## Authentication / Login

NordVPN CLI typically requires logging in once per machine/user session.

```bash
nordvpn login
```

If the environment is headless, the CLI will guide you through the login flow (often via a browser link / code). After login, confirm:

```bash
nordvpn account
nordvpn status
```

**ClawBot guidance:** treat login as a manual prerequisite unless you explicitly automate the browser-based login flow.

## Quick Reference

### Status

```bash
nordvpn status
```

### Connect (best available)

```bash
nordvpn connect
# alias:
nordvpn c
```

### Connect to a country / city / group

```bash
# country
nordvpn connect Sweden

# city (must exist in `nordvpn cities <country>`)
nordvpn connect "Stockholm"

# group (must exist in `nordvpn groups`)
nordvpn connect P2P
```

### Disconnect

```bash
nordvpn disconnect
# alias:
nordvpn d
```

### List locations

```bash
nordvpn countries
nordvpn cities Sweden
nordvpn groups
```

### Settings (read + change)

```bash
nordvpn settings

# examples (options differ by version)
nordvpn set autoconnect on
nordvpn set killswitch on
nordvpn set threatprotectionlite on  # if supported
nordvpn set protocol nordlynx        # if supported
```

### Allowlist (bypass VPN for certain traffic)

```bash
# view help
nordvpn allowlist --help

# examples (subcommands differ by version)
nordvpn allowlist add port 22
nordvpn allowlist add subnet 192.168.0.0/16
nordvpn allowlist remove port 22
```

## Skill Design

### What this skill should do well

1. **Idempotent connection actions**

   * If already connected to the requested target, do nothing (or return “already connected”).
   * If connected elsewhere, optionally disconnect then connect to target.
2. **Reliable verification**

   * After connect/disconnect, always run `nordvpn status` and parse the result.
3. **Safe fallbacks**

   * If a requested city/country/group is invalid, provide closest alternatives by listing:

     * `nordvpn countries`
     * `nordvpn cities <country>`
     * `nordvpn groups`
4. **Human-in-the-loop login**

   * If `nordvpn` reports not logged in, return a structured response instructing to run `nordvpn login`.

### Recommended “actions” (API surface)

Implement these as the skill’s callable intents/tools:

* `status()` → returns parsed connection status
* `connect_best()` → connects to best available
* `connect_country(country)`
* `connect_city(city)` (optionally with `country` for disambiguation)
* `connect_group(group)`
* `disconnect()`
* `list_countries()`
* `list_cities(country)`
* `list_groups()`
* `get_settings()`
* `set_setting(key, value)`
* `allowlist_add(type, value)`
* `allowlist_remove(type, value)`

## Suggested Implementation Pattern (CLI orchestration)

### 1) Always start with status

```bash
nordvpn status
```

Parse fields commonly returned by the CLI, such as:

* Connection state (Connected/Disconnected)
* Current server / country / city
* IP, protocol, technology

### 2) Connect flow

**Goal:** connect to a target (country/city/group) with verification.

Pseudo-logic:

* Run `nordvpn status`
* If disconnected → connect directly
* If connected to different target → `nordvpn disconnect` then connect
* Run `nordvpn status` again and confirm connected

Commands:

```bash
nordvpn connect "<target>"
nordvpn status
```

### 3) Disconnect flow

```bash
nordvpn disconnect
nordvpn status
```

### 4) Resolve targets safely

If user asks for a city:

* Prefer `nordvpn cities <country>` when country is known
* Otherwise attempt connect; if it fails, list countries and search-like suggestions.

```bash
nordvpn countries
nordvpn cities "<country>"
nordvpn groups
```

## Common Errors & Handling

### Not logged in

Symptoms:

* CLI complains about authentication/account/login.

Handling:

* Return: “Login required. Run `nordvpn login` and repeat.”
* Optionally: run `nordvpn account` to confirm.

### Daemon not running / permission denied

Symptoms:

* Can’t connect, service errors, permission errors.

Handling:

* Check `systemctl status nordvpnd` (systemd installs)
* Confirm snap service health (snap installs vary)
* Ensure user belongs to the right group (some installs use a `nordvpn` group):

  ```bash
  groups
  getent group nordvpn || true
  ```

### Invalid location/group

Symptoms:

* “Unknown country/city/group” or connect fails immediately.

Handling:

* Provide available options:

  ```bash
  nordvpn countries
  nordvpn groups
  nordvpn cities "<country>"
  ```

## Practical Automation Recipes

### Ensure VPN is connected (any server)

```bash
nordvpn status | sed -n '1,10p'
nordvpn connect
nordvpn status | sed -n '1,15p'
```

### Reconnect to a specific country

```bash
nordvpn disconnect
nordvpn connect Sweden
nordvpn status
```

### Toggle killswitch (example)

```bash
nordvpn set killswitch on
nordvpn settings
```

## Notes

* Command options and setting keys can differ by NordVPN CLI version. Always rely on:

  ```bash
  nordvpn help
  nordvpn set --help
  nordvpn allowlist --help
  ```
* If you need stable machine-readable output, the NordVPN CLI does not consistently provide JSON; plan to parse human-readable status text defensively (line-based key/value extraction, tolerate missing fields).