# nordvpn-client

Cross-platform NordVPN lifecycle skill for macOS and Linux.

## What it does

- Probes whether NordVPN is already installed
- Bootstraps NordVPN if missing
- Handles login bootstrap
- Connects to a country or city target
- Disconnects and reports status
- Verifies public IP and geolocation after connect

## Commands

```bash
node skills/nordvpn-client/scripts/nordvpn-client.js status
node skills/nordvpn-client/scripts/nordvpn-client.js install
node skills/nordvpn-client/scripts/nordvpn-client.js login
node skills/nordvpn-client/scripts/nordvpn-client.js verify
node skills/nordvpn-client/scripts/nordvpn-client.js verify --country "Italy"
node skills/nordvpn-client/scripts/nordvpn-client.js verify --country "Italy" --city "Milan"
node skills/nordvpn-client/scripts/nordvpn-client.js connect --country "Italy"
node skills/nordvpn-client/scripts/nordvpn-client.js connect --city "Milan"
node skills/nordvpn-client/scripts/nordvpn-client.js disconnect
```

## Platform behavior

### macOS

- install path: `brew install --cask nordvpn`
- probe order:
  - `nordvpn` CLI if present
  - `NordVPN.app`
- if the installed package exposes a usable CLI, the skill uses it
- otherwise it opens the app and returns a clear manual-action-required result for login/connect/disconnect

### Linux

- install path follows NordVPN's official installer script
- primary control path is the official `nordvpn` CLI
- token login is supported through `nordvpn login --token <token>`

## Credentials

Supported env vars:

- `NORDVPN_TOKEN`
- `NORDVPN_TOKEN_FILE`
- `NORDVPN_USERNAME`
- `NORDVPN_PASSWORD`
- `NORDVPN_PASSWORD_FILE`

Do not put secrets in the skill docs or repo.

## Verification model

`status`, `verify`, and `connect` emit JSON suitable for agent use:

- platform
- install state
- control mode (`cli` vs `app-manual`)
- auth state
- connection state
- requested target
- public IP / geolocation lookup

After `connect`, the intended workflow is:

1. `nordvpn-client connect ...`
2. `nordvpn-client verify ...` if an explicit location check is needed
3. run the follow-up task such as `web-automation`

## Limitations

- Linux city targeting is attempted through the CLI target string and then validated by public IP/location checks.
- macOS app-only fallback cannot guarantee non-interactive control if the app does not expose a CLI.
- On macOS, the Homebrew cask may install only the GUI app. That is still a supported install state; `status` reports `controlMode: "app-manual"` so agents should continue with the app flow instead of concluding NordVPN is unavailable.