runbook-py 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ ## 1.0.0 — 2026-11-19
4
+
5
+ First public release, from the internal `runbook.py` script used for a Proxmox VE 8 → 9 migration.
6
+
7
+ - Plans in JSON, one JSON report per run, rewritten after each command.
8
+ - English console and prompts: `Run? [y/N/a/q]`.
9
+ - `.runbook.ini` configuration (`/etc`, `~`, `./`, `$RUNBOOK_CONFIG`, `--config`) with a `[vars]` section.
10
+ - `{{variables}}`: built-ins, plan `vars`, config `[vars]`, `--var`.
11
+ - `capture`, `skip_if`, `only_if` with several ids, `retries`, `stdin`, `requires`.
12
+ - `--from`, `--only`, `--skip`, `--resume previous.result.json`.
13
+ - Live output while capturing, ANSI and carriage-return clean-up, head + tail truncation.
14
+ - Lock file against parallel runs; SIGTERM handled like Ctrl-C.
15
+ - Subcommands: `run` (default), `validate`, `report` (text / Markdown), `schema`, `init-config`.
16
+ - Exit codes: 0, 1, 2, 3 (requirements), 4 (locked), 130 (interrupted).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Emmanuel Bocquet
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,6 @@
1
+ include README.md CHANGELOG.md LICENSE
2
+ recursive-include tests *.py
3
+ recursive-include examples *.json
4
+ recursive-include schema *.json
5
+ recursive-include docs *.md
6
+ recursive-include scripts *.py
@@ -0,0 +1,225 @@
1
+ Metadata-Version: 2.4
2
+ Name: runbook-py
3
+ Version: 1.0.0
4
+ Summary: Run a JSON plan of shell commands and get a complete JSON report back (rc, stdout, stderr, duration). Built for humans and AI assistants working together on servers.
5
+ Author-email: Emmanuel Bocquet <manu@unixdev.ca>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/OWNER/runbook-py
8
+ Project-URL: Source, https://github.com/OWNER/runbook-py
9
+ Project-URL: Issues, https://github.com/OWNER/runbook-py/issues
10
+ Project-URL: Changelog, https://github.com/OWNER/runbook-py/blob/main/CHANGELOG.md
11
+ Keywords: runbook,sysadmin,shell,automation,devops,json,llm,ops
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: System Administrators
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Operating System :: MacOS
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Topic :: System :: Systems Administration
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.6
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Dynamic: license-file
26
+
27
+ # runbook-py
28
+
29
+ **Run a JSON plan of shell commands. Get one JSON report back.**
30
+
31
+ `runbook` executes the commands of a plan in order and records, for each one, the exit code, stdout,
32
+ stderr, duration and status. It was born from a simple workflow: an AI assistant (or a colleague)
33
+ writes the plan, you review and run it on the server, and you hand back a single
34
+ `.result.json` file instead of copy-pasting terminal output.
35
+
36
+ ```console
37
+ $ runbook hello.json
38
+ ▶ hello — 5 command(s) on web01
39
+ [1/5] whoami $ id; hostname; uptime
40
+ │ uid=0(root) gid=0(root) groups=0(root)
41
+ │ web01
42
+ → ok rc=0 0.01s
43
+ [3/5] kernel $ uname -r
44
+ │ 6.8.12-4-pve
45
+ → ok rc=0 0.00s
46
+ ...
47
+ ■ Done in 0.2s — ok=5
48
+ /root/hello_web01_20261119-091500.result.json
49
+ ```
50
+
51
+ - **No dependencies**, one command, Python 3.6+ (Debian, Ubuntu, Proxmox, RHEL/Rocky 8+, macOS).
52
+ - **Safe by default**: commands marked `"dangerous": true` ask for confirmation; stdin is closed, so
53
+ nothing hangs on a prompt; every command has a timeout that kills its whole process group.
54
+ - **Complete, honest report**: exit codes, both streams, durations, the host, the OS, the plan's
55
+ SHA-256. It is rewritten after every command, so even a Ctrl-C leaves a usable partial report.
56
+ - **Built for review**: secrets masked by regex, ANSI codes and progress bars cleaned up, huge outputs
57
+ kept as head + tail.
58
+
59
+ ## Install
60
+
61
+ ```bash
62
+ pipx install runbook-py # recommended: isolated, puts `runbook` in your PATH
63
+ # or
64
+ python3 -m pip install --user runbook-py
65
+ ```
66
+
67
+ On Debian 12+ / Ubuntu 23.04+, plain `pip install` outside a virtualenv is refused (PEP 668): use
68
+ `pipx` (`apt install pipx`). On RHEL/Rocky 8 (Python 3.6, pip 9), upgrade pip first:
69
+ `python3 -m pip install --user --upgrade pip`.
70
+
71
+ ## A plan
72
+
73
+ ```json
74
+ {
75
+ "name": "nginx-check",
76
+ "description": "Check nginx and reload it if the configuration is valid",
77
+ "requires": { "root": true, "commands": ["nginx"] },
78
+ "defaults": { "timeout": 30, "stop_on_error": true },
79
+ "commands": [
80
+ { "id": "status", "cmd": "systemctl is-active nginx", "expect_rc": [0, 3] },
81
+ { "id": "test", "cmd": "nginx -t" },
82
+ { "id": "reload", "cmd": "systemctl reload nginx", "dangerous": true, "only_if": "test" }
83
+ ]
84
+ }
85
+ ```
86
+
87
+ ```bash
88
+ runbook validate plan.json # structure, ids, variables; runs nothing
89
+ runbook plan.json --dry-run # shows what would run
90
+ runbook plan.json # runs it; prints the path of the result file on stdout
91
+ runbook report plan_web01_20261119-091500.result.json
92
+ ```
93
+
94
+ ### Command fields
95
+
96
+ | Field | Default | Meaning |
97
+ | --- | --- | --- |
98
+ | `id` | `cmdN` | Unique name, used by `only_if`, `--from`, `--only`, `--skip`, the report |
99
+ | `cmd` | required | String run with `bash -c` (or `sh -c`), or an argv list when `"shell": false` |
100
+ | `description` | | Shown at confirmation and in the report |
101
+ | `timeout` | `60` | Seconds; `0` or `null` = no limit. The process group is killed (SIGTERM, then SIGKILL) |
102
+ | `stop_on_error` | `true` | A failure, timeout or start error skips the rest of the plan |
103
+ | `expect_rc` | `[0]` | Exit codes that count as success |
104
+ | `dangerous` | `false` | Changes the system: asks first (with the default `--confirm dangerous`) |
105
+ | `only_if` | | Id(s) of earlier commands that must have ended `ok` |
106
+ | `skip_if` | | Shell test run first; exit code 0 = already done, the command is skipped |
107
+ | `capture` | | Saves stdout as `{{NAME}}` and `$NAME` for later commands |
108
+ | `retries`, `retry_delay` | `0`, `5` | Extra attempts after a failure or a timeout |
109
+ | `stdin` | | Text sent to the command's standard input (otherwise `/dev/null`) |
110
+ | `cwd`, `env` | | Working directory, extra environment variables |
111
+ | `shell` | `true` | `false` runs `cmd` as an argv list without a shell |
112
+ | `stream` | | Force live output on or off for this command |
113
+
114
+ Every field except `id`, `cmd`, `description`, `only_if`, `skip_if`, `capture` and `stdin` can be set
115
+ once in `"defaults"`. Plan-level keys: `name`, `description`, `defaults`, `vars`, `redact`,
116
+ `requires` (`root`, `os`, `commands`), `commands`. The full JSON Schema: `runbook schema`, also in
117
+ [`schema/runbook-plan.schema.json`](schema/runbook-plan.schema.json).
118
+
119
+ ### Statuses
120
+
121
+ `ok`, `failed` (exit code not in `expect_rc`), `timeout`, `error` (could not start, undefined
122
+ variable), `skipped` (with a `reason`), `declined` (answered *no* at the confirmation).
123
+
124
+ ## Variables and captures
125
+
126
+ `{{name}}` is replaced in `cmd`, `cwd`, `env`, `skip_if` and `stdin`. Sources, lowest priority first:
127
+
128
+ 1. built-ins: `host`, `fqdn`, `user`, `date` (YYYYMMDD), `time`, `timestamp`, `plan_name`
129
+ 2. the plan's `"vars"`
130
+ 3. `[vars]` in `.runbook.ini`: host-specific values, so one plan serves many servers
131
+ 4. `--var NAME=VALUE`
132
+
133
+ A command with `"capture": "NAME"` stores its stdout (trailing newlines removed) for the commands
134
+ after it, both as `{{NAME}}` and as the environment variable `$NAME`:
135
+
136
+ ```json
137
+ { "id": "esp", "cmd": "findmnt -no SOURCE /boot/efi", "capture": "ESP" },
138
+ { "id": "show", "cmd": "lsblk {{ESP}}", "only_if": "esp" }
139
+ ```
140
+
141
+ `runbook validate` rejects a variable that no source defines, including one captured only *later*.
142
+
143
+ ## Re-running part of a plan
144
+
145
+ ```bash
146
+ runbook plan.json --from upgrade # start at a command
147
+ runbook plan.json --only update,pending # run only these
148
+ runbook plan.json --skip reboot # everything but these
149
+ runbook plan.json --resume previous.result.json # skip what was ok, rerun the rest
150
+ ```
151
+
152
+ `--resume` also restores the values captured in the previous run. Plans written with `skip_if` can
153
+ simply be run again.
154
+
155
+ ## Confirmation
156
+
157
+ With `--confirm dangerous` (default), each `"dangerous": true` command shows its description and
158
+ command line and asks `Run? [y/N/a/q]`: **y** runs it, **N** (or Enter) skips it (`declined`),
159
+ **a** runs it and every following command without asking, **q** stops the plan. `--confirm all` asks
160
+ for every command; `-y` / `--confirm none` never asks. Without a terminal, dangerous commands are
161
+ declined, never run silently.
162
+
163
+ ## Configuration: `.runbook.ini`
164
+
165
+ Read in this order, later files overriding earlier ones: `/etc/runbook.ini`, `~/.runbook.ini`,
166
+ `./.runbook.ini`, then `$RUNBOOK_CONFIG` or `--config FILE`. Command-line options override everything.
167
+ `runbook init-config ~/.runbook.ini` writes a commented template.
168
+
169
+ ```ini
170
+ [runbook]
171
+ output_dir = /root/runbook-results
172
+ max_output = 65536 ; bytes kept per stream (head + tail), 0 = all
173
+ confirm = dangerous ; none | dangerous | all
174
+ timeout = 60
175
+ stream = auto ; live output: auto | true | false
176
+ color = auto ; auto | always | never (NO_COLOR honoured)
177
+ strip_ansi = true
178
+ redact =
179
+ (?i)(password|passwd|secret|token)\s*[:=]\s*\S+
180
+
181
+ [vars]
182
+ backup_dir = /srv/backups
183
+ ```
184
+
185
+ Unknown keys are errors, so a typo never goes unnoticed.
186
+
187
+ ## The report
188
+
189
+ ```json
190
+ {
191
+ "runbook_version": "1.0.0", "schema_version": 1,
192
+ "plan_name": "nginx-check", "plan_sha256": "…", "host": "web01", "os": "Debian GNU/Linux 13 (trixie)",
193
+ "started": "2026-11-19T09:15:00-05:00", "duration_s": 0.4, "stopped_at": null, "interrupted": false,
194
+ "summary": { "ok": 3, "total": 3 },
195
+ "results": [
196
+ { "id": "test", "cmd": "nginx -t", "status": "ok", "rc": 0, "duration_s": 0.05, "attempts": 1,
197
+ "stdout": "", "stderr": "nginx: configuration file /etc/nginx/nginx.conf test is successful\n",
198
+ "stdout_bytes": 0, "stderr_bytes": 64, "truncated": false }
199
+ ]
200
+ }
201
+ ```
202
+
203
+ `runbook report FILE` prints a summary table with the output of failed commands;
204
+ `--format markdown` gives the same for a ticket or a chat.
205
+
206
+ ## Exit codes
207
+
208
+ | Code | Meaning |
209
+ | --- | --- |
210
+ | 0 | every command ended `ok` (or was skipped) |
211
+ | 1 | at least one command `failed`, timed out or could not start |
212
+ | 2 | invalid plan, configuration or arguments |
213
+ | 3 | `requires` not met: nothing was run |
214
+ | 4 | another run holds the lock (`--no-lock` to bypass) |
215
+ | 130 | interrupted (Ctrl-C or SIGTERM); the partial report is written |
216
+
217
+ ## Working with an AI assistant
218
+
219
+ The format is meant to be written by a language model and reviewed by a human. See
220
+ [docs/ai-assistants.md](docs/ai-assistants.md) for a ready-to-paste instruction block and the rules
221
+ that make generated plans safe to run.
222
+
223
+ ## License
224
+
225
+ MIT, © Emmanuel Bocquet.
@@ -0,0 +1,199 @@
1
+ # runbook-py
2
+
3
+ **Run a JSON plan of shell commands. Get one JSON report back.**
4
+
5
+ `runbook` executes the commands of a plan in order and records, for each one, the exit code, stdout,
6
+ stderr, duration and status. It was born from a simple workflow: an AI assistant (or a colleague)
7
+ writes the plan, you review and run it on the server, and you hand back a single
8
+ `.result.json` file instead of copy-pasting terminal output.
9
+
10
+ ```console
11
+ $ runbook hello.json
12
+ ▶ hello — 5 command(s) on web01
13
+ [1/5] whoami $ id; hostname; uptime
14
+ │ uid=0(root) gid=0(root) groups=0(root)
15
+ │ web01
16
+ → ok rc=0 0.01s
17
+ [3/5] kernel $ uname -r
18
+ │ 6.8.12-4-pve
19
+ → ok rc=0 0.00s
20
+ ...
21
+ ■ Done in 0.2s — ok=5
22
+ /root/hello_web01_20261119-091500.result.json
23
+ ```
24
+
25
+ - **No dependencies**, one command, Python 3.6+ (Debian, Ubuntu, Proxmox, RHEL/Rocky 8+, macOS).
26
+ - **Safe by default**: commands marked `"dangerous": true` ask for confirmation; stdin is closed, so
27
+ nothing hangs on a prompt; every command has a timeout that kills its whole process group.
28
+ - **Complete, honest report**: exit codes, both streams, durations, the host, the OS, the plan's
29
+ SHA-256. It is rewritten after every command, so even a Ctrl-C leaves a usable partial report.
30
+ - **Built for review**: secrets masked by regex, ANSI codes and progress bars cleaned up, huge outputs
31
+ kept as head + tail.
32
+
33
+ ## Install
34
+
35
+ ```bash
36
+ pipx install runbook-py # recommended: isolated, puts `runbook` in your PATH
37
+ # or
38
+ python3 -m pip install --user runbook-py
39
+ ```
40
+
41
+ On Debian 12+ / Ubuntu 23.04+, plain `pip install` outside a virtualenv is refused (PEP 668): use
42
+ `pipx` (`apt install pipx`). On RHEL/Rocky 8 (Python 3.6, pip 9), upgrade pip first:
43
+ `python3 -m pip install --user --upgrade pip`.
44
+
45
+ ## A plan
46
+
47
+ ```json
48
+ {
49
+ "name": "nginx-check",
50
+ "description": "Check nginx and reload it if the configuration is valid",
51
+ "requires": { "root": true, "commands": ["nginx"] },
52
+ "defaults": { "timeout": 30, "stop_on_error": true },
53
+ "commands": [
54
+ { "id": "status", "cmd": "systemctl is-active nginx", "expect_rc": [0, 3] },
55
+ { "id": "test", "cmd": "nginx -t" },
56
+ { "id": "reload", "cmd": "systemctl reload nginx", "dangerous": true, "only_if": "test" }
57
+ ]
58
+ }
59
+ ```
60
+
61
+ ```bash
62
+ runbook validate plan.json # structure, ids, variables; runs nothing
63
+ runbook plan.json --dry-run # shows what would run
64
+ runbook plan.json # runs it; prints the path of the result file on stdout
65
+ runbook report plan_web01_20261119-091500.result.json
66
+ ```
67
+
68
+ ### Command fields
69
+
70
+ | Field | Default | Meaning |
71
+ | --- | --- | --- |
72
+ | `id` | `cmdN` | Unique name, used by `only_if`, `--from`, `--only`, `--skip`, the report |
73
+ | `cmd` | required | String run with `bash -c` (or `sh -c`), or an argv list when `"shell": false` |
74
+ | `description` | | Shown at confirmation and in the report |
75
+ | `timeout` | `60` | Seconds; `0` or `null` = no limit. The process group is killed (SIGTERM, then SIGKILL) |
76
+ | `stop_on_error` | `true` | A failure, timeout or start error skips the rest of the plan |
77
+ | `expect_rc` | `[0]` | Exit codes that count as success |
78
+ | `dangerous` | `false` | Changes the system: asks first (with the default `--confirm dangerous`) |
79
+ | `only_if` | | Id(s) of earlier commands that must have ended `ok` |
80
+ | `skip_if` | | Shell test run first; exit code 0 = already done, the command is skipped |
81
+ | `capture` | | Saves stdout as `{{NAME}}` and `$NAME` for later commands |
82
+ | `retries`, `retry_delay` | `0`, `5` | Extra attempts after a failure or a timeout |
83
+ | `stdin` | | Text sent to the command's standard input (otherwise `/dev/null`) |
84
+ | `cwd`, `env` | | Working directory, extra environment variables |
85
+ | `shell` | `true` | `false` runs `cmd` as an argv list without a shell |
86
+ | `stream` | | Force live output on or off for this command |
87
+
88
+ Every field except `id`, `cmd`, `description`, `only_if`, `skip_if`, `capture` and `stdin` can be set
89
+ once in `"defaults"`. Plan-level keys: `name`, `description`, `defaults`, `vars`, `redact`,
90
+ `requires` (`root`, `os`, `commands`), `commands`. The full JSON Schema: `runbook schema`, also in
91
+ [`schema/runbook-plan.schema.json`](schema/runbook-plan.schema.json).
92
+
93
+ ### Statuses
94
+
95
+ `ok`, `failed` (exit code not in `expect_rc`), `timeout`, `error` (could not start, undefined
96
+ variable), `skipped` (with a `reason`), `declined` (answered *no* at the confirmation).
97
+
98
+ ## Variables and captures
99
+
100
+ `{{name}}` is replaced in `cmd`, `cwd`, `env`, `skip_if` and `stdin`. Sources, lowest priority first:
101
+
102
+ 1. built-ins: `host`, `fqdn`, `user`, `date` (YYYYMMDD), `time`, `timestamp`, `plan_name`
103
+ 2. the plan's `"vars"`
104
+ 3. `[vars]` in `.runbook.ini`: host-specific values, so one plan serves many servers
105
+ 4. `--var NAME=VALUE`
106
+
107
+ A command with `"capture": "NAME"` stores its stdout (trailing newlines removed) for the commands
108
+ after it, both as `{{NAME}}` and as the environment variable `$NAME`:
109
+
110
+ ```json
111
+ { "id": "esp", "cmd": "findmnt -no SOURCE /boot/efi", "capture": "ESP" },
112
+ { "id": "show", "cmd": "lsblk {{ESP}}", "only_if": "esp" }
113
+ ```
114
+
115
+ `runbook validate` rejects a variable that no source defines, including one captured only *later*.
116
+
117
+ ## Re-running part of a plan
118
+
119
+ ```bash
120
+ runbook plan.json --from upgrade # start at a command
121
+ runbook plan.json --only update,pending # run only these
122
+ runbook plan.json --skip reboot # everything but these
123
+ runbook plan.json --resume previous.result.json # skip what was ok, rerun the rest
124
+ ```
125
+
126
+ `--resume` also restores the values captured in the previous run. Plans written with `skip_if` can
127
+ simply be run again.
128
+
129
+ ## Confirmation
130
+
131
+ With `--confirm dangerous` (default), each `"dangerous": true` command shows its description and
132
+ command line and asks `Run? [y/N/a/q]`: **y** runs it, **N** (or Enter) skips it (`declined`),
133
+ **a** runs it and every following command without asking, **q** stops the plan. `--confirm all` asks
134
+ for every command; `-y` / `--confirm none` never asks. Without a terminal, dangerous commands are
135
+ declined, never run silently.
136
+
137
+ ## Configuration: `.runbook.ini`
138
+
139
+ Read in this order, later files overriding earlier ones: `/etc/runbook.ini`, `~/.runbook.ini`,
140
+ `./.runbook.ini`, then `$RUNBOOK_CONFIG` or `--config FILE`. Command-line options override everything.
141
+ `runbook init-config ~/.runbook.ini` writes a commented template.
142
+
143
+ ```ini
144
+ [runbook]
145
+ output_dir = /root/runbook-results
146
+ max_output = 65536 ; bytes kept per stream (head + tail), 0 = all
147
+ confirm = dangerous ; none | dangerous | all
148
+ timeout = 60
149
+ stream = auto ; live output: auto | true | false
150
+ color = auto ; auto | always | never (NO_COLOR honoured)
151
+ strip_ansi = true
152
+ redact =
153
+ (?i)(password|passwd|secret|token)\s*[:=]\s*\S+
154
+
155
+ [vars]
156
+ backup_dir = /srv/backups
157
+ ```
158
+
159
+ Unknown keys are errors, so a typo never goes unnoticed.
160
+
161
+ ## The report
162
+
163
+ ```json
164
+ {
165
+ "runbook_version": "1.0.0", "schema_version": 1,
166
+ "plan_name": "nginx-check", "plan_sha256": "…", "host": "web01", "os": "Debian GNU/Linux 13 (trixie)",
167
+ "started": "2026-11-19T09:15:00-05:00", "duration_s": 0.4, "stopped_at": null, "interrupted": false,
168
+ "summary": { "ok": 3, "total": 3 },
169
+ "results": [
170
+ { "id": "test", "cmd": "nginx -t", "status": "ok", "rc": 0, "duration_s": 0.05, "attempts": 1,
171
+ "stdout": "", "stderr": "nginx: configuration file /etc/nginx/nginx.conf test is successful\n",
172
+ "stdout_bytes": 0, "stderr_bytes": 64, "truncated": false }
173
+ ]
174
+ }
175
+ ```
176
+
177
+ `runbook report FILE` prints a summary table with the output of failed commands;
178
+ `--format markdown` gives the same for a ticket or a chat.
179
+
180
+ ## Exit codes
181
+
182
+ | Code | Meaning |
183
+ | --- | --- |
184
+ | 0 | every command ended `ok` (or was skipped) |
185
+ | 1 | at least one command `failed`, timed out or could not start |
186
+ | 2 | invalid plan, configuration or arguments |
187
+ | 3 | `requires` not met: nothing was run |
188
+ | 4 | another run holds the lock (`--no-lock` to bypass) |
189
+ | 130 | interrupted (Ctrl-C or SIGTERM); the partial report is written |
190
+
191
+ ## Working with an AI assistant
192
+
193
+ The format is meant to be written by a language model and reviewed by a human. See
194
+ [docs/ai-assistants.md](docs/ai-assistants.md) for a ready-to-paste instruction block and the rules
195
+ that make generated plans safe to run.
196
+
197
+ ## License
198
+
199
+ MIT, © Emmanuel Bocquet.
@@ -0,0 +1,63 @@
1
+ # Generating plans with an AI assistant
2
+
3
+ runbook-py started as the glue between a sysadmin and an AI assistant: instead of "run these
4
+ twelve commands and paste me the output", the assistant writes a plan, the human reviews and runs
5
+ it, and the assistant reads one `.result.json` file. The loop is short, nothing gets lost in
6
+ copy-paste, and every exit code is visible.
7
+
8
+ ## The loop
9
+
10
+ 1. Describe the goal and the server to the assistant.
11
+ 2. It answers with a plan file. Read it, or at least `runbook validate plan.json` and
12
+ `runbook plan.json --dry-run`.
13
+ 3. Run it: `runbook plan.json`. Answer the confirmations for `dangerous` commands.
14
+ 4. Give the `.result.json` file back to the assistant. It reads the results and proposes the next plan.
15
+
16
+ Start with a read-only inventory plan: the assistant then writes the following plans against the
17
+ real state of the machine instead of guessing.
18
+
19
+ ## Instructions to paste into your assistant
20
+
21
+ Put this in your assistant's custom instructions, project instructions or memory:
22
+
23
+ ```text
24
+ When I need to run commands on one of my machines, do not give me commands to copy and paste.
25
+ Write a runbook-py plan (JSON) that I will run with `runbook plan.json`; I will send you back
26
+ the .result.json file it produces.
27
+
28
+ Rules for plans:
29
+ - Top level: "name", "description", optional "defaults", "vars", "redact", "requires", and "commands".
30
+ - Each command: "id" (short, unique), "cmd", and when useful "description", "timeout",
31
+ "stop_on_error", "expect_rc", "only_if", "skip_if", "capture", "retries", "env", "cwd", "stdin".
32
+ - Mark "dangerous": true on every command that changes the system (writes files, installs,
33
+ restarts services, reboots, deletes). Read-only commands are never dangerous.
34
+ - Stdin is /dev/null: never use interactive commands; add -y / --non-interactive flags.
35
+ - Use "expect_rc" when a non-zero exit code is a normal answer (grep: [0, 1]; systemctl is-active: [0, 3]).
36
+ - Use "stop_on_error": false for independent read-only checks, true before anything that depends on them.
37
+ - Use "only_if" to chain a step to the success of an earlier one, "skip_if" to make a step idempotent,
38
+ "capture" to reuse an output in later steps ({{NAME}} or $NAME), instead of repeating a pipeline.
39
+ - Put host-specific values in "vars" with {{name}} so the same plan works on several servers.
40
+ - Long or risky operations (dist-upgrade, migrations) go in their own plan, with a preflight plan
41
+ before them and a verification plan after them.
42
+ - Never put secrets in a plan; add "redact" regexes when an output may contain one.
43
+ - Reboots are left to the human, outside the plan.
44
+ ```
45
+
46
+ ## Things worth asking the assistant to check in a result
47
+
48
+ - `summary` first, then every entry whose `status` is not `ok`.
49
+ - `stderr` of commands that ended `ok`: warnings often hide there.
50
+ - `truncated: true`: the output was cut to head + tail; ask for a narrower command if the middle matters.
51
+ - `plan_sha256`: proves which version of the plan produced the result.
52
+
53
+ ## Validating generated plans
54
+
55
+ `runbook schema` prints the JSON Schema (draft-07). Editors such as VS Code validate and
56
+ autocomplete a plan that starts with:
57
+
58
+ ```json
59
+ { "$schema": "https://raw.githubusercontent.com/OWNER/runbook-py/main/schema/runbook-plan.schema.json" }
60
+ ```
61
+
62
+ `runbook validate` goes further than the schema: it checks that `only_if` names earlier commands
63
+ and that every `{{variable}}` is defined, by the plan, `.runbook.ini`, `--var` or an earlier `capture`.
@@ -0,0 +1,19 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/OWNER/runbook-py/main/schema/runbook-plan.schema.json",
3
+ "name": "debian-upgrade-check",
4
+ "description": "Refresh the package index, list pending upgrades, then upgrade after confirmation.",
5
+ "requires": { "root": true, "os": ["debian", "ubuntu"], "commands": ["apt-get"] },
6
+ "defaults": { "timeout": 600, "env": { "DEBIAN_FRONTEND": "noninteractive", "LC_ALL": "C" } },
7
+ "redact": ["(?i)(password|passwd|secret|token)\\s*[:=]\\s*\\S+"],
8
+ "commands": [
9
+ { "id": "free_space", "description": "At least 2 GB free on /",
10
+ "cmd": "df -h /; [ $(df --output=avail -k / | tail -1) -gt 2097152 ]" },
11
+ { "id": "update", "cmd": "apt-get update", "dangerous": true, "retries": 2, "retry_delay": 15 },
12
+ { "id": "pending", "cmd": "apt list --upgradable 2>/dev/null | tail -n +2", "only_if": "update" },
13
+ { "id": "upgrade", "description": "Keeps local versions of modified config files",
14
+ "cmd": "apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold dist-upgrade",
15
+ "dangerous": true, "only_if": "update", "timeout": 3600 },
16
+ { "id": "reboot_needed", "cmd": "[ -f /var/run/reboot-required ] && cat /var/run/reboot-required || echo 'no reboot needed'",
17
+ "stop_on_error": false }
18
+ ]
19
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/OWNER/runbook-py/main/schema/runbook-plan.schema.json",
3
+ "name": "hello",
4
+ "description": "A first plan: read-only commands, one expected failure, one capture.",
5
+ "defaults": { "timeout": 30, "stop_on_error": false },
6
+ "commands": [
7
+ { "id": "whoami", "cmd": "id; hostname; uptime" },
8
+ { "id": "disk", "cmd": "df -h /" },
9
+ { "id": "kernel", "cmd": "uname -r", "capture": "KERNEL" },
10
+ { "id": "use_capture", "cmd": "echo \"running kernel {{KERNEL}} on {{host}}\"", "only_if": "kernel" },
11
+ { "id": "expected_fail", "cmd": "ls /does-not-exist", "expect_rc": [0, 2] }
12
+ ]
13
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "$schema": "https://raw.githubusercontent.com/OWNER/runbook-py/main/schema/runbook-plan.schema.json",
3
+ "name": "per-host-vars",
4
+ "description": "One plan for several servers: host-specific values come from [vars] in each server's .runbook.ini or from --var.",
5
+ "vars": { "service": "ssh", "backup_dir": "/root/backups" },
6
+ "commands": [
7
+ { "id": "mkdir", "cmd": "mkdir -p {{backup_dir}}", "skip_if": "test -d {{backup_dir}}", "dangerous": true },
8
+ { "id": "archive", "cmd": "tar czf {{backup_dir}}/etc-{{host}}-{{timestamp}}.tgz /etc 2>/dev/null; ls -t {{backup_dir}} | head -1",
9
+ "capture": "ARCHIVE", "dangerous": true },
10
+ { "id": "size", "cmd": "du -h \"{{backup_dir}}/$ARCHIVE\"", "only_if": "archive" },
11
+ { "id": "service", "cmd": "systemctl is-active {{service}}", "expect_rc": [0, 3] }
12
+ ]
13
+ }
@@ -0,0 +1,45 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "runbook-py"
7
+ dynamic = ["version"]
8
+ description = "Run a JSON plan of shell commands and get a complete JSON report back (rc, stdout, stderr, duration). Built for humans and AI assistants working together on servers."
9
+ readme = "README.md"
10
+ requires-python = ">=3.6"
11
+ license = {text = "MIT"}
12
+ authors = [{name = "Emmanuel Bocquet", email = "manu@unixdev.ca"}]
13
+ keywords = ["runbook", "sysadmin", "shell", "automation", "devops", "json", "llm", "ops"]
14
+ classifiers = [
15
+ "Development Status :: 5 - Production/Stable",
16
+ "Environment :: Console",
17
+ "Intended Audience :: System Administrators",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Operating System :: POSIX :: Linux",
20
+ "Operating System :: MacOS",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3 :: Only",
23
+ "Topic :: System :: Systems Administration",
24
+ "Topic :: Utilities",
25
+ ]
26
+ dependencies = []
27
+
28
+ [project.urls]
29
+ Homepage = "https://github.com/OWNER/runbook-py"
30
+ Source = "https://github.com/OWNER/runbook-py"
31
+ Issues = "https://github.com/OWNER/runbook-py/issues"
32
+ Changelog = "https://github.com/OWNER/runbook-py/blob/main/CHANGELOG.md"
33
+
34
+ [project.scripts]
35
+ runbook = "runbook_py.cli:main"
36
+
37
+ [tool.setuptools.dynamic]
38
+ version = {attr = "runbook_py.__version__"}
39
+
40
+ [tool.setuptools.packages.find]
41
+ where = ["src"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
45
+ pythonpath = ["src", "tests"]