Command-Line Interface#
Full reference for the CLI:
Options for each command can also be set via environment variables to avoid them
having to be set for every call. The variable to set should be BLUEAPI
followed by the name of each subcommand, and then the name of the option all
made upper-case and joined with underscores. For example, to set the --output
option to the controller subcommand to ‘full’, you would need to set the
environment variable BLUEAPI_CONTROLLER_OUTPUT=full.
blueapi#
blueapi [OPTIONS] COMMAND [ARGS]...
Options
- --version#
Show the version and exit.
- -c, --config <config>#
Path to configuration YAML file
config-schema#
Generates a json schema from the ApplicationConfig pydantic basemodel
blueapi config-schema [OPTIONS]
Options
- -u, --update#
[Development only] update the config schema in the documentation
- -o, --output <output>#
Path to file to save the config schema
controller#
Client utility for controlling and introspecting the worker
blueapi controller [OPTIONS] COMMAND [ARGS]...
Options
- -o, --output <output>#
- Options:
json | full | compact
abort#
Abort the execution of the current task, marking any ongoing runs as failed, with optional reason
blueapi controller abort [OPTIONS] [REASON]
Arguments
- REASON#
Optional argument
devices#
Get a list of devices available for the worker to use
blueapi controller devices [OPTIONS]
env#
Inspect or restart the environment
blueapi controller env [OPTIONS]
Options
- -r, --reload#
Reload the current environment
- -t, --timeout <timeout>#
Timeout to wait for reload in seconds, defaults to 10
get-python-env#
Retrieve the installed packages and their sources in the current environment.
blueapi controller get-python-env [OPTIONS]
Options
- --name <name>#
Filter by the name of the installed package
- --source <source>#
Filter by the source type
listen#
Listen to events output by blueapi
blueapi controller listen [OPTIONS]
pause#
Pause the execution of the current task
blueapi controller pause [OPTIONS]
Options
- --defer#
Defer the pause until the next checkpoint
plans#
Get a list of plans available for the worker to use
blueapi controller plans [OPTIONS]
resume#
Resume the execution of the current task
blueapi controller resume [OPTIONS]
run#
Run a plan with parameters
blueapi controller run [OPTIONS] NAME [PARAMETERS]
Options
- --foreground, --fg, --background, --bg#
- -t, --timeout <timeout>#
Timeout for the plan in seconds. None hangs forever
- -i, --instrument-session <instrument_session>#
Required Instrument session associated with running the plan, used to tell blueapi where to store any data and as a security check: the session must be valid and active and you must be a member of it.
Arguments
- NAME#
Required argument
- PARAMETERS#
Optional argument
state#
Print the current state of the worker
blueapi controller state [OPTIONS]
stop#
Stop the execution of the current task, marking as ongoing runs as success
blueapi controller stop [OPTIONS]
login#
Authenticate with the blueapi using the OIDC (OpenID Connect) flow.
blueapi login [OPTIONS]
logout#
Logs out from the OIDC provider and removes the cached access token.
blueapi logout [OPTIONS]
schema#
Only import the service functions when starting the service or generating the schema, not the controller as a new FastAPI app will be started each time.
blueapi schema [OPTIONS]
Options
- -o, --output <output>#
Path to file to save the schema
- -u, --update#
[Development only] update the schema in the documentation
serve#
Run a worker that accepts plans to run
blueapi serve [OPTIONS]
setup-scratch#
blueapi setup-scratch [OPTIONS]