Runbook CLI¶
runbook¶
Usage
runbook [OPTIONS] COMMAND [ARGS]...
Options
- --cwd <cwd>¶
Directory for operations (normally at root above runbooks, ie ../.runbook.yaml) and can be set with RUNBOOK_WORKING_DIR or WORKING_DIR environment variables
Environment variables
- ['RUNBOOK_WORKING_DIR', 'WORKING_DIR']
Provide a default for
--cwd
check¶
Check the language validity and formatting of a runbook.
This command validates the syntax and formatting of runbook cells based on the kernel specified in the notebook’s metadata. By default: - For Python kernels: uses ‘black’ to check code formatting - For Deno kernels: uses ‘deno check’ to validate TypeScript/JavaScript
FILENAME: Path to the runbook file to check.
- Options:
- –command, -c: Specify a custom validation command. Use {} as a placeholder for the
filename (e.g., ‘mycheck {} –strict’). This overrides the default checker for the kernel.
- Exit codes:
0: Check passed successfully Non-zero: Check failed, see error output for details
Usage
runbook check [OPTIONS] FILENAME
Options
- -c, --command <command>¶
Run a notebook through this custom command, ie ‘deno check {}’ where the {} is the temporary filename.
Arguments
- FILENAME¶
Required argument
clear-output¶
Clear outputs and execution counts from one or more notebooks (in place).
Usage
runbook clear-output [OPTIONS] NOTEBOOKS...
Arguments
- NOTEBOOKS¶
Required argument(s)
convert¶
Convert a runbook between different formats
This command converts notebooks between various formats using jupytext. Supported conversions include: - .ipynb to .py (Python script) - .ipynb to .ts (Deno notebook) - .ipynb to .md (Markdown) - And other formats supported by jupytext
FILENAME: Path to the source notebook file to convert. OUTPUT: Destination path for the converted file. The format is determined
by the file extension.
- Examples:
runbook convert notebook.ipynb script.py # Convert to Python script runbook convert notebook.ipynb notebook.ts # Convert to Deno notebook runbook convert notebook.ipynb notebook.md # Convert to Markdown
The conversion preserves cell metadata, notebook metadata, and execution outputs where applicable.
Usage
runbook convert [OPTIONS] FILENAME OUTPUT
Arguments
- FILENAME¶
Required argument
- OUTPUT¶
Required argument
create¶
Create a new runbook from a template
This command creates a new runbook using a specified template or language preset. The new runbook will be created in the runbooks/binder directory.
- FILENAME: Name for the new runbook file (e.g., ‘maintenance-task.ipynb’).
Should be a basename only, without directory path.
- Options:
- –template, -t: Path to a custom template runbook to use as a base.
Can be set via TEMPLATE environment variable. Default: ./runbooks/binder/_template-deno.ipynb
- –language, -l: Shortcut to use a predefined language template.
Can be set via LANGUAGE environment variable. Default: deno
- Examples:
runbook create maintenance-task.ipynb # Creates using default Deno template runbook create task.ipynb -l python # Creates using Python template runbook create task.ipynb -t custom-template.ipynb # Creates from custom template
The command will create the notebook and display the edit command to open it.
Usage
runbook create [OPTIONS] FILENAME
Options
- -t, --template <template>¶
Path to the template file to use
- -l, --language <language>¶
Language to use for the runbook
Arguments
- FILENAME¶
Required argument
Environment variables
- TEMPLATE
Provide a default for
-t
- LANGUAGE
Provide a default for
-l
diff¶
Compare two runbooks and show their differences
This command uses nbdime to display a detailed comparison between two runbooks.
- Arguments:
NOTEBOOK_1: Path to the first runbook for comparison NOTEBOOK_2: Path to the second runbook for comparison
- Examples:
runbook diff notebook1.ipynb notebook2.ipynb # Compare two notebooks runbook diff original.ipynb modified.ipynb # Show changes between versions
The diff output will be displayed in a terminal-friendly format, with: - Added content in green - Removed content in red - Modified content showing both versions
Usage
runbook diff [OPTIONS] NOTEBOOK_1 NOTEBOOK_2
Arguments
- NOTEBOOK_1¶
Required argument
- NOTEBOOK_2¶
Required argument
edit¶
Edit an existing runbook
Usage
runbook edit [OPTIONS] FILENAME
Arguments
- FILENAME¶
Required argument
init¶
Initialize a folder as a runbook repository
Usage
runbook init [OPTIONS]
Options
- -d, --directory <directory>¶
Path to the runbook directory
- -s, --skip-confirmation <skip_confirmation>¶
Skip confirmation prompt
Environment variables
- DIRECTORY
Provide a default for
-d
- SKIP_CONFIRMATION
Provide a default for
-s
list¶
List runbooks
Usage
runbook list [OPTIONS]
plan¶
Prepares the runbook for execution by injecting parameters. Doesn’t run runbook.
Usage
runbook plan [OPTIONS] INPUT
Options
- -e, --embed <embed>¶
Path to file(s) to embed in the runbook output directory
- -p, --params <params>¶
Parameters to inject into the runbook in json object format where the key is the parameter name and the value is the parameter value
- -i, --identifier <identifier>¶
Optional identifier to append to the output filename
- -r, --prompter <prompter>¶
[Experimental] Path to a prompter script that will be used to gather parameters from the user
Arguments
- INPUT¶
Required argument
review¶
[Unimplemented] Entrypoint for reviewing runbook
Usage
runbook review [OPTIONS]
run¶
Run a runbook
Usage
runbook run [OPTIONS] FILENAME
Options
- --output <output>¶
Path to the output file
- --interactive, --no-interactive¶
Run the notebook in interactive mode or EXPERIMENTAL non-interactive mode
Arguments
- FILENAME¶
Required argument
show¶
Show runbook parameters and metadata
Usage
runbook show [OPTIONS] RUNBOOK
Arguments
- RUNBOOK¶
Required argument
version¶
Display version information about runbook
Usage
runbook version [OPTIONS]