CLI Reference
Vaibify provides two equivalent entry points: vaibify and the shorthand
vaib. All commands accept a --config flag to specify an alternate
vaibify.yml path.
Global Options
Flag |
Description |
|---|---|
|
Path to |
|
Print the installed version and exit |
|
Show the help message and exit |
When invoked with no subcommand, Vaibify starts in hub mode – a browser-based dashboard for managing multiple projects.
Project Targeting
Note: When you are in a directory containing
vaibify.yml, the--projectflag defaults to that project. When only one project is registered globally, the flag can be omitted entirely. When multiple projects exist,--projectis required unless you are in a project directory. Projects are registered automatically when you runvaibify init.
Project Setup
vaibify init
Create a new project from a template.
vaibify init [--template NAME] [--force]
Option |
Description |
|---|---|
|
Template name: |
|
Overwrite existing configuration files |
Creates vaibify.yml, container.conf, and project.json in the current
directory.
vaibify register
Register an existing project directory in the global registry so it
can be targeted with --project/-p from any directory. Unlike
vaibify init, this does not create or overwrite any files.
vaibify register [DIRECTORY]
Argument |
Description |
|---|---|
|
Path to the project directory (default: |
The directory must contain a vaibify.yml file.
vaibify setup
Launch the interactive setup wizard in a browser (port 8051). The wizard
walks through configuration fields and writes the result to vaibify.yml.
vaibify setup
vaibify config
Edit, export, or import configuration.
vaibify config edit # Open vaibify.yml in $EDITOR
vaibify config export [-p NAME] <file> # Write current config to a file
vaibify config import <file> # Load config from a file
Container Lifecycle
vaibify build
Build the Docker image from vaibify.yml and container.conf.
vaibify build [--no-cache] [--project/-p NAME]
Option |
Description |
|---|---|
|
Force a clean rebuild of all layers |
|
Target project name (optional if only one exists) |
vaibify start
Start the container in the background.
vaibify start [--gui] [--jupyter] [--project/-p NAME]
Option |
Description |
|---|---|
|
Launch the pipeline viewer after starting |
|
Start JupyterLab inside the container |
|
Target project name (optional if only one exists) |
vaibify stop
Stop the running container. The workspace volume persists.
vaibify stop [--project/-p NAME]
vaibify destroy
Remove the container and optionally delete the workspace volume.
vaibify destroy [--volumes] [--project/-p NAME]
Option |
Description |
|---|---|
|
Also remove the workspace volume |
|
Target project name (optional if only one exists) |
vaibify status
Report the state of the container, image, and workspace volume.
vaibify status [--project/-p NAME]
Working with the Container
These commands work from any directory on the host. If you have multiple
projects, specify which one with --project/-p. If only one project is
registered, the flag can be omitted.
vaibify connect
Open an interactive shell inside the running container.
vaibify connect [--project/-p NAME]
Option |
Description |
|---|---|
|
Target project name (optional if only one exists) |
vaibify push
Copy files from the host into the container workspace.
vaibify push [--project/-p NAME] <source> <destination>
Option |
Description |
|---|---|
|
Target project name (optional if only one exists) |
vaibify pull
Copy files from the container workspace to the host.
vaibify pull [--project/-p NAME] <source> <destination>
Option |
Description |
|---|---|
|
Target project name (optional if only one exists) |
vaibify verify
Run the isolation security audit inside the container. The audit checks for Docker socket access, privilege escalation paths, exposed ports, and mounted secrets.
vaibify verify [--project/-p NAME]
vaibify ls
List files in the container workspace. The path defaults to
/workspace; relative paths are resolved against /workspace/.
vaibify ls [--project/-p NAME] [--json] [PATH]
Option |
Description |
|---|---|
|
Target project name (optional if only one exists) |
|
Emit a JSON array instead of one filename per line |
|
Directory to list (default: |
vaibify cat
Print the contents of a file inside the container. Relative paths are
resolved against /workspace/.
vaibify cat [--project/-p NAME] PATH
vaibify run
Execute pipeline steps inside the container. Without options, runs every
step from the beginning. Use --step to run one step in isolation, or
--from to resume from a specific step. The two are mutually exclusive.
vaibify run [--project/-p NAME] [--step N | --from N]
Option |
Description |
|---|---|
|
Run only step N (1-based) |
|
Run step N and every step after it |
|
Target project name (optional if only one exists) |
Step progress, per-step pass/fail, and pipeline outcome are printed to stdout as the run progresses.
vaibify workflow
Print a summary of the current project, or details for a single step.
Without --step, emits a table of all steps with their last verification
status and run timestamp. With --step N, emits the step’s name,
directory, run flags, and verification block.
vaibify workflow [--project/-p NAME] [--step N] [--json]
Option |
Description |
|---|---|
|
Show details for step N (1-based) only |
|
Emit JSON instead of a human-readable table |
|
Target project name (optional if only one exists) |
vaibify test
Run the test commands attached to one or all pipeline steps. Without
--step, every step’s tests run in order. The exit code is non-zero if
any step’s tests fail.
vaibify test [--project/-p NAME] [--step N] [--json]
Option |
Description |
|---|---|
|
Run tests for step N only (1-based) |
|
Emit JSON results instead of a summary table |
|
Target project name (optional if only one exists) |
vaibify verify-step
Set the user-verification status for a single pipeline step. This is the CLI counterpart to clicking your sign-off row in a step’s Verification section in the GUI: a researcher records their judgment that a step’s outputs look correct (or don’t).
vaibify verify-step --step N --status STATUS [--project/-p NAME]
Option |
Description |
|---|---|
|
Step number (1-based, required) |
|
One of |
|
Target project name (optional if only one exists) |
GUI and Pipeline
vaibify gui
Launch the pipeline viewer in a browser (port 8050 by default). When run without a project, the landing page opens and displays all registered containers. Use the + button to add an existing project or create a new one. See The Dashboard for details.
vaibify gui [--project/-p NAME] [--port N]
Multiple sessions
Several vaibify instances can run on the same host. Typing
vaibify twice in two terminals does not collide — the second
invocation auto-shifts to the next free port (8051, 8052, …) and
announces the fallback on stderr. Pass --port N to pin an
explicit port. Any given container may be accessed by only one
browser session at a time: the hub landing page greys out
containers already held by another session, a second tab that tries
to open a held container is refused “In use in another browser
session”, and a second vaibify start -p X on the same project
refuses to attach. The exclusivity mechanism — the per-claim lease,
the owner-of-record map, the one-live-connection invariant, and the
release triggers — is specified once in the
architecture reference;
that section is the normative source of truth, including the
holder-payload field table.
The New vaibify window button on the container hub, project
picker, and Admin menu spawns a detached hub on a free port and
opens it in a new browser tab.
Session management
Vaibify hub and viewer servers run in the foreground of the terminal
that launched them. Closing a browser tab does not stop them, and
closing the terminal orphans the server, which keeps holding its
session slot and per-container locks until it is reaped. These
commands let you see and stop live sessions. They are the host-side
analog of jupyter server list and jupyter server stop, and like
those, they run on the host only – they are not invokable from
inside a container.
vaibify sessions
List every live hub and viewer session on the host, with its PID, role, port, start time, and the container(s) it holds.
vaibify sessions
Each line reports pid, role (hub or viewer), port, started
(the ISO start time), and containers (the names locked on that
port). When nothing is running it prints No live Vaibify sessions.
vaibify sessions stop
Gracefully stop a session by PID, or every session with --all.
vaibify sessions stop <PID>
vaibify sessions stop --all
Option |
Description |
|---|---|
|
The session PID to stop (from |
|
Stop every live session except the current one |
Stopping sends SIGTERM, which lets the server run its graceful
shutdown – releasing its session slot and any container locks it
holds. stop refuses any PID that is not a known live Vaibify
session, so it can never signal an unrelated process, and --all
excludes the current session so a session never stops itself.
Publishing
The vaibify publish subcommands are coming soon. The publishing
machinery (Zenodo archive, GitHub Actions workflow generation) is
already available through the GUI’s Settings → Publish pane; the
CLI counterparts will land in a future release. Until then, both
subcommands print Not yet implemented. and exit.
vaibify publish workflow (coming soon)
Generate a GitHub Actions workflow from project.json and vaibify.yml.
The output will be written to .github/workflows/vaibify.yml.
vaibify publish workflow
vaibify publish archive (coming soon)
Package pipeline outputs and upload them to Zenodo (or the Zenodo sandbox). Will return a DOI on success.
vaibify publish archive