help

The help command asks the server to describe itself: which commands it accepts, what each one does, and how to call it. Use it to explore the API interactively, or to check what a particular server supports before writing against it.


Command Type	DisplayNet
Minimum Version	4.6

Usage

Listing every command family:

help

Describing one family in detail:

help <command>

Arguments

Argument	Required	Description
`command`	No	A command family to describe. When omitted, all families are listed.

Examples

List every command family
help

Describe the preset family
help preset

Return value

Listing families

help with no argument returns a commands array, one entry per command family, alphabetical by name.

help
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "commands": [
      {
        "command": "auth",
        "description": "Authorize a device against the server's device auth key",
        "subcommands": []
      },
      {
        "command": "authkey",
        "description": "SSH public key management for server access",
        "subcommands": [
          "add",
          "list",
          "remove"
        ]
      },
      {
        "command": "backup",
        "description": "Encrypted server configuration backup and restore",
        "subcommands": [
          "backup",
          "readbackup",
          "restore"
        ]
      }
    ]
  },
  "error": null
}

Field	Description
`command`	The command family name
`description`	What the family is for
`subcommands`	The family's subcommands. Empty when the command takes arguments directly

Describing one family

help <command> returns a command_help array, one entry per subcommand.

help preset
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "command_help": [
      {
        "command": "preset",
        "subcommand": "get",
        "aliases": [],
        "description": "Get a preset's contents (snapshot or script)",
        "usage": "preset get <name>",
        "parameters": [
          {
            "name": "name",
            "type": "string",
            "optional": false,
            "rest": false,
            "description": ""
          }
        ]
      },
      {
        "command": "preset",
        "subcommand": "rename",
        "aliases": [],
        "description": "Rename a preset (snapshot or script)",
        "usage": "preset rename <old_name> <new_name>",
        "parameters": [
          {
            "name": "old_name",
            "type": "string",
            "optional": false,
            "rest": false,
            "description": ""
          },
          {
            "name": "new_name",
            "type": "string",
            "optional": false,
            "rest": false,
            "description": ""
          }
        ]
      }
    ]
  },
  "error": null
}

Field	Description
`command`	The command family
`subcommand`	The subcommand this entry describes
`aliases`	Alternative spellings the subcommand also answers to
`description`	What the subcommand does
`usage`	A generated synopsis. Required arguments in `<angle brackets>`, optional in `[square brackets]`
`parameters`	One entry per argument, in the order they are given
`parameters[].name`	The argument name
`parameters[].type`	The value type, such as `string` or `int`
`parameters[].optional`	Whether the argument may be omitted
`parameters[].rest`	When true, this argument captures everything remaining
`parameters[].description`	What the argument means. May be empty

A subcommand with an alias reports it, so a legacy spelling can be recognised:

An aliased subcommand
{
  "command": "preset",
  "subcommand": "run",
  "aliases": [
    "load"
  ],
  "description": "Run a preset: apply a snapshot or start a script task ('load' is the legacy alias)",
  "usage": "preset run <name>"
}

Coverage

The server generates help at runtime, so it always matches the version you are connected to. A few commands are not described by it: they are absent from the listing, and asking about one returns an error.

help version
{
  "status": "ERROR",
  "request_id": null,
  "result": null,
  "error": {
    "message": "Unknown command 'version' (only registry-dispatched commands are described; see the API documentation for others)",
    "reason": "HELP API ERROR"
  }
}

A command absent from help is still supported. This manual covers them all.

Errors

Error	Cause
`Unknown command '<name>'`	No such family, or the command is not registry-dispatched

REST API

Endpoint type	DisplayNet API command
Address	`POST /api/displaynet/<operation>`, or name the operation in the body of a `POST /api/displaynet`. See Sending commands.
Role	`User`

Operation	Parameters
`help`	`[command]`

A parameter in brackets is optional.

Usage​

Arguments​

Examples​

Return value​

Listing families​

Describing one family​

Coverage​

Errors​

REST API​

See also​