komodo/docsite/docs/ecosystem/cli.mdx

# Komodo CLI

The Komodo CLI, `km`, can be used to:
  - Quickly **run executions** and update **resources** and **variables**.
  - **Reset user passwords** and elevate users to **Super Admin**.
  - Perform Database **backup**, **restore**, and **copy**.
  - **Connect to server / container shell** via Komodo Terminals.

The Komodo Core image comes packaged with the Komodo CLI,
and is available for usage inside running container with `docker exec -it komodo-core km ...`.
This way, it inherits the Core database config in order to easily perform backups with `km db backup -y`.

### Examples

  - `km --help`
  - `km deploy stack my-stack`
  - `km run action my-action -y`
  - `km database backup`
  - `km db restore`
  - `km set var MY_VAR my_value -y`
  - `km update build my-build "version=1.19.0&branch=release"`
  - `km x commit my-sync`
  - `km set user mbecks super-admin true`
  - `km set user mbecks password "temp-password"`
  - `km ssh my-server`
  - `km connect my-server bash -n my-session`
  - `km exec my-container bash`
  - `km attach my-container -s my-server`

### Terminals

All terminal commands share the same disconnect shortcut: press **Alt+Q** to end the session.
The session itself stays running and will keep the history if you connect again, or connect from a
different device.

#### SSH / Connect

The `km ssh` command (alias for `km connect`) opens an interactive shell on a server managed by Komodo Periphery. Analogous to `ssh`.

```
km ssh <server> [command] [options]
km connect <server> [command] [options]
```

| Argument | Description |
|---|---|
| `server` | Server name (required) |
| `command` | Shell command to start, e.g. `bash` (optional, defaults to Periphery default) |
| `-n`, `--name` | Terminal session name (default: `ssh`) |
| `-r`, `--recreate` | Force a fresh terminal, replacing any existing session with the same name |

#### Exec

The `km exec` command opens an interactive shell inside a running container. Analogous to `docker exec`.

```
km exec <container> <shell> [options]
```

| Argument | Description |
|---|---|
| `container` | Container name (required) |
| `shell` | Shell to use, e.g. `bash` or `sh` (required) |
| `-s`, `--server` | Server name — required if multiple servers have a container with the same name |
| `-r`, `--recreate` | Force a fresh terminal, replacing any existing session |

#### Attach

The `km attach` command attaches to a running container's main process stdio. Analogous to `docker attach`.

```
km attach <container> [options]
```

| Argument | Description |
|---|---|
| `container` | Container name (required) |
| `-s`, `--server` | Server name — required if multiple servers have a container with the same name |
| `-r`, `--recreate` | Force a fresh terminal, replacing any existing session |

### Install

There are binaries available for **Linux** (x86_64 / aarch64), **MacOS** (apple silicon), as
well as a distroless image: **`ghcr.io/moghtech/komodo-cli`**.

#### Linux

You can install the binary using the following command:

System-wide, as root, to `/usr/local/bin/km`:
```bash
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/install-cli.py | python3
```

Or as non-root, to `${HOME}/.local/bin/km`:
```bash
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/install-cli.py | python3 - --user
```

#### MacOS (Homebrew)

Add the `moghtech/komodo` tap, then install `km`:
```bash
brew tap moghtech/komodo && \
  brew install km
```

#### Container

You can alias a docker run command:
```bash
alias km='docker run --rm -v $HOME/.config/komodo:/config ghcr.io/moghtech/komodo-cli:2 km'
km config
```

### Configure

The CLI uses a configuration file to pass the Komodo host / api keys, database address and credentials,
and configure some other behaviors. Additionally, all configuration fields can be individually overridden
using **CLI arguments** or **environment variables**, with CLI arguments having top priority.

Whenever you want to check how config will be loaded, you can use the `km config` command
to print it out.

#### File detection

When run, CLI will scan the **current working directory** in addition to `${HOME}/.config/komodo` for any files matching the wildcard pattern **`*komodo.cli*.*`**,
parse them into a general representation, and then merge them together. Files which are detected later are merged later,
meaning they will override on conflicting fields. By default, files in `${HOME}/.config/komodo` come first
in the merge ordering, meaning they are **lower priority** than those detected in the current working directory.
You can also override these default paths by passing `km -c /path/to/1/base.config.yaml -c ./overrides ...`.

If you want `km` to find configuration files in another directory,
you can make a `.kminclude` file inside one of the configured directories.

```
# Supports comments

./.komodo    # relative to directory containing `.kminclude`

/etc/komodo/komodo.cli.toml  # also supports absolute path
```

Note that wildcards in these paths are **not supported**.

#### Profiles

In the files, you can configure multiple profiles, each with a name / aliases. Then you
choose which config profile to use with `km -p <profile> ...`. This allows you to easily switch between
multiple Cores you want to connect to, or different database backup / restore options.

In order to avoid passing `-p <profile>` every time, you can set a
`default_profile` at the top level of the configuration file. Additionally,
any fields you would like to be the "default" across all profiles can be 
set at the top level of the file.

#### Example File

The configuration can also be passed as **YAML** or **JSON**.
You can use it-tools to convert this TOML file to your preferred format:
  - YAML: https://it-tools.tech/toml-to-yaml
  - JSON: https://it-tools.tech/toml-to-json

Quick download to `./komodo/komodo.cli.toml`:
```bash
wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/komodo.cli.toml
```

```mdx-code-block
import RemoteCodeFile from "@site/src/components/RemoteCodeFile";

<RemoteCodeFile
	title="https://github.com/moghtech/komodo/blob/main/config/komodo.cli.toml"
	url="https://raw.githubusercontent.com/moghtech/komodo/main/config/komodo.cli.toml"
	language="toml"
/>
```