neuroskill-com/neuroskill-transport

NeuroSkill Transport & Quick Start

NeuroSkill runs a local server (auto-discovered via mDNS or lsof). All commands work over both transports; the CLI picks the best one automatically.

---

WebSocket (ws://127.0.0.1:<port>)

• Full-duplex, low-latency. Best for live data, event streaming, and polling loops.
• Commands are JSON messages sent over the socket; responses arrive as JSON messages.
• Supports real-time broadcast events (EEG packets, scores, label-created, …).
• Used by default when the server is reachable.

# Force WebSocket:
npx neuroskill status --ws

# Direct WebSocket from any language (wscat example):
wscat -c ws://127.0.0.1:8375
> {"command":"status"}
< {"command":"status","ok":true,"device":{...},"scores":{...},...}

---

HTTP (http://127.0.0.1:<port>/)

• Request / response only. No live streaming, no broadcast events.
• All commands are POST / with a JSON body; the response is JSON.
• Useful from curl, Python requests, Node fetch, or any HTTP client.
• Automatic fallback when the WebSocket is unreachable.

# Force HTTP:
npx neuroskill status --http

# curl equivalent of every CLI command:
curl -s -X POST http://127.0.0.1:8375/ \
  -H "Content-Type: application/json" \
  -d '{"command":"status"}'

# Extract a single field with jq:
curl -s -X POST http://127.0.0.1:8375/ \
  -H "Content-Type: application/json" \
  -d '{"command":"status"}' | jq '.scores.focus'

---

Auto-transport (default)

When neither --ws nor --http is given, the CLI probes WebSocket first and silently falls back to HTTP. Informational lines are written to stderr (not stdout), so JSON piping is never polluted.

---

Port Discovery

The CLI finds the port automatically via:

1. --port <n> flag (explicit, skips all discovery)
2. mDNS (_skill._tcp service advertisement, 5 s timeout)
3. lsof / pgrep fallback (probes each TCP LISTEN port)

npx neuroskill status --port 62853    # skip discovery entirely

---

Quick Start

# Prerequisites (run once):
npm install -g neuroskill

# Snapshot of everything:
npx neuroskill status

# Pipe-friendly JSON output:
npx neuroskill status --json | jq '.scores'

# Print full help with examples:
npx neuroskill --help

---

Output Modes

Every command has three output modes.

Default (no flag) — human-readable summary only

Colored, structured summary to stdout. Raw JSON is discarded after rendering.

npx neuroskill status        # colored summary, no JSON
npx neuroskill session 0     # trend table, no JSON
npx neuroskill sleep         # stage counts, no JSON

--json — raw JSON only, pipe-safe

print() calls suppressed; only printResult() fires. Plain JSON, no ANSI codes on stdout. Informational lines go to stderr and never pollute the JSON stream.

npx neuroskill status --json                            # full JSON, no summary
npx neuroskill status --json | jq '.scores.focus'       # pipe to jq
npx neuroskill sleep  --json | jq '.summary'
npx neuroskill search --json | jq '.result.results[0].neighbors'
npx neuroskill umap   --json | jq '.result.points | length'

--full — human-readable summary and colorized JSON

Both print() and printResult() fire. Summary prints first, then complete colorized JSON.

npx neuroskill status       --full   # summary + full colorized JSON
npx neuroskill neurological --full   # summary + references object
npx neuroskill session 0    --full   # trend table + raw first/second/trends objects
npx neuroskill sleep        --full   # stage counts + full epochs[] array
npx neuroskill umap         --full   # cluster analysis + full points[] array

Colors: --full uses ANSI-colored JSON. For plain text, pipe through sed 's/\x1b\[[0-9;]*m//g' or use --json.

---

Global Options

| Flag | Description | |---|---| | --port <n> | Connect to an explicit port (skips mDNS) | | --ws | Force WebSocket; error if unreachable | | --http | Force HTTP REST; no live-event commands | | --json | Raw JSON only — no summary, no colors, pipe-safe | | --full | Human-readable summary and colorized full JSON appended below | | --no-color | Disable ANSI color output (also honoured via NO_COLOR env var) | | --dot | (interactive only) Graphviz DOT to stdout — pipe to dot -Tsvg | | --trends | (sessions only) Show first-half → second-half deltas | | --mode <m> | (search-labels) text | context | both | | --k <n> | Number of nearest neighbors (search, search-labels) | | --k-text <n> | (interactive) k for text-label HNSW search (default 5) | | --k-eeg <n> | (interactive) k for EEG-similarity HNSW search (default 5) | | --k-labels <n> | (interactive) k for label-proximity step (default 3) | | --reach <n> | (interactive) temporal window in minutes around each EEG point (default 10) | | --ef <n> | HNSW ef parameter (search-labels; default max(k×4, 64)) | | --seconds <n> | Duration for listen (default 5) | | --profile <p> | Profile name or UUID for calibrate | | --poll <n> | (status) Re-poll every N seconds; keeps the socket open | | --context "..." | (label) Long-form annotation body; used by search-labels --mode context | | --at <utc> | (label) Backdate to a specific Unix second (default: now) | | --voice <name> | (say) Voice name to use (e.g. Jasper); omits to use the server default | | --version | Print CLI version and exit | | --help | Show full help and exit |

---

Polling with status

status is the single fastest call to get a complete system snapshot. Poll it periodically from any script or external tool to react to EEG state changes.

# One-shot snapshot:
npx neuroskill status --json

# Poll every 5 seconds and print focus score:
while true; do
  npx neuroskill status --json | jq '.scores.focus'
  sleep 5
done

# Alert when focus drops below 0.4:
while true; do
  FOCUS=$(npx neuroskill status --json | jq '.scores.focus')
  if (( $(echo "$FOCUS < 0.4" | bc -l) )); then
    npx neuroskill notify "Focus dropped" "Current: $FOCUS"
  fi
  sleep 10
done