core-lightning/doc/schemas/lightning-commando.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "commando",
  "title": "Command to Send a Command to a Remote Peer",
  "description": [
    "The **commando** RPC command is a homage to bad 80s movies. It also sends a directly-connected *peer_id* a custom message, containing a request to run *method* (with an optional dictionary of *params*); generally the peer will only allow you to run a command if it has provided you with a *rune* which allows it."
  ],
  "request": {
    "required": [
      "peer_id",
      "method"
    ],
    "additionalProperties": false,
    "properties": {
      "peer_id": {
        "type": "pubkey",
        "description": [
          "Peer to command."
        ]
      },
      "method": {
        "type": "string",
        "description": [
          "Method to invoke on peer."
        ]
      },
      "params": {
        "oneOf": [
          {
            "type": "array",
            "description": [
              "Array of positional parameters."
            ]
          },
          {
            "type": "object",
            "description": [
              "Parameters for method."
            ]
          }
        ]
      },
      "rune": {
        "type": "string",
        "description": [
          "Rune to authorize the command."
        ]
      },
      "filter": {
        "type": "object",
        "description": [
          "Filter to peer to apply to any successful result."
        ]
      }
    }
  },
  "response": {
    "required": [],
    "additionalProperties": true,
    "properties": {},
    "pre_return_value_notes": [
      "On success, the return depends on the *method* invoked."
    ]
  },
  "errors": [
    "On failure, one of the following error codes may be returned:",
    "",
    "- -32600: Usually means peer is not connected",
    "- 19535: the local commando plugin discovered an error.",
    "- 19536: the remote commando plugin discovered an error.",
    "- 19537: the remote commando plugin said we weren't authorized.",
    "",
    "It can also fail if the peer does not respond, in which case it will simply hang awaiting a response."
  ],
  "author": [
    "Rusty Russell <<rusty@rustcorp.com.au>> wrote the original Python commando.py plugin, the in-tree commando plugin, and this manual page.",
    "",
    "Christian Decker came up with the name \"commando\", which almost excuses his previous adoption of the name \"Eltoo\"."
  ],
  "see_also": [
    "lightning-commando-rune(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:commando#1",
        "method": "commando",
        "params": {
          "peer_id": "nodeid020202020202020202020202020202020202020202020202020202020202",
          "rune": "_RWaZZRI7wAYU2hqlFBmYgC_dFczcpAdI_9O87YbDpg9MCZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5Jm1ldGhvZC9saXN0ZGF0YXN0b3Jl",
          "method": "getinfo",
          "params": {}
        }
      },
      "response": {
        "id": "nodeid020202020202020202020202020202020202020202020202020202020202",
        "alias": "SILENTARTIST",
        "color": "022d22",
        "num_peers": 3,
        "num_pending_channels": 0,
        "num_active_channels": 3,
        "num_inactive_channels": 1,
        "address": [],
        "binding": [
          {
            "type": "ipv4",
            "address": "127.0.0.1",
            "port": 19735
          }
        ],
        "version": "v24.11rc1",
        "blockheight": 130,
        "network": "regtest",
        "fees_collected_msat": 106,
        "lightning-dir": "/tmp/.lightning/regtest",
        "our_features": {
          "init": "08a0882a8a59a1",
          "node": "88a0882a8a59a1",
          "channel": "",
          "invoice": "02000002024100"
        }
      }
    },
    {
      "request": {
        "id": "example:commando#2",
        "method": "commando",
        "params": {
          "peer_id": "nodeid020202020202020202020202020202020202020202020202020202020202",
          "rune": "RXgu0DD_i0wSPEZkIDyZIWL0bSAGdhvJ_GHOQdTg04A9MSZpZF4wMjY2ZTQ1OThkMWQzYzQxNWY1NyZtZXRob2Q9bGlzdHBlZXJz",
          "method": "listpeers",
          "params": [
            "nodeid030303030303030303030303030303030303030303030303030303030303"
          ]
        }
      },
      "response": {
        "peers": [
          {
            "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
            "connected": true,
            "num_channels": 2,
            "netaddr": [
              "127.0.0.1:19736"
            ],
            "features": "08a0882a8a59a1"
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:commando#3",
        "method": "commando",
        "params": {
          "peer_id": "nodeid020202020202020202020202020202020202020202020202020202020202",
          "rune": "QUJEYMLGgiaJvMDv_MhR2hiMKIBTbq-PrL-KxcIlirQ9MiZtZXRob2Q9cGF5JnBuYW1lYW1vdW50bXNhdDwxMDAwMA==",
          "method": "pay",
          "params": {
            "bolt11": "lnbcrt100n1pnt2bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000bolt11invl020300000000",
            "amount_msat": 9900
          }
        }
      },
      "response": {
        "destination": "nodeid020202020202020202020202020202020202020202020202020202020202",
        "payment_hash": "paymenthashcmdpycp10cp10cp10cp10cp10cp10cp10cp10cp10cp10cp10cp10",
        "created_at": 1738000000,
        "parts": 1,
        "amount_msat": 9900,
        "amount_sent_msat": 9900,
        "payment_preimage": "paymentpreimagec010101010101010101010101010101010101010101010101",
        "status": "complete"
      }
    }
  ]
}