Skip to main content

Kurtosis CLI

The Kurtosis CLI is the main way you will interact with Kurtosis. This document will walk you through some common CLI workflows.

TIP: The kurtosis command, and all of its subcommands, will print helptext when passed the -h flag. You can use this at any time to see information on the command you're trying to run.

TIP: Kurtosis supports tab-completion. To add it, follow these instructions.

Initialize configuration​

When the Kurtosis CLI is executed for the first time on a machine, we ask you to make a choice about whether you'd like to send anonymized usage metrics to help us make the product better. To make this election non-interactively, you can run either:

kurtosis config init send-metrics

to send anonymized metrics to improve the product or

kurtosis config init dont-send-metrics

if you'd prefer not to.

Start the engine​

The CLI functions through calls to the Kurtosis engine, which is a very lightweight container. The CLI will start the engine container automatically for you so you should never need to start it manually, but you can do so if you please:

kurtosis engine start

Check engine status​

The engine's version and status can be printed with:

kurtosis engine status

Stop the engine​

To stop the engine, run:

kurtosis engine stop

Create an enclave​

The environments in Kurtosis that house your containers are called "enclaves". They are isolated from each other, to ensure they don't interfere with each other. To create a new, empty enclave, run:

kurtosis enclave new

List enclaves​

To see all the enclaves in Kurtosis, run:

kurtosis enclave ls

The enclave IDs that are printed will be used in enclave manipulation commands.

View enclave details​

To view detailed information about a given enclave, run:

kurtosis enclave inspect $THE_ENCLAVE_ID

This will print detailed information about:

  • The enclave's status (running or stopped)
  • The services inside the enclave (if any), and the information for accessing those services' ports from your local machine
  • The modules inside the enclave (if any)
  • The REPLs that have been attached to the enclave (if any)

Dump enclave information to disk​

You'll likely need to store enclave logs to disk at some point - maybe you want to have a log package if your CI fails, or you want to record historical logs as you work on a module, or you want to send debugging information to a module author. Whatever the case may be, you can run:

kurtosis enclave dump $THE_ENCLAVE_ID $OUTPUT_DIRECTORY

You'll get the container logs & configuration in the output directory for further analysis & sharing.

Delete an enclave​

To delete an enclave and everything inside of it, run:

kurtosis enclave rm $THE_ENCLAVE_ID

Note that this will only delete stopped enclaves. To delete a running enclave, pass in the -f/--force flag.

Add a service to an enclave​

To add a service to an enclave, run:

kurtosis service add $THE_ENCLAVE_ID $THE_SERVICE_ID $CONTAINER_IMAGE

Much like docker run, this command has multiple options available to customize the service that's started:

  1. The --entrypoint flag can be passed in to override the binary the service runs
  2. The --env flag can be used to specify a set of environment variables that should be set when running the service
  3. The --ports flag can be used to set the ports that the service will listen on

To override the service's CMD, add a -- after the image name and then pass in your CMD args like so:

kurtosis service add --entrypoint sh my-enclave test-service alpine -- -c "echo 'Hello world'"

View a service's logs​

To print the logs for a service, run:

kurtosis service logs $THE_ENCLAVE_ID $THE_SERVICE_ID

The service ID is printed upon inspecting an enclave.

The -f flag can also be added to continue following the logs, similar to tail -f.

Run commands inside a service container​

You might need to get access to a shell on a given service container. To do so, run:

kurtosis service shell $THE_ENCLAVE_ID $THE_SERVICE_ID

Delete a service from an enclave​

Services can be deleted from an enclave like so:

kurtosis service rm $THE_ENCLAVE_ID $THE_SERVICE_ID

NOTE: To avoid destroying debugging information, Kurtosis will leave removed services inside the Docker engine. They will be stopped and won't show up in the list of active services in the enclave, but you'll still be able to access them (e.g. using service logs) by their service GUID (available via enclave inspect).

Execute a module​

For ease-of-use, the Kurtosis CLI provides a single command to 1) create an enclave 2) load a module inside it and 3) execute the module. This command is:

kurtosis module exec $THE_MODULE_IMAGE

The module's behaviour can be customized with the optional --load-params and --execute-params flags that are specific to the module. For convenience, we recommend putting the params into a file so you can get syntax highlighting and then using command substitution to cat the file contents.

For example:

Some module params, stored in /tmp/my-module-params.json so that I get syntax highlighting:

{
    "someProperty": "someValue",
    "someOtherProperty": 4
}

The kurtosis command to slot those params into the module using command substitution:

kurtosis module exec $THE_MODULE_IMAGE --execute-params "$(cat /tmp/my-module-params.json)"

Remove old artifacts from Kurtosis​

Kurtosis defaults to leaving enclave artifacts (containers, volumes, etc.) around so that you can refer back them for debugging. To clean up artifacts from stopped enclaves, run:

kurtosis clean

To remove artifacts from all enclaves (including running ones), add the -a/--all flag.

NOTE: This will not stop the Kurtosis engine itself! To do so, see "Stopping the engine" above.

Adding Tab Completion​

The Kurtosis CLI supports tab completion for bash, zsh, and fish via the kurtosis completion SHELL command (e.g. kurtosis completion bash). sourceing the output of the command will enable tab-completion, and adding the source command to your shell config file will enable it across shells. The instructions below will get you set up for your shell.

NOTE: As of 2022-02-21, tab completion for all commands is available but intelligent tab completion for command parameters (e.g. kurtosis enclave inspect <TAB> auto-completing enclave IDs) is still ongoing.

Bash​

  1. Ensure you have Bash version >= 4.1
    1. Print your Bash version:
      echo $BASH_VERSION
    2. If your Bash version is less than 4.1, upgrade it:
  2. Check if you have bash-completion installed:
    type _init_completion
  3. If you get an error like -bash: type: _init_completion: not found, install Bash completion:
    • On Mac:
      1. Install the completion library:
        brew install [email protected]
      2. Add the following to your ~/.bash_profile:
        export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
        [[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"
      3. Reload your shell
      4. Verify that you now have the completion installed:
        type _init_completion
    • On Linux, install it using the package manager for your distro using these installation instructions
  4. Source the output of kurtosis completion bash in your Bash config file:
    • On Mac, add the following to your ~/.bash_profile file:
      # Add Kurtosis tab-completion
      source <(kurtosis completion bash)
    • On Linux, add the following to your ~/.bashrc file:
      # Add Kurtosis tab-completion
      source <(kurtosis completion bash)
  5. If you have an alias set up for Kurtosis, add completion for that as well (we'll assume the alias kt in the examples below):
    • On Mac, add the following to your ~/.bash_profile file:
      # Add tab-completion to Kurtosis alias
      complete -F __start_kurtosis kt
    • On Linux, add the following to your ~/.bashrc file:
      # Add tab-completion to Kurtosis alias
      complete -F __start_kurtosis kt
  6. Reload your shell

Zsh​

  1. Add the following to your ~/.zshrc file:
    # Add Kurtosis tab-completion
    source <(kurtosis completion zsh)
  2. If you have an alias set up for Kurtosis, add the following to your ~/.zshrc file (we'll assume the alias kt in this example):
    # Add tab-completion to Kurtosis alias
    compdef __start_kurtosis kt
  3. Reload your shell
  4. If you get an error like complete:13: command not found: compdef, add the following to the top of your ~/.zshrc and reload your shell again:
    autoload -Uz compinit
    compinit

Fish​

  1. Add the following to your ~/.config/fish/config.fish file:
    # Add Kurtosis tab-completion
    kurtosis completion fish | source
  2. Reload your shell