Commands Reference

Global Flags

Flag	Description
`--json` / `--no-json`	Force JSON or human text (JSON is default for non-TTY / `NEXSPACE_CLI_JSON=1`)
`--help`	Show help
`--version`	Show version

Authenticate once with nexspace login (see CLI Authentication); commands reuse the stored credential automatically.

Agent loop

nexspace search "fill open shift"
nexspace mcp schema fillShift
nexspace mcp call fillShift --args '{"shiftId":12,"staffId":7}' --dry-run
nexspace mcp call fillShift --args '{"shiftId":12,"staffId":7}'
nexspace agent playbook
nexspace skill install

Errors return { "error", "code", "next" } with exit 2 (auth) or 3 (input).

Environment

Variable	Purpose
`NEXSPACE_API_KEY`	API key when not logged in via config
`NEXSPACE_BASE_URL`	Override API base (default `https://api.nexspace365.com`)
`NEXSPACE_CLI_JSON`	Set to `1` to force JSON output

Auth

Authenticate. Defaults to the browser device-code OAuth flow; pass --token to store an API key/PAT instead. Credentials are saved to the OS keychain when available (falling back to ~/.nexspace/config.json).

nexspace login
nexspace login --token nex_pat_xxxxxxxxxxxxxxxxxxxx

Explicit alias for the OAuth device-code login flow.

nexspace login-device

`nexspace logout`

Remove stored credentials.

nexspace logout

`nexspace whoami`

Print the identity the current credential authenticates as.

nexspace whoami
nexspace whoami --json

Discovery

`nexspace search <query>`

Rank MCP tools by natural-language intent.

Flag	Description
`--limit <n>`	Max results (default: 10)
`--suite <name>`	Limit to `scheduling` \| `hr` \| `payroll` \| `crm` \| `ai` \| `messaging`

nexspace search "fill open shift"
nexspace search "leads" --suite crm --json

`nexspace mcp tools`

List available MCP tools.

Flag	Description
`--suite <name>`	Filter by suite

nexspace mcp tools
nexspace mcp tools --suite scheduling --json

`nexspace mcp schema <toolName>`

Print inputSchema (and outputSchema when present) for a tool.

nexspace mcp schema fillShift

`nexspace mcp call <toolName>`

Invoke an MCP tool by name.

Flag	Description
`--args <json>`	Tool arguments as JSON
`--dry-run`	Validate args + auth; never invokes the named tool

Under --dry-run the named tool is never called, read-only or not. Where a preview sibling exists (runPayroll → previewPayrollRun) the CLI calls that instead and returns its result under result; otherwise it returns { dryRun: true, valid: true, mutating } with nothing executed.

nexspace mcp call listFacilities
nexspace mcp call fillShift --args '{"shiftId":12,"staffId":7}' --dry-run
nexspace mcp call fillShift --args '{"shiftId":12,"staffId":7}'

Context

`nexspace context use`

Pin a facility so shifts, staff, and payroll commands default to it instead of repeating --facility-id on every call.

nexspace context use --facility-id 12
nexspace context show
nexspace context use --clear

There is no --org-id. Org scope is derived from the credential you logged in with and cannot be overridden per-request; the few super-admin REST routes that accept a narrowing override take it explicitly as nexspace api GET /api/crm/... -q orgUnitId=N.

Facilities

`nexspace facilities list` / `get`

nexspace facilities list --json
nexspace facilities get --id 12

Staff

`nexspace staff search` / `get` / `find-credentialed` / `credentials-expiring`

nexspace staff search --query "Jane"
nexspace staff get 789
nexspace staff find-credentialed --facility-id 12 --specialty RN
nexspace staff credentials-expiring --days-ahead 30 --facility-id 12

Shifts

`nexspace shifts list` / `get` / `fill` / `propose` / `swap` / `coverage`

nexspace shifts list --facility-id 12 --status open
nexspace shifts get --id 456
nexspace shifts fill --shift-id 456 --staff-id 789 --dry-run
nexspace shifts fill --shift-id 456 --staff-id 789
nexspace shifts propose --facility-id 12 --start-date 2026-05-10 --end-date 2026-05-17
nexspace shifts swap --shift-a-id 1 --shift-b-id 2
nexspace shifts coverage --facility-id 12 --start-date 2026-05-10 --end-date 2026-05-17

Use --dry-run on mutating verbs before the real call.

Credentials

`nexspace credentials verify`

nexspace credentials verify --credential-id 456

Payroll

`nexspace payroll preview` / `run`

Always preview (or --dry-run on run) before committing.

nexspace payroll preview --facility-id 12 --period-start 2026-05-01 --period-end 2026-05-15
nexspace payroll run --facility-id 12 --period-start 2026-05-01 --period-end 2026-05-15 \
  --confirmed-by "alice@example.com" --dry-run
nexspace payroll run --facility-id 12 --period-start 2026-05-01 --period-end 2026-05-15 \
  --confirmed-by "alice@example.com"

CRM

`nexspace crm leads-search` / `leads-qualify`

nexspace crm leads-search --query "Acme"
nexspace crm leads-qualify --lead-id 99 --dry-run

Notify

`nexspace notify shift-swap`

nexspace notify shift-swap --shift-id 456 --staff-ids 789,790 --message "Swap confirmed"
nexspace notify shift-swap --shift-id 456 --staff-ids 789 --message "Swap confirmed" \
  --channels push,email --dry-run

Flag	Description
`--shift-id <n>`	Shift the swap applies to (required)
`--staff-ids <list>`	Comma-separated staff ids (required)
`--message <text>`	Notification body (required)
`--channels <list>`	Any of `push`, `sms`, `email` (default `push,sms`)
`--dry-run`	Validate without sending

This verb sends real SMS and push notifications, so it validates strictly rather than notifying a subset: a non-numeric entry in --staff-ids or an unrecognized --channels value exits 3 (VALIDATION_FAILED) and sends nothing.

API Keys

`nexspace api-keys list` / `create` / `revoke`

nexspace api-keys list
nexspace api-keys create --name "CI Pipeline" --scopes "shifts:read,staff:read"
nexspace api-keys create --name "Agent key" --scopes "*:*" --expires-in-days 90
nexspace api-keys revoke 42

Webhooks & events

`nexspace webhooks list` / `create` / `delete` / `test`

nexspace webhooks list
nexspace webhooks create --name "Local" --url https://xxxx.ngrok-free.app/hooks --events shift_filled
nexspace webhooks test --id 42
nexspace webhooks delete --id 42

`nexspace events listen`

Local receiver + temporary subscription. Verifies X-NexSpace-Signature when the create response includes signingSecret. Cloud API hosts cannot reach 127.0.0.1 — pass --forward-url (ngrok / cloudflared).

nexspace events listen --max-events 5
nexspace events listen --forward-url https://xxxx.ngrok-free.app/hooks --port 8787

`nexspace events trigger`

Fire a test delivery against an existing subscription.

nexspace events trigger --webhook-id 42

Approvals, audit & logs

Admin-gated AI action surfaces (same APIs as Admin → AI Config → Approvals). These are not the same as nexspace agents approvals (headless run resolution under agents:approve).

`nexspace approvals list` / `approve` / `reject`

nexspace approvals list
nexspace approvals approve --id 42 --reason "Coverage confirmed"
nexspace approvals reject --id 42 --reason "Wrong facility"

`nexspace audit list`

nexspace audit list --limit 20
nexspace audit list --tool-name fillShift --json
nexspace audit list --trajectory-id abc-123

`nexspace logs tail`

Polls GET /api/ai/audit as JSONL (there is no general HTTP request-log API).

nexspace logs tail --no-follow --max-events 20
nexspace logs tail --follow --interval 2

Agents

Headless agent runs (distinct from admin AI approvals above). Requires agents:run / agents:approve / agents.manage as noted. See also Agent runs.

`nexspace agents run <agentId>`

Start a headless agent run and stream its events to completion. Backed by POST /api/agents/{id}/runs + the run SSE stream (GET /api/agents/{id}/runs/{runId}/stream); requires the agents:run scope.

Flag	Description
`-m, --message <text>`	Seed message / task for the run (required to start)
`--resume-session-id <id>`	Continue a prior agent session (multi-turn)
`--output-format <fmt>`	`json` (default, prints the final result) or `stream-json` (NDJSON per event)
`--resume-run`	Resume an existing run stream instead of starting a new one (with `--run-id`)
`--run-id <id>`	Existing `runId` to resume
`--last-event-id <id>`	Last SSE event id seen, to replay missed events on resume

In stream-json mode each event is emitted as one JSON object per line — ideal for agents/CI that consume the run incrementally. A run_started line is emitted first, then one line per status / assistant / tool_call / result / done event. The command exits non-zero if the run ends in error or rejected.

# Print the final result as JSON
nexspace agents run 12 --message "Summarize open shifts for facility 3"

# Stream every event as NDJSON (agent/CI friendly)
nexspace agents run 12 -m "Qualify new leads" --output-format stream-json

# Reconnect to a dropped stream and replay from the last event id
nexspace agents run 12 --resume-run --run-id run_abc --last-event-id 4 --output-format stream-json

`nexspace agents runs <list|get|cancel|approvals>`

Inspect and control runs after they start. All require the agents:run scope and only operate on runs owned by the credential’s user.

Command	Backed by	Purpose
`agents runs list <agentId>`	`GET /api/agents/{id}/runs`	List runs (newest first). `--status`, `--limit`, `--json`
`agents runs get <agentId> <runId>`	`GET /api/agents/{id}/runs/{runId}`	Current state of a single run. `--json`
`agents runs cancel <agentId> <runId>`	`DELETE /api/agents/{id}/runs/{runId}`	Soft-cancel a `running` run
`agents runs approvals <agentId> <runId>`	`GET /api/agents/{id}/runs/{runId}/approvals`	List approvals a paused run raised

nexspace agents runs list 12 --status pending_approval
nexspace agents runs get 12 run_abc --json
nexspace agents runs approvals 12 run_abc
nexspace agents runs cancel 12 run_abc

`nexspace agents approvals <approve|reject> <approvalId>`

Resolve a pending_approval action raised by one of your runs. Requires the agents:approve scope. Approving executes the deferred tool and resumes the run once all its approvals are terminal; rejecting terminates the run as rejected.

Flag	Description
`--reason <text>`	Optional note recorded on the decision
`--json`	Emit the `ApprovalResolution` payload

nexspace agents approvals approve 1001 --reason "verified coverage"
nexspace agents approvals reject 1001 --reason "out of budget"

`nexspace agents triggers <list|create|update|delete|toggle|run-now>`

Manage automation triggers that fire an agent on a cron schedule or business event through the durable headless-run path. Requires the agents.manage permission and the ai suite.

Command	Backed by	Purpose
`agents triggers list <agentId>`	`GET /api/agent-builder/{id}/triggers`	List an agent’s triggers
`agents triggers create <agentId>`	`POST …/triggers`	Create a `schedule`/`event` trigger
`agents triggers update <agentId> <triggerId>`	`PATCH …/triggers/{triggerId}`	Partial update
`agents triggers delete <agentId> <triggerId>`	`DELETE …/triggers/{triggerId}`	Remove a trigger
`agents triggers toggle <agentId> <triggerId> --active <true\|false>`	`POST …/toggle`	Enable/disable
`agents triggers run-now <agentId> <triggerId>`	`POST …/run-now`	Dispatch immediately (`409` if busy)

create/update accept: --type, --cron, --timezone, --event-type, --event-filters (JSON), --run-as-user-id, --facility-id, --seed-message, --no-activate (create only). Schedule triggers need --cron; event triggers need --event-type.

# Daily 9am summary (Central time)
nexspace agents triggers create 12 --type schedule \
  --cron "0 9 * * *" --timezone America/Chicago \
  --seed-message "Summarize yesterday's open shifts"

# Fire on a no-call/no-show for facility 3
nexspace agents triggers create 12 --type event \
  --event-type shift.ncns --event-filters '{"facilityId":3}'

nexspace agents triggers list 12
nexspace agents triggers toggle 12 34 --active false
nexspace agents triggers run-now 12 34

Fixtures & conformance

`nexspace fixtures`

Sandbox / webhook helpers for agent demos.

nexspace fixtures list
nexspace fixtures sandbox-reset --facility-id 1   # session auth only — not API keys
nexspace fixtures webhook-test --webhook-id 12

See Sandbox.

`nexspace conformance run`

Runs the Governance Conformance Suite (Vitest) from a NexSpace checkout.

nexspace conformance run
nexspace conformance run --repo /path/to/NexSpace

Exits non-zero when the suite fails, in every output mode — safe to use as a CI gate. The JSON payload also reports coverage, because a green suite is not the same as a fully enforced one:

Field	Meaning
`passedClauses`	Clauses asserted and passing
`pendingClauses`	Clauses still stubbed as `it.todo` — declared but unenforced
`fullyEnforced`	`true` only when the suite passed and `pendingClauses` is 0

Gate on fullyEnforced rather than the exit code alone if you need every clause actually enforced; the exit code ignores pending clauses.

Agent helpers

`nexspace skill install`

Install the nexspace-operations skill for Cursor and/or Claude Code.

nexspace skill install
nexspace skill install --cursor --project
nexspace skill install --claude

`nexspace agent playbook`

Print the short search → schema → dry-run → call reminder.

nexspace agent playbook

`nexspace run`

Inline agent scripting with injected execute, search, api, and schema. Useful for fan-out; not a production runtime SLA — prefer MCP/REST for stable integrations.

nexspace run -e 'console.log(await search("credential"))'
nexspace run --file ./workflow.mjs
nexspace run -e 'await execute("searchStaff",{query:"a"})' --dry-run

--dry-run matches mcp call --dry-run: every execute() returns a { dryRun: true, skipped: true } envelope instead of running the tool — including read-only tools, so a mis-classified verb can’t slip through. The injected api() helper still performs GETs (discovery stays useful) but short-circuits POST / PUT / PATCH / DELETE the same way. search() and schema() are unaffected.

Escape hatch

`nexspace api <METHOD> <PATH>`

Authenticated passthrough to any API endpoint.

Flag	Description
`-d, --data <json>`	JSON request body
`-q, --query <k=v>`	Query param (repeatable)

nexspace api GET /api/shifts -q facilityId=1 -q status=open
nexspace api POST /api/webhooks -d '{"url":"https://x.dev/hook","events":["shift_filled"]}'
nexspace api DELETE /api/webhooks/42

Paths are resolved against the base URL you logged in with. You may pass an absolute URL, but it must share that origin — the CLI refuses to attach your bearer token to a foreign host rather than leaking the credential:

$ nexspace api GET https://evil.example/x
Refusing to send credentials to https://evil.example: the configured API base
is https://api.nexspace365.com. Use `nexspace login --base-url <url>` to target
a different host.

`nexspace update`

Update a standalone (Homebrew/curl) install to the latest release. npm installs update with npm i -g @nexspace/cli; Homebrew with brew upgrade nexspace.

nexspace update

​Commands Reference

​Global Flags

​Agent loop

​Environment

​Auth

​nexspace login

​nexspace login-device

​nexspace logout

​nexspace whoami

​Discovery

​nexspace search <query>

​nexspace mcp tools

​nexspace mcp schema <toolName>

​nexspace mcp call <toolName>

​Context

​nexspace context use

​Facilities

​nexspace facilities list / get

​Staff

​nexspace staff search / get / find-credentialed / credentials-expiring

​Shifts

​nexspace shifts list / get / fill / propose / swap / coverage

​Credentials

​nexspace credentials verify

​Payroll

​nexspace payroll preview / run

​CRM

​nexspace crm leads-search / leads-qualify

​Notify

​nexspace notify shift-swap

​API Keys

​nexspace api-keys list / create / revoke

​Webhooks & events

​nexspace webhooks list / create / delete / test

​nexspace events listen

​nexspace events trigger

​Approvals, audit & logs

​nexspace approvals list / approve / reject

​nexspace audit list

​nexspace logs tail

​Agents

​nexspace agents run <agentId>

​nexspace agents runs <list|get|cancel|approvals>

​nexspace agents approvals <approve|reject> <approvalId>

​nexspace agents triggers <list|create|update|delete|toggle|run-now>

​Fixtures & conformance

​nexspace fixtures

​nexspace conformance run

​Agent helpers

​nexspace skill install

​nexspace agent playbook

​nexspace run

​Escape hatch

​nexspace api <METHOD> <PATH>

​nexspace update