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.
- runbook_py-1.0.0/CHANGELOG.md +16 -0
- runbook_py-1.0.0/LICENSE +21 -0
- runbook_py-1.0.0/MANIFEST.in +6 -0
- runbook_py-1.0.0/PKG-INFO +225 -0
- runbook_py-1.0.0/README.md +199 -0
- runbook_py-1.0.0/docs/ai-assistants.md +63 -0
- runbook_py-1.0.0/examples/debian-upgrade-check.json +19 -0
- runbook_py-1.0.0/examples/hello.json +13 -0
- runbook_py-1.0.0/examples/per-host-vars.json +13 -0
- runbook_py-1.0.0/pyproject.toml +45 -0
- runbook_py-1.0.0/schema/runbook-plan.schema.json +321 -0
- runbook_py-1.0.0/scripts/gen_schema.py +13 -0
- runbook_py-1.0.0/setup.cfg +4 -0
- runbook_py-1.0.0/src/runbook_py/__init__.py +4 -0
- runbook_py-1.0.0/src/runbook_py/__main__.py +5 -0
- runbook_py-1.0.0/src/runbook_py/cli.py +266 -0
- runbook_py-1.0.0/src/runbook_py/config.py +168 -0
- runbook_py-1.0.0/src/runbook_py/plan.py +307 -0
- runbook_py-1.0.0/src/runbook_py/report.py +76 -0
- runbook_py-1.0.0/src/runbook_py/runner.py +538 -0
- runbook_py-1.0.0/src/runbook_py/schema.py +76 -0
- runbook_py-1.0.0/src/runbook_py/util.py +111 -0
- runbook_py-1.0.0/src/runbook_py.egg-info/PKG-INFO +225 -0
- runbook_py-1.0.0/src/runbook_py.egg-info/SOURCES.txt +27 -0
- runbook_py-1.0.0/src/runbook_py.egg-info/dependency_links.txt +1 -0
- runbook_py-1.0.0/src/runbook_py.egg-info/entry_points.txt +2 -0
- runbook_py-1.0.0/src/runbook_py.egg-info/top_level.txt +1 -0
- runbook_py-1.0.0/tests/conftest.py +47 -0
- runbook_py-1.0.0/tests/test_runbook.py +285 -0
|
@@ -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).
|
runbook_py-1.0.0/LICENSE
ADDED
|
@@ -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,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"]
|