CLI Schema - Nullspace

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.

nullspace schema
nullspace schema sandbox list

The full document has this shape:

{
  "schema_version": "v1",
  "program": "nullspace",
  "output_versions": ["v1"],
  "commands": {
    "sandbox.list": {
      "id": "sandbox.list",
      "full_path": "nullspace sandbox list",
      "summary": "List all running sandboxes.",
      "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 sandbox.list
full_path: shell command path, for example nullspace sandbox 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.