Quickstart¶

This guide will help you get started with Kessel quickly, from installation to running your first workflow.

Installation¶

Kessel can be installed directly from the repository:

$ git clone https://github.com/lanl/kessel.git
$ cd kessel
$ source share/kessel/setup-env.sh

This adds Kessel to your PATH and sets up the necessary environment variables.

Verify the installation:

$ kessel --version

To make Kessel available in future shell sessions, add the source command to your shell configuration file (e.g., .bashrc or .zshrc):

$ echo "source /path/to/kessel/share/kessel/setup-env.sh" >> ~/.bashrc

Prerequisites¶

Python 3.10 or higher
Git

Initializing a Project¶

Kessel provides several project templates to help you get started. Navigate to your project directory and initialize it with:

$ cd /path/to/your/project
$ kessel init

By default, this creates a .kessel directory with the spack-project template. To use a different template:

$ kessel init --template minimal-cmake-project

Available templates:

spack-project: For projects using Spack for dependency management
spack-deployment: For creating Spack deployment environments
minimal-cmake-project: For simple CMake-based projects

Project Structure¶

After initialization, your project will contain:

your-project/
├── .kessel/
│   └── workflows/
│       └── default.py
└── (your project files)

The .kessel/workflows/ directory contains workflow definitions. Each workflow is defined as a .py file (or a package directory with an __init__.py file) that defines the workflow steps.

Running Your First Workflow¶

Once initialized, you can run the default workflow:

$ kessel run

This executes all steps in the active workflow in sequence. Kessel will display a progress indicator showing which steps have been completed.

Running Individual Steps¶

You can execute individual workflow steps using the step command:

$ kessel step env
$ kessel step configure
$ kessel step build
$ kessel step test

To see available steps for the current workflow:

$ kessel workflow status

Working with Multiple Workflows¶

List all available workflows:

$ kessel list

Activate a different workflow:

$ kessel activate my-workflow

The active workflow is highlighted in the workflow list and persisted across sessions.

Example: CMake Project Workflow¶

For a typical CMake project, the workflow steps are:

configure: Run CMake configuration to generate build files
build: Compile the project
test: Run tests with CTest
install: Install the built artifacts

For projects using Spack for dependency management, an additional env step is added at the beginning to set up the build environment.

Run the complete workflow:

$ kessel run

Or run steps individually:

$ kessel step env
$ kessel step configure
$ kessel step build
$ kessel step test

You can pass arguments to steps. For example, to specify custom CMake arguments:

$ kessel step env --build-dir /path/to/build

Example: Spack Deployment¶

To create a Spack deployment for your system:

$ mkdir my-deployment
$ cd my-deployment
$ kessel init --template spack-deployment
$ kessel run ubuntu24.04

This will:

Set up the deployment structure
Bootstrap Spack
Create source mirrors
Build all specified environments
Finalize the deployment

Viewing Workflow Status¶

Check the current workflow status and progress:

$ kessel status

This displays a visual progress indicator showing completed and pending steps.

Resetting Workflow State¶

If you need to start over or clear the workflow state:

$ kessel reset

This allows you to re-run steps from the beginning.

Debugging¶

To see the shell commands that Kessel would execute without actually running them:

$ kessel --shell-debug run

This is useful for understanding what Kessel does or debugging issues.

Next Steps¶

Learn how to create custom workflows: Workflows
Set up Spack deployments: Spack Deployments
Integrate Kessel with CI/CD pipelines

Common Commands Reference¶

Command	Description
`kessel init`	Initialize a new Kessel project
`kessel run`	Run the complete active workflow
`kessel step <name>`	Execute a specific workflow step
`kessel list`	List all available workflows
`kessel activate <name>`	Switch to a different workflow
`kessel status`	Show workflow progress
`kessel reset`	Reset workflow state
`kessel --help`	Show help for all commands