CLI reference#

Complete reference for the ibek command-line interface. Everything below is generated directly from the Typer application, so it always matches the installed version.

ibek groups its commands by the lifecycle phase in which you run them:

  • ibek support — runs during the Generic IOC container build, while EPICS support modules are being compiled and configured.

  • ibek ioc — runs during the container build to turn the installed support definitions into a schema and to package the runtime assets.

  • ibek runtime — runs at container start-up, turning an IOC instance’s YAML into the boot script and databases it runs from.

  • ibek dev — runs inside a development container to wire a checked-out instance or support module into the EPICS tree for live editing.

  • ibek pattern — runs in a services repository to vendor pinned runtime-support patterns into an IOC instance and verify their integrity.

Note

This page is reference material. ibek <group> <command> --help is the authoritative, version-exact source of truth for any command — if the text here and --help ever disagree, trust --help.

For the YAML formats these commands consume and produce, and for the vendoring concepts behind ibek pattern, see the dedicated pages — they are not repeated here:

Things worth knowing#

Note

ibek runtime generate is LEGACY. It builds a startup script from a single instance file and is superseded by ibek runtime generate2, which supports multiple instance files. generate2 auto-gathers ioc.yaml and runtime.yaml from its positional config-folder argument (e.g. a ioc.yaml from the image plus a runtime.yaml from the services repo), and --instance/-i supplies any further instance files on top of those. Prefer generate2 for new work.

Note

ibek support generate-schema --output has no default. If you omit --output, the global JSON schema is printed to stdout; pass --output FILE to write it to a file instead. The same is true of ibek ioc generate-schema.

Note

ibek pattern check integrity policy. By default a hash mismatch between a vendored file and runtime-lock.yaml is a hard error (non-zero exit). Pass --allow-dirty, or set the environment variable IBEK_ALLOW_DIRTY=1, to downgrade mismatches to warnings while still reporting them.

Command tree#

ibek#

ibek Usage: ibek [OPTIONS] COMMAND [ARGS]... IOC Builder for EPICS and Kubernetes Provides support for building generic EPICS IOC container images and for running IOC instances in a Kubernetes cluster. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--versionPrint the version of ibek and exit│ │--install-completionInstall completion for the current shell.│ │--show-completionShow completion for the current shell, to copy│ │it or customize the installation.             │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │supportCommands for building support modules during container build       │ │ioc    Commands for building generic IOCs during container build          │ │runtimeCommands for building IOC instance startup files at container      │ │runtime                                                            │ │dev    Commands for working inside Generic IOC development containers     │ │patternCommands for vendoring runtime-support patterns into a services    │ │repo                                                               │ ╰──────────────────────────────────────────────────────────────────────────────╯

support#

support Usage: ibek support [OPTIONS] COMMAND [ARGS]... Commands for building support modules during container build ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │apt-install-runtime-packagesInstall packages from the list collected by   │ │calls to add_runtime_packages                 │ │generate-schema             Produce JSON global schema for all            │ │<support_module>.ibek.support.yaml files      │ ╰──────────────────────────────────────────────────────────────────────────────╯
apt-install-runtime-packages#
apt-install-runtime-packages Usage: ibek support apt-install-runtime-packages [OPTIONS] Install packages from the list collected by calls to add_runtime_packages ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
generate-schema#
generate-schema Usage: ibek support generate-schema [OPTIONS] Produce JSON global schema for all <support_module>.ibek.support.yaml files ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--outputPATHThe filename to write the schema to│ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯

ioc#

ioc Usage: ibek ioc [OPTIONS] COMMAND [ARGS]... Commands for building generic IOCs during container build ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │build-docker          EXPERIMENTAL: Attempt to interpret the Dockerfile   │ │and run it's commands                               │ │inside the devcontainer. For internal, incremental  │ │builds of the Dockerfile.                           │ │generate-schema       Create a json schema from a number of               │ │support_module.ibek.support.yaml                    │ │files                                               │ │extract-runtime-assetsFind all the runtime assets in an EPICS installation│ │and copy them to a                                  │ │new folder hierarchy for packaging into a container │ │runtime stage.                                      │ │do-wait               Read the YAML list file which includes the devices  │ │to wait for and execute the appropriate wait command│ │for each device type.                               │ │Currently only supports request to wait for         │ │successful connection to a remote socket.           │ │For now, unknown entry types (i.e. not              │ │"ibek.wait_ip") are treated as a non-fatal warning. │ ╰──────────────────────────────────────────────────────────────────────────────╯
build-docker#
build-docker Usage: ibek ioc build-docker [OPTIONS] EXPERIMENTAL: Attempt to interpret the Dockerfile and run it's commands inside the devcontainer. For internal, incremental builds of the Dockerfile. Useful for debugging the Dockerfile without having to build the whole container from outside of the IOC devcontainer. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--startINTEGERThe step to start at in the Dockerfile│ │[default: 1]                          │ │--stopINTEGERThe step to stop at in the Dockerfile│ │[default: 999]                       │ │--dockerfilePATH   The filepath to the Dockerfile to build        │ │[default:                                      │ │/home/runner/work/ibek/ibek/Dockerfile]        │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
generate-schema#
generate-schema Usage: ibek ioc generate-schema [OPTIONS] [DEFINITIONS]... Create a json schema from a number of support_module.ibek.support.yaml files ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │definitions[DEFINITIONS]...File paths to one or more support      │ │module YAML files                      │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--outputPATHThe file path to the schema file to  │ │be written                           │ │--ibek-defs--no-ibek-defsInclude definitions in               │ │/epics/ibek-defs in generated schema │ │[default: ibek-defs]                 │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
extract-runtime-assets#
extract-runtime-assets Usage: ibek ioc extract-runtime-assets [OPTIONS] DESTINATION [EXTRAS]... Find all the runtime assets in an EPICS installation and copy them to a new  folder hierarchy for packaging into a container runtime stage. This should be performed in a throw away container stage (runtime_prep) as it is destructive of the source folder, because it uses move for speed. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*destinationPATH       The root folder to extract assets into│ │[required]                            │ │extras     [EXTRAS]...list of files to also extract│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--sourcePATHThe root folder to extract assets from│ │[default: /epics]                     │ │--defaults--no-defaultscopy the default assets│ │[default: defaults]    │ │--dry-run--no-dry-runshow what would happen│ │[default: no-dry-run] │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
do-wait#
do-wait Usage: ibek ioc do-wait [OPTIONS] Read the YAML list file which includes the devices to wait for and execute the appropriate wait command for each device type. Currently only supports request to wait for successful connection to a remote socket. For now, unknown entry  types (i.e. not "ibek.wait_ip") are treated as a non-fatal warning. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--sourcePATHThe YAML file containing the list of wait commands to │ │execute                                               │ │[default: /epics/runtime/wait_list.yaml]              │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯

runtime#

runtime Usage: ibek runtime [OPTIONS] COMMAND [ARGS]... Commands for building IOC instance startup files at container runtime ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │generate2        An updated version of generate that supports multiple    │ │instance files.                                          │ │This allows a main ioc.yaml with entities from the       │ │generic IOC image and                                    │ │additional runtime.yaml with entities from the services  │ │repository.                                              │ │place-files      Place runtime artifacts (proto / db / ...) from an IOC   │ │instance config                                          │ │folder into their runtime search-path locations for IOC  │ │boot.                                                    │ │generate         LEGACY single-instance generate; superseded by           │ │`generate2`.                                             │ │generate-autosaveGenerate autosave request files from autosave settings   │ │and positions                                            │ │template files found in support module db folders. Allow │ │overrides                                                │ │from ibek-support/* and /epics/ioc/config folders.       │ ╰──────────────────────────────────────────────────────────────────────────────╯
generate2#
generate2 Usage: ibek runtime generate2 [OPTIONS] [CONFIG_FOLDER] An updated version of generate that supports multiple instance files. This  allows a main ioc.yaml with entities from the generic IOC image and additional runtime.yaml with entities from the services repository. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │config_folder[CONFIG_FOLDER]The IOC instance folder containing    │ │entity yaml files                     │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--instance-iFILEAdditional IOC instance entity yaml    │ │files                                  │ │--definitionsFILEThe filepath to a support module yaml  │ │file                                   │ │--output-oPATHThe folder to write the generated      │ │runtime files to                       │ │[default: /epics/runtime]              │ │--pvi--no-pvigenerate pvi PVs and opi files│ │[default: pvi]                │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
place-files#
place-files Usage: ibek runtime place-files [OPTIONS] CONFIG_FOLDER Place runtime artifacts (proto / db / ...) from an IOC instance config folder  into their runtime search-path locations for IOC boot. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*config_folderDIRECTORYThe IOC instance config folder containing│ │runtime artifacts                        │ │[required]                               │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
generate#
generate Usage: ibek runtime generate [OPTIONS] INSTANCE DEFINITIONS... LEGACY single-instance generate; superseded by `generate2`. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*instance   PATH          The filepath to the ioc instance      │ │entity file                           │ │[required]                            │ │*definitionsDEFINITIONS...The filepath to a support module yaml │ │file                                  │ │[required]                            │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--output-oPATHThe folder to write the generated runtime   │ │files to                                    │ │[default: /epics/runtime]                   │ │--pvi--no-pvigenerate pvi PVs and opi files│ │[default: pvi]                │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
generate-autosave#
generate-autosave Usage: ibek runtime generate-autosave [OPTIONS] [SUBST_FILE] Generate autosave request files from autosave settings and positions template  files found in support module db folders. Allow overrides from ibek-support/*  and /epics/ioc/config folders. CONVENTION: req template files must be in the support module db folder after the module is built. The template files must be named with the same stem as the db file that defines the PVs to be saved. The naming convention is: DbTemplateFileStem_positions.req : for autosave stage 0 settings DbTemplateFileStem_settings.req : for autosave stage 1 settings The steps are: 1. at build time "ibek support generate-links" creates symlinks to override    req files in /epics/autosave. These override req files come from individual    ibek-support folders 2. at runtime "ibek runtime generate-autosave" handles the remaining steps: 3. All req files in /epics/support/*/db/ are symlinked to /epics/autosave    except if that req file name already exists (from 1.) 4. All req files in /epics/ioc/config are symlinked to /epics/autosave    overwriting any existing req file (thus supplying instance overrides) 5. AutosaveGenerator generates two substitution files for settings and  positions.    These substitution files are the same as ioc.db except that they contain    the file names of the req templates instead of the db files. If ioc.db    contains a database template that has no corresponding req template, then    that line is omitted from the new substitution file. 6. Two req files are generated from the two substitution files using MSI. Where the database template has a full path, this will be stripped in substitution files created in step 5. At runtime autosave will be pointed at the /epics/autosave folder for its search path. There is an issue with name collisions that we will address if this ever arises. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │subst_file[SUBST_FILE][default: /epics/runtime/ioc.subst]│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯

dev#

dev Usage: ibek dev [OPTIONS] COMMAND [ARGS]... Commands for working inside Generic IOC development containers ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │instanceSymlink an IOC instance config folder into /epics/ioc/config.     │ │support enable a support module for development.                          │ ╰──────────────────────────────────────────────────────────────────────────────╯
instance#
instance Usage: ibek dev instance [OPTIONS] INSTANCE Symlink an IOC instance config folder into /epics/ioc/config. Used in the devcontainer to allow the IOC instance to be run using /epics/ioc/starts.sh. Changes made to the config will be immediately available and also under version control. e.g. if instance is /workspaces/bl38p/iocs/bl38p-mo-panda-01 then we need: - /epics/ioc/config -> /workspaces/bl38p/iocs/bl38p-mo-panda-01/config ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*instanceDIRECTORYThe filepath to the ioc instance entity file│ │[required]                                  │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
support#
support Usage: ibek dev support [OPTIONS] MODULE enable a support module for development. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*modulePATHThe filepath to the support module to work on│ │[required]                                   │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯

pattern#

pattern Usage: ibek pattern [OPTIONS] COMMAND [ARGS]... Commands for vendoring runtime-support patterns into a services repo ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │add    Vendor a pattern into an instance, writing files +                 │ │runtime-lock.yaml + schema.                                        │ │update Re-vendor a pattern to a new pinned version; refresh hashes +      │ │schema.                                                            │ │check  Verify vendored files match runtime-lock.yaml (vendor integrity).  │ │restoreRevert vendored files to the version pinned in runtime-lock.yaml.  │ │schema Generate the instance's ioc.schema.json and rewrite ioc.yaml's     │ │header.                                                            │ ╰──────────────────────────────────────────────────────────────────────────────╯
add#
add Usage: ibek pattern add [OPTIONS] NAME [INSTANCE] Vendor a pattern into an instance, writing files + runtime-lock.yaml + schema. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │*name    TEXT      Pattern reference: name, e.g. │ │ibek-runtime-streamdevice:lakeshore340@1.0.0│ │[required]                                   │ │instance[INSTANCE]The IOC instance folder (containing config/)│ │[default: .]                                │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--source-sTEXTOverride the library source URI (git URL or local   │ │path)                                               │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
update#
update Usage: ibek pattern update [OPTIONS] [INSTANCE] Re-vendor a pattern to a new pinned version; refresh hashes + schema. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │instance[INSTANCE]The IOC instance folder (containing config/)│ │[default: .]                                │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--name-nTEXTRestrict to a single pattern by name (default: all │ │in the lock)                                       │ │--version-vTEXTNew pinned version to vendor│ │--source-sTEXTOverride the library source URI (git URL or local  │ │path)                                              │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
check#
check Usage: ibek pattern check [OPTIONS] [INSTANCE] Verify vendored files match runtime-lock.yaml (vendor integrity). ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │instance[INSTANCE]The IOC instance folder (containing config/)│ │[default: .]                                │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--allow-dirtyDowngrade hash mismatches to warnings (also enabled  │ │by IBEK_ALLOW_DIRTY=1)                               │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
restore#
restore Usage: ibek pattern restore [OPTIONS] [INSTANCE] Revert vendored files to the version pinned in runtime-lock.yaml. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │instance[INSTANCE]The IOC instance folder (containing config/)│ │[default: .]                                │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--name-nTEXTRestrict to a single pattern by name (default: all in │ │the lock)                                             │ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
schema#
schema Usage: ibek pattern schema [OPTIONS] [INSTANCE] Generate the instance's ioc.schema.json and rewrite ioc.yaml's header. Fetches the published base schema for the instance's pinned image and merges the instance's vendored / local support entities into it. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │instance[INSTANCE]The IOC instance folder (containing config/)│ │[default: .]                                │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯