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

# CLI Overview

> Manage NexSpace from the command line

# NexSpace CLI

The NexSpace CLI is the agent-friendly surface of the **headless triad** (REST,
hosted MCP, CLI) — same auth model, JSON-friendly output, and first-class verbs
for workforce operations.

Package: `@nexspace/cli@0.2.0` · Hosted MCP: `https://mcp.nexspace365.com`

## Features

* Agent loop: `search` → `mcp schema` → `mcp call --dry-run` → execute
* First-class commands for MCP verbs (shifts, staff, payroll, CRM, credentials, …)
* JSON by default for non-TTY / `NEXSPACE_CLI_JSON=1` (`--json` / `--no-json`)
* Structured errors `{ error, code, next }` with exit `2` (auth) / `3` (input)
* OAuth device-code login + API keys; `skill install` for Cursor / Claude
* Facility pinning via `context use`; suite filter via `--suite`
* Webhooks CRUD + `events listen` (HMAC verify + tunnel UX)
* Approvals decide loop, audit / trajectories, `logs tail`
* Fixtures (`sandbox-reset`, `webhook-test`) and `conformance run`
* Inline `nexspace run` with injected `execute` / `search` / `api` / `schema`

## Output format

Every command that prints a result takes `--json` / `--no-json`. When you pass
neither, the CLI picks for you:

| Condition                                  | Output |
| ------------------------------------------ | ------ |
| `--no-json`                                | human  |
| `--json`                                   | JSON   |
| `NEXSPACE_CLI_JSON=1`                      | JSON   |
| stdout is not a TTY (pipe, CI, subprocess) | JSON   |
| otherwise                                  | human  |

That means agents and scripts get parseable output with no flag, while an
interactive terminal still gets tables.

<Warning>
  **Breaking change in 0.2.0.** In 0.1.x these commands printed a human table
  unless you passed `--json`; they now emit JSON whenever stdout is not a TTY:
  `whoami`, `api-keys list`, `api-keys create`, `api-keys revoke`,
  `facilities list`, `mcp tools`, `shifts list`, `shifts get`, `shifts fill`,
  `staff search`, `staff get`, `agents runs list|get|cancel|approvals`,
  `agents approvals approve|reject`, and
  `agents triggers list|create|update|delete|toggle|run-now`.

  Scripts that parsed the table output must either consume JSON or pass
  `--no-json`, which is new in 0.2.0 (in 0.1.x `--json` was opt-in only and had no
  negated form).
</Warning>

## Quick Start

```bash theme={null}
# Install
npm install -g @nexspace/cli

# Login (opens browser for device-code OAuth)
nexspace login
nexspace skill install

# Agent discovery
nexspace search "fill open shift"
nexspace mcp schema fillShift

# List facilities
nexspace facilities list --json

# Fill a shift (dry-run first)
nexspace shifts fill --shift-id 456 --staff-id 789 --dry-run
nexspace shifts fill --shift-id 456 --staff-id 789
```

<CardGroup cols={3}>
  <Card title="Installation" icon="download" href="/cli/installation">
    npm, Homebrew, or curl installer.
  </Card>

  <Card title="Authentication" icon="key" href="/cli/authentication">
    API key or OAuth device-code flow.
  </Card>

  <Card title="Commands" icon="terminal" href="/cli/commands">
    Full command reference.
  </Card>
</CardGroup>