CLI reference

CLI reference#

Every Kiso CLI command and flag.

Global options#

kiso [OPTIONS] COMMAND [ARGS]...

Option

Default

Description

--debug / --no-debug

--no-debug

Enable debug-level logging

--help

—

Show help and exit

kiso check#

Check the experiment configuration.

kiso check [OPTIONS] [EXPERIMENT_CONFIG]

Arguments:

Argument

Required

Default

Description

EXPERIMENT_CONFIG

No

experiment.yml

Path to the experiment YAML file. Must exist and be readable.

Example:

kiso check experiment.yml

Exit codes:

Code

Meaning

0

Config is valid

1

Config is invalid (validation error printed to stderr)

kiso up#

Create the resources needed to run the experiment.

kiso up [OPTIONS] [EXPERIMENT_CONFIG]

Arguments:

Argument

Required

Default

Description

EXPERIMENT_CONFIG

No

experiment.yml

Path to the experiment YAML file

Options:

Option

Default

Description

--force / --no-force

--no-force

Tear down existing resources and recreate them from scratch

-o, --output PATH

output

Directory to store the EnOSlib environment and run state

Examples:

# Basic provisioning
kiso up experiment.yml

# Force rebuild of existing resources
kiso up --force experiment.yml

# Use a custom output directory
kiso up --output /data/exp1 experiment.yml

kiso run#

Run the defined experiments.

kiso run [OPTIONS] [EXPERIMENT_CONFIG]

Arguments:

Argument

Required

Default

Description

EXPERIMENT_CONFIG

No

experiment.yml

Path to the experiment YAML file

Options:

Option

Default

Description

--force / --no-force

--no-force

Disregard previous run results and rerun the experiment

-o, --output PATH

output

Directory containing the EnOSlib environment (must match the --output used with kiso up)

Examples:

# Run the experiment
kiso run experiment.yml

# Re-run, discarding previous results
kiso run --force experiment.yml

# Use a custom output directory
kiso run --output /data/exp1 experiment.yml

Notes:

  • Resources must be provisioned (kiso up) before running

  • Results are written to <output>/run/<experiment-name>/

kiso down#

Destroy the resources provisioned for the experiments.

kiso down [OPTIONS] [EXPERIMENT_CONFIG]

Arguments:

Argument

Required

Default

Description

EXPERIMENT_CONFIG

No

experiment.yml

Path to the experiment YAML file

Options:

Option

Default

Description

-o, --output PATH

output

Directory containing the EnOSlib environment

Examples:

kiso down experiment.yml
kiso down --output /data/exp1 experiment.yml

Notes:

  • Destroys all provisioned resources. This action is irreversible.

  • Collect all results before running kiso down.

kiso ssh#

SSH into a provisioned node by label or alias.

kiso ssh [OPTIONS] NODE_ALIAS [-- COMMAND...]

Arguments:

Argument

Required

Description

NODE_ALIAS

Yes

Label or node alias to connect to. Accepts [user@]<label-or-alias> format.

COMMAND

No

Command to execute on the remote node. Separate from options with --.

Options:

Option

Default

Description

-o, --output PATH

output

Directory containing the EnOSlib environment (must match the --output used with kiso up)

-s, --ssh-options TEXT

—

Extra options passed to the underlying ssh command (shell-quoted string)

-t / -T

-t (tty)

Allocate (-t) or suppress (-T) a pseudo-TTY. Suppress when piping output

Examples:

# Interactive shell on the node with label submit-host
kiso ssh submit-host

# Connect as a specific user
kiso ssh ubuntu@submit-host

# Run a one-off command
kiso ssh submit-host -- hostname

# Run a command without TTY (useful for piping output)
kiso ssh -T submit-host -- cat /etc/os-release

# Pass extra SSH options (e.g. port forwarding)
kiso ssh -s "-L 9000:localhost:8000" submit-host

Notes:

  • Resources must be provisioned (kiso up) before connecting.

  • NODE_ALIAS can be either a label defined in the sites section of the config or the node’s own alias assigned by the testbed. Labels that map to more than one node are not usable — use the specific node alias instead.

  • The user@ prefix overrides the default login user for the node. Without it, Kiso uses the user configured by the testbed (e.g. cc for Chameleon bare metal, rocky for FABRIC Rocky images).

  • --ssh-options accepts a shell-quoted string; shlex.split is used internally so quoting and escaping follow standard shell rules.

  • Not supported on Chameleon Edge — those resources are containers without SSH access.

kiso version#

Display the version information.

kiso version

Examples:

kiso version

Typical workflow#

# 1. Validate the config
kiso check experiment.yml

# 2. Provision and configure
kiso up experiment.yml

# 3. (Optional) Inspect a node while resources are up
kiso ssh submit-host

# 4. Run experiments and collect results
kiso run experiment.yml

# 5. Tear down
kiso down experiment.yml

See also#