> ## 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 Schema

> Machine-readable command metadata emitted by nullspace schema.

`nullspace schema` emits the versioned `v1` schema for the installed CLI.
Agents can use it to discover commands, arguments, flags, exit codes, and the
JSON error envelope without scraping help text.

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace schema
nullspace schema machine list
```

The full document has this shape:

```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "schema_version": "v1",
  "program": "nullspace",
  "output_versions": ["v1"],
  "commands": {
    "machine.list": {
      "id": "machine.list",
      "full_path": "nullspace machine list",
      "summary": "List all running machines.",
      "flags": [
        {"name": "json_output", "flags": ["--json"], "type": "boolean"},
        {"name": "fields", "flags": ["--fields"], "type": "text"},
        {"name": "states", "flags": ["--state"], "type": "choice"},
        {"name": "template_filter", "flags": ["--template"], "type": "text"},
        {"name": "metadata_entries", "flags": ["--metadata"], "type": "text"},
        {"name": "metadata_json", "flags": ["--metadata-json"], "type": "text"},
        {"name": "limit", "flags": ["--limit"], "type": "integer range"},
        {"name": "next_token", "flags": ["--next-token"], "type": "text"}
      ],
      "arguments": [],
      "json_schema": {
        "type": "object",
        "properties": {
          "states": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["creating", "running", "paused", "destroyed", "error"]
            }
          },
          "limit": {"type": "integer", "minimum": 1}
        },
        "additionalProperties": false
      }
    }
  },
  "exit_codes": [],
  "error_envelope": {}
}
```

Use `nullspace schema <command path>` to return a single command entry. Command
entries include:

* `id`: dotted command path, for example `machine.list`
* `full_path`: shell command path, for example `nullspace machine list`
* `kind`: `group` or `command`
* `flags`: Click options with flag names, defaults, required state, help text,
  and JSON Schema type metadata
* `arguments`: positional arguments with type and required state
* `error_codes`: common error codes that command callers should handle
* `output.version`: currently `v1`

The schema is additive within `v1`. New fields may appear, but existing field
names and meanings will not change without a new schema version.