killercoda-cli

Table of Contents

• Installation
• Introduction
• Documentation
  • Requirements
• Usage
  • Initialize a new scenario
  • Add a new step
  • Adding assets
• Development
• Testing
• Disclaimer
• License

Installation

pip install killercoda-cli

[!NOTE]

If there is an installation permissions error [Error 13], consider installing with --user flag or adding ./local/bin to the PATH variable.

Introduction

The interactive killercoda scenarios are a great way learn new technologies in an hands-on approach. However, creating the scenarios and managing can be tedious and time consuming.

The killercoda-cli solves some of those problems by:

• Adding a new step after the existing last step and creating a directory for including foreground and background scripts placeholders.
• Adding a regular step with background.sh and foreground.sh scripts or a verify step with verify.sh script.
• Renaming and re indexing step files and directories allowing for inserting a step in between existing steps and moving content down
• Updating the index.json file to reflect changes in step order and titles.

Documentation

Autogenerated API documentation generated in pdoc available at: https://piotr1215.github.io/killercoda-cli/killercoda_cli/cli.html.

Requirements

• The tool must be run in a directory containing step files or directories (e.g. step1.md, step2/).
• An index.json file must be present in the directory, which contains metadata about the steps.

Usage

Initialize a new scenario

In a new directory run killercoda-cli init. This command will trigger a wizard to create a new scenario. After answering all the questions, the directory will contain the following structure:

.
├── index.json
├── intro.md
├── finish.md

Add a new step

From here run killercoda-cli without arguments. This command will trigger a wizard to add a new step. After answering all the questions, the directory will contain steps in the similar structure:

.
├── index.json
├── step1.md
└── step2
    └── step2.md

And you want to insert a new step between step1.md and step2/, titled "New Step".

1. Run killercoda-cli.
2. Enter the title for the new step: "New Step".
3. Enter the step number to insert the new step at: 2.
4. Enter the step type (regular or verify): regular.

After running the tool, your directory structure will be updated to:

.
├── index.json
├── step1.md
├── step2
    └── step2.md (previously step1.md content)
└── step3
    └── step3.md (previously step2.md content)

The index.json file will also be updated to include the new step and renumber existing steps accordingly.

Before:

{
  "steps": [
    {
      "title": "Step 1",
      "text": "step1.md"
    },
    {
      "title": "Step 2",
      "text": "step2/step2.md"
    }
  ]
}

After:

{
  "steps": [
    {
      "title": "Step 1",
      "text": "step1.md"
    },
    {
      "title": "New Step",
      "text": "step2/step2.md"
    },
    {
      "title": "Step 2",
      "text": "step3/step3.md"
    }
  ]
}

Adding assets

The killercoda-cli assets command has been added to facilitate the generation of necessary assets and folder structures in the current working directory using a predefined cookiecutter template.

[!NOTE] The assets are opinionated and may not fit all use cases, but it's a good starting point to add some interactivity to the scenario.

This command will generate the required folder structure and files directly in the current working directory and remove the temporary directory.

Assets are NOT automatically added to the index.json to leave the decision to the user how to bring the assets into the scenario.

Validating courses

The killercoda-cli validate command allows you to validate the structure and configuration of your scenarios:

➜ killercoda-cli validate

=== Scenario Validation ===
[+]json-syntax                                        ok
[+]step-1                                             ok
[+]step-2                                             ok

Validation Status: PASSED
Location: /scenario/folder

This command checks:

• Presence and validity of index.json files
• Required fields in configuration
• Existence of all referenced files
• Step structure and consistency

The validation command is useful for CI/CD pipelines to ensure course integrity before deployment.

Development

Installing locally with pip install -e . --user will allow you to run the tool locally.

Testing

To run the tests, use the following commands:

Here is the text rendered as a Markdown list:

• hatch run test:unit - to run the unit tests.
• hatch run test:integration - to run the integration tests.
• hatch run test:coverage-report - to generate the coverage report.

Let me know if you have any further requests!

Disclaimer

This is an my personal project to easier create and manage killercoda scenarios. Check out killercoda interactive scenarios to learn more about the service.

License

killercoda-cli is distributed under the terms of the MIT license.