# 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 [command] [options] km connect [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 [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 [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 ...`. 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 ` 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"; ```