puppet.status

This method is only available when using RVC version 3.13.0 or later.

Reports the current status of the Puppet agent on the node, including the state of any active run, the time of the last and next runs, and who disabled Puppet and why if it is currently disabled. Runs started outside RVC, such as scheduled runs, are also detected.

JSON-RPC Request

{"jsonrpc":"2.0","id":1,"method":"puppet.status"}

JSON-RPC Response

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "state": "<state>",
        "pid": "<pid>",
        "last_run_at": "<timestamp>",
        "environment": "<environment>",
        "disabled_by": "<username>",
        "disabled_at": "<timestamp>",
        "disabled_message": "<text_describing_reason>",
        "next_run_at": "<timestamp>"
    }
}

Response parameters

Values that cannot be determined are returned as null. In the CLI output, fields with no value are not shown.

Parameter	Type	Description
`state`	String	The state of the Puppet agent: `running`, `stopped`, or `disabled`. `running` is reported whenever a run is in progress, even if Puppet is also disabled.
`pid`	Integer	The process ID of the in-progress Puppet run. `null` when no run is in progress. This is the process ID of the Puppet agent, which can differ from the process ID that `rvc puppet run` prints when the run starts.
`last_run_at`	String	The timestamp of the most recent completed Puppet run, in ISO 8601 UTC format.
`environment`	String	The Puppet environment of the in-progress run, or of the last run when no run is in progress.
`disabled_by`	String	The user who disabled Puppet with puppet.disable. `null` when Puppet is enabled, or when it was disabled outside RVC.
`disabled_at`	String	The timestamp indicating when Puppet was disabled, in ISO 8601 UTC format. `null` when Puppet is enabled.
`disabled_message`	String	The reason given when Puppet was disabled. When Puppet was disabled outside RVC, for example with `puppet agent --disable`, the message given to Puppet is reported, or `reason not specified` if no message was given. `null` when Puppet is enabled.
`next_run_at`	String	The timestamp of the next scheduled Puppet run, in ISO 8601 UTC format. `null` when no Puppet run is scheduled. The actual start can be later than this time because of the random wait added before a scheduled run.

The disable details are reported whenever Puppet is disabled, including while a run is in progress. This covers the case where Puppet is disabled during a run to prevent further runs.

RVC CLI Example

rvc puppet status

Response

State......: stopped
Last Run At: 2026-10-09T16:13:46Z
Environment: production
Next Run At: 2026-10-09T16:30:00Z

Output while a run is in progress:

State......: running
Pid........: 28869
Last Run At: 2026-10-09T16:13:46Z
Environment: production
Next Run At: 2026-10-09T16:30:00Z

Output when Puppet is disabled:

State...........: disabled
Last Run At.....: 2026-08-05T21:10:53Z
Environment.....: production
Disabled By.....: test.user
Disabled At.....: 2026-08-06T12:37:29Z
Disabled Message: <text_describing_reason>
Next Run At.....: 2026-08-10T04:00:00Z