mw — the mittwald command-line tool

Synposis

mw is the command-line tool for interacting with the mittwald mStudio v2 API.

Getting started

Installation

macOS, using Homebrew

Installation using Homebrew is the recommended way of installation on macOS.

$ brew tap mittwald/cli
$ brew install mw

Windows, using the Installer

Find the appropriate Windows installer from the releases page and run the installer. After running the installer, you should be able to use the mw command on either the CMD prompt or PowerShell.

Any OS, using Node.js+NPM

Installing the CLI via NPM will work on any OS; however we cannot guarantee stability, because functionality of the CLI may depend on the Node.js runtime already installed on your system. Also, the automatic upgrade will not work when using NPM; remember to run npm upgrade -g @mittwald/cli occasionally.

$ npm install -g @mittwald/cli

Attention! When installing via -g flag, make sure you have nodejs >= 20.7.0 installed, as package definition is ignored for global installations!

Any OS, using Docker

There is also the mittwald/cli Docker image that you can use instead of installing the CLI on your system. Pass your mStudio API token as the MITTWALD_API_TOKEN environment variable instead of logging in as described below:

$ export MITTWALD_API_TOKEN=<enter token here>
$ docker run --rm -it -e MITTWALD_API_TOKEN mittwald/cli help

See Using the Docker image for SSH-based commands, local files, port forwarding and a shell function that lets you use the image like a local mw install.

Authentication

To use the CLI, you will need an mStudio API token. With your token in your clipboard, run the mw login token command:

$ mw login token
Enter your mStudio API token: ****************
token saved to '/Users/mhelmich/.config/mw/token'

Setting up shell autocompletion

The mw CLI offers a lot of commands and flags, and it can be hard to remember all of them. To make your life easier, the CLI offers autocompletion for the Bash and ZSH shells. To enable autocompletion, run the following command:

$ mw autocomplete

After that, follow the instructions printed by that command (those are specific to your shell -- Bash, ZSH and Powershell are supported).

Using the Docker image

Every run of the mittwald/cli Docker image starts a fresh container, so mw context set does not persist; pass IDs like --project-id explicitly.

SSH-based commands

Commands that connect via SSH (like mw container exec, mw app ssh or mw app download) need your SSH private key inside the container. Mount it read-only and point MITTWALD_SSH_IDENTITY_FILE to it; adjust the file name if your key is not id_ed25519. With --mount, docker fails if the key does not exist instead of creating an empty directory in its place. The examples below show the mount.

Local files and file ownership

Mount your working directory if a command reads or writes local files, and use paths relative to it; everything written elsewhere is lost when the container exits.

The container runs as root unless you set MW_UID (and optionally MW_GID, which defaults to MW_UID). With them, the CLI runs as a user with your IDs, so on Linux the downloaded files belong to you instead of root:

$ docker run --rm -it -e MITTWALD_API_TOKEN \
    --mount type=bind,source="$HOME/.ssh/id_ed25519",target=/ssh/id_ed25519,readonly \
    -e MITTWALD_SSH_IDENTITY_FILE=/ssh/id_ed25519 \
    -e MW_UID="$(id -u)" -e MW_GID="$(id -g)" \
    -v "$PWD:/work" -w /work \
    mittwald/cli app download <app-id> --target ./app

Using the image like a local mw install

Add a small function to your ~/.bashrc or ~/.zshrc. It only allocates a TTY when you run it interactively, so piping (e.g. mw project list -o json | jq) keeps working. Set MW_SSH_KEY if your key is not ~/.ssh/id_ed25519; only that one key is mounted into the container, and only if it exists, so commands without SSH work without a key:

mw() {
  local key="${MW_SSH_KEY:-$HOME/.ssh/id_ed25519}"
  local args=(--rm -i -e MITTWALD_API_TOKEN -e MW_UID="$(id -u)" -e MW_GID="$(id -g)"
    -v "$PWD:/work" -w /work)
  [ -t 0 ] && [ -t 1 ] && args+=(-t)
  [ -f "$key" ] && args+=(
    --mount "type=bind,source=$key,target=/ssh/key,readonly"
    -e MITTWALD_SSH_IDENTITY_FILE=/ssh/key
  )
  docker run "${args[@]}" mittwald/cli "$@"
}

Port forwarding

For mw container port-forward, also publish the local port of the forwarding to your host:

$ docker run --rm -it -e MITTWALD_API_TOKEN \
    --mount type=bind,source="$HOME/.ssh/id_ed25519",target=/ssh/id_ed25519,readonly \
    -e MITTWALD_SSH_IDENTITY_FILE=/ssh/id_ed25519 \
    -p 127.0.0.1:3306:3306 \
    mittwald/cli container port-forward <container-id> 3306 --project-id <project-id>

Inside the container, forwardings listen on all interfaces so that docker can publish them. Keep the 127.0.0.1: prefix in -p, and do not combine port forwarding with --network host or a docker network shared with other containers: the forwarded port would be reachable from your local network or from those containers.

Contributing

If you are a developer (either at @mittwald or an external contributor) and want to contribute to the CLI, please refer to the CONTRIBUTING.md document.

Usage

$ npm install -g @mittwald/cli
$ mw COMMAND
running command...
$ mw (--version)
@mittwald/cli/1.0.0 darwin-arm64 node-v18.11.0
$ mw --help [COMMAND]
USAGE
  $ mw COMMAND
...

Command Topics

• mw app - Manage apps, and app installations in your projects
• mw autocomplete - Display autocomplete installation instructions.
• mw backup - Manage backups of your projects
• mw container - Manage containers
• mw context - Save certain environment parameters for later use
• mw conversation - Manage your support cases
• mw cronjob - Manage cronjobs of your projects
• mw database - Manage databases (like MySQL and Redis) in your projects
• mw ddev - Integrate your mittwald projects with DDEV
• mw domain - Manage domains, virtual hosts and DNS settings in your projects
• mw experimental - Experimental features, which are not considered stable yet and might change without a major version bump
• mw extension - Install and manage extensions in your organisations and projects
• mw help - Display help for mw.
• mw login - Manage your client authentication
• mw mail - Manage mailboxes and mail addresses in your projects
• mw org - Manage your organizations, and also any kinds of user memberships concerning these organizations.
• mw project - Manage your projects, and also any kinds of user memberships concerning these projects.
• mw registry - Manage container registries
• mw server - Manage your servers
• mw sftp-user - Manage SFTP users of your projects
• mw ssh-user - Manage SSH users of your projects
• mw stack - Manage container stacks
• mw update - update the mw CLI
• mw user - Manage your own user account
• mw volume - Manage volumes