stanza.cli

Stanza CLI - Command-line interface for Stanza experiment framework.

Module Contents

Functions

API

1
stanza.cli.cli() -> None

Stanza - Build tune up sequences for quantum computers fast.

Easy to code. Easy to run.

1
stanza.cli.init(
2
    path: pathlib.Path | None, name: str | None
3
) -> None

Initialize a new timestamped experiment session directory.

Creates a directory with the format YYYYMMDDHHMMSS_<name> where all experiment data from routines will be logged. The session becomes active automatically.

Examples:

stanza init

stanza init —name my_experiment

stanza init —path /data/experiments

1
stanza.cli.status() -> None

Show current active session information.

Displays the active session name, location, and creation timestamp. If no session is active, provides instructions for initializing one.

1
stanza.cli.delete_session(
2
    force: bool, keep_data: bool
3
) -> None

Delete the active session directory or clear the pointer.

1
stanza.cli._get_config_file() -> pathlib.Path

Get path to live plot config file.

Returns:

Path to live_plot_config.json in the .stanza directory

1
stanza.cli._read_config() -> dict[str, typing.Any]

Read live plot config from disk.

Returns:

Configuration dictionary, or empty dict if file doesn’t exist

1
stanza.cli._write_config(config: dict[str, typing.Any]) -> None

Write live plot config to disk.

Parameters:

1
stanza.cli.live_plot() -> None

Manage live plotting configuration.

Configure and control live plotting for experiment data visualization during runtime. Supports both server and inline backends.

1
stanza.cli.enable_live_plot(
2
    backend: str, port: int
3
) -> None

Enable live plotting for experiments.

Configures DataLogger to automatically start live plotting when experiments run. The server backend starts a Bokeh server that can be viewed in a browser, while the inline backend displays plots directly in Jupyter notebooks.

1
stanza.cli.disable_live_plot() -> None

Disable live plotting for experiments.

Turns off automatic live plotting. Experiments will run normally without real-time visualization.

1
stanza.cli.live_plot_status() -> None

Show current live plotting configuration.

Displays whether live plotting is enabled and the configured backend and port settings.

1
stanza.cli.jupyter_cli() -> None

Manage Jupyter notebook server.

Start, stop, and monitor a background Jupyter server with automatic cell output logging. The server runs detached and survives terminal closure.

1
stanza.cli.jupyter_start(
2
    notebook_dir: pathlib.Path, port: int
3
) -> None

Start a Jupyter notebook server in the background.

Launches a JupyterLab server as a detached process with automatic cell output logging enabled. The server runs independently of the terminal and can be stopped with ‘stanza jupyter stop’.

Cell outputs are automatically logged to <notebook_name>.log files in the same directory as the notebook.

Examples:

stanza jupyter start

stanza jupyter start /path/to/notebooks —port 8889

1
stanza.cli.jupyter_stop() -> None

Stop the Jupyter notebook server gracefully.

Uses escalating shutdown strategies to ensure the server stops:

1. REST API shutdown request
2. SIGTERM signal
3. SIGKILL signal (if necessary)

Safe to run even if no server is currently running.

Examples:

stanza jupyter stop

1
stanza.cli.jupyter_status() -> None

Show current Jupyter server status.

Displays server information including process ID, JupyterLab URL, uptime, and notebook root directory. Shows helpful message if no server is running.

Examples:

stanza jupyter status

1
stanza.cli.jupyter_open() -> None

Open JupyterLab in your default browser.

Opens the JupyterLab URL with authentication token automatically included. If no server is running, starts one automatically in the current directory.

Examples:

stanza jupyter open

1
stanza.cli._require_server() -> None

Check if Jupyter server is running, abort if not.

Raises:

click.Abort: If no server is running

1
stanza.cli._find_notebook(name: str) -> dict[str, typing.Any]

Find notebook session by name, abort if not found or ambiguous.

Performs case-insensitive substring matching on notebook names.

Parameters:

Returns:

Session dictionary containing notebook_path, log_path, etc.

Raises:

click.Abort: If no matches found or multiple matches found

1
stanza.cli.jupyter_list() -> None

List all active notebook sessions.

Shows the names of all notebooks currently running with active kernels on the Jupyter server.

1
stanza.cli.jupyter_logs(
2
    notebook: str | None, lines: int
3
) -> None

View or list notebook log files.

Without arguments, lists all active notebook sessions with their log files and sizes. With a notebook name, streams the log file in real-time (like ‘tail -f’). Press Ctrl+C to detach.

Examples:

stanza jupyter logs

stanza jupyter logs my_notebook.ipynb

stanza jupyter logs my_notebook —lines 20

1
stanza.cli.jupyter_attach(
2
    notebook: str, lines: int
3
) -> None

Attach to a notebook with active kernel control.

Similar to ‘logs’ but with additional keyboard controls:

• Ctrl+C: Kill the notebook’s kernel
• ESC (twice): Exit without killing the kernel

Useful for monitoring and controlling long-running notebook executions.

Examples:

stanza jupyter attach my_notebook.ipynb

stanza jupyter attach experiment —lines 20

1
stanza.cli.main() -> None

Entry point for CLI.