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

# CLI

> Install and use the optional nullspace command line for auth, machines, desktop automation, code execution, lifecycle, snapshots, and volumes.

Install the optional CLI extras:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
python -m pip install "nullspace-sdk[cli]==1.0.0"
```

## Authenticate

Hosted private beta:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace auth login --api-url https://api.13-215-85-171.sslip.io
nullspace doctor
nullspace quickstart
```

Self-hosted single-host localhost/no-domain mode:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_KEY="$(sudo cat /etc/nullspace/operator-api-key)"
export NULLSPACE_API_URL=http://localhost
nullspace doctor
nullspace machine list
```

Self-hosted owned-domain mode uses the owned Caddy/API origin:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
export NULLSPACE_API_URL=https://nullspace.example
```

The CLI reads environment variables, project `.env`,
`~/.config/nullspace/config.json`, then legacy `~/.nullspace/config.json`.
SDK constructors also accept explicit `api_key=` and `base_url=` arguments.
Use `NULLSPACE_API_KEY` and `NULLSPACE_API_URL` directly for scripts, CI, and
coding agents. The SDK/CLI client variable is `NULLSPACE_API_URL`; the
similarly named `VITE_NULLSPACE_API_BASE` is only for console builds.

## Machines

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create --template base
nullspace machine create --template base --on-timeout pause --auto-resume
nullspace machine create --snapshot-id snap_123 --timeout 300
nullspace machine create --template desktop --resolution 1280x720 --dpi 144
nullspace machine list
nullspace machine list --state running --metadata team=eval
nullspace machine exec mch_123 --shell "echo hello"
nullspace ssh mch_123 -- python --version
nullspace machine ssh-access mch_123 --print-command
nullspace machine url mch_123 8080
nullspace machine preview-url create mch_123 8080 --expires 15m --wait
nullspace machine preview-url list mch_123 --port 8080 --json
nullspace machine preview-proxy-target create mch_123 8080 --transport http --transport websocket
nullspace machine metrics mch_123
nullspace machine metrics mch_123 --json
nullspace machine kill mch_123
```

The text form prints CPU, memory, and disk samples. Use `--json` when another
tool should consume the raw metrics payload.
For create-time pause/hibernate behavior, prefer `--on-timeout pause`; use
`nullspace machine timeout set mch_123 --seconds 300 --action hibernate` when
changing an existing machine.
Use `nullspace ssh` when a local tool requires OpenSSH; it mints a
short-lived certificate for the Nullspace SSH relay.
Use `machine preview-url` for direct preview link lifecycle, inventory, and
revocation. Human output redacts signed preview URLs by default; use `--raw`
only for an explicit secret-bearing display action. Grant list output includes
safe usage counters and last-error metadata; use `--json` for automation that
needs raw returned values.

## Files and lifecycle

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine upload mch_123 ./report.txt /workspace/report.txt
nullspace machine file list mch_123 /workspace
nullspace machine file upload-url mch_123 /workspace/report.txt
nullspace machine desktop screenshot mch_123 --output screen.png
nullspace machine code run mch_123 "print('hello')" --json
nullspace snapshot create mch_123
nullspace lifecycle events --limit 20
nullspace lifecycle stream --machine-id mch_123 --live-only
nullspace monitor stream --include-processes
nullspace lifecycle webhooks deliveries wh_123
nullspace lifecycle webhooks delivery wh_123 del_123
```

## Volumes

> Volume commands require a shared-volume-enabled environment.

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume list
nullspace volume get team-data
nullspace volume ls-files team-data /
printf "hello" | nullspace volume write team-data /hello.txt
nullspace volume read team-data /hello.txt
nullspace volume find team-data /datasets "needle"
nullspace volume upload-url team-data /models/model.bin
nullspace volume download-url team-data /models/model.bin
nullspace volume upload team-data ./model.bin /models/model.bin
nullspace volume download team-data /models/model.bin ./model.bin
nullspace volume delete vol_12345678
```

They do not make live VM memory or mutable rootfs snapshot state portable;
shared volumes remain external durable storage that remounts on compatible
resume and fork.

Concepts: [Create](../../concepts/create), [Destroy](../../concepts/destroy).
API reference: [createMachine](../../api-reference),
[destroyMachine](../../api-reference), [createVolume](../../api-reference).

Use `nullspace schema` to inspect the installed command tree and generated MCP
tool input schemas. Install `nullspace-sdk[cli,mcp]==1.0.0` before using
`nullspace mcp serve` so the MCP server dependency is available.

For Claude Code or Codex running locally, run
`nullspace docs install --agent all` from the project directory after installing
the MCP extra. The command installs local Markdown docs and project-local agent
instructions without requiring an API key.

Self-hosted setup: [Self-Hosted Single-Host](../../quickstarts/self-hosted-single-host).