Download client

The Machine client is a self-contained program called machine.

You need an account to download the client, and must accept the Terms of Service and the Client EULA that licenses it. The installer signs you in, or signs you up, with a code sent to your email, before it downloads anything.

Pick your system.

Install

Run this in a terminal.

1
curl https://testflows.com/machine/install -fsS | bash

It verifies the download and puts the client in ~/.local/bin, with machine-env beside it. It never asks for root. Run the same command again to update.

The client needs the OpenSSH client, ssh, which most Linux systems have. If yours does not, run sudo apt install openssh-client on Debian and Ubuntu.

Automated install

For automated installations, use your API key:

1
curl https://testflows.com/machine/install -fsS | TESTFLOWS_MACHINE_API_KEY=<key> bash

The installer also reads the key from the environment. It must be exported: a variable set without export is not passed to the installer. A CI secret is exported already.

1
2
export TESTFLOWS_MACHINE_API_KEY=<key>
curl https://testflows.com/machine/install -fsS | bash

Then

The installer signs out when it is done. Sign the client in with machine login. The docs walk through your first run.

machine-env

The installer also writes machine-env beside machine. It starts a shell in which machine is this client, ahead of any other machine on your PATH. If another command on your system is also named machine, use machine-env. which machine shows which one you get. It is the same file on every system. The prompt starts with (machine), your usual shell setup is loaded, and exit leaves. It supports zsh and bash.

1
2
3
4
5
$ machine-env
(machine) $ machine login
(machine) $ machine --version
(machine) $ exit
$

The (machine) at the start of the prompt says you are in it: there machine is this client. exit leaves it, back to the shell you were in. To run one command there without starting a shell:

1
machine-env -- machine --version

That form runs one command in that environment and starts no shell, for scripts.

Tab completion

In machine-env, Tab completes commands, options and the names of your runs. To have it in every shell, add the line for your shell to its startup file. The installer prints the one for yours when it finishes.

1
2
3
eval "$(machine completion bash)"     # ~/.bashrc
eval "$(machine completion zsh)" # ~/.zshrc
machine completion fish | source # ~/.config/fish/config.fish

Check the download

The installer already verifies every download. To check by hand, download the files without installing them, with your version in place of YYYYMMDD-HHMM (machine --version shows it):

1
2
mkdir machine-check && cd machine-check
curl https://testflows.com/machine/install -fsS | MACHINE_VERSION=YYYYMMDD-HHMM bash -s -- --download

That fetches machine, its checksum, and two signatures of the checksum. We sign only the checksum, so verify the signature first, with either tool.

With GPG, the key's fingerprint must match the GPG fingerprint. gpg then prints Good signature; its warning that the key is not certified is normal.

1
2
3
4
curl -fsSO https://testflows.com/machine/keys/machine-client-gpg.asc
gpg --show-keys --fingerprint machine-client-gpg.asc
gpg --import machine-client-gpg.asc
gpg --verify machine.sha256.asc machine.sha256

With openssl, a good signature prints Verified OK:

1
2
curl -fsSO https://testflows.com/machine/keys/machine-client-rsa.pub.pem
openssl dgst -sha256 -verify machine-client-rsa.pub.pem -signature machine.sha256.sig machine.sha256

Last, check the file against the checksum, and against the client you installed. If a check fails, delete the client and install again.

1
2
sha256sum -c machine.sha256
cmp machine "$(command -v machine)"

To read the installer before you run it, pipe it to less instead of bash.

Uninstall

Sign out, then delete the client and what it stored.

1
2
3
machine logout
rm ~/.local/bin/machine ~/.local/bin/machine-env
rm -rf ~/.cache/machine ~/.testflows/machine

Install

Run this in a terminal.

1
curl https://testflows.com/machine/install -fsS | bash

It verifies the download and puts the client in ~/.local/bin, with machine-env beside it. It never asks for root. Run the same command again to update.

The client needs the OpenSSH client, ssh, which most Linux systems have. If yours does not, run sudo apt install openssh-client on Debian and Ubuntu.

Automated install

For automated installations, use your API key:

1
curl https://testflows.com/machine/install -fsS | TESTFLOWS_MACHINE_API_KEY=<key> bash

The installer also reads the key from the environment. It must be exported: a variable set without export is not passed to the installer. A CI secret is exported already.

1
2
export TESTFLOWS_MACHINE_API_KEY=<key>
curl https://testflows.com/machine/install -fsS | bash

Then

The installer signs out when it is done. Sign the client in with machine login. The docs walk through your first run.

machine-env

The installer also writes machine-env beside machine. It starts a shell in which machine is this client, ahead of any other machine on your PATH. If another command on your system is also named machine, use machine-env. which machine shows which one you get. It is the same file on every system. The prompt starts with (machine), your usual shell setup is loaded, and exit leaves. It supports zsh and bash.

1
2
3
4
5
$ machine-env
(machine) $ machine login
(machine) $ machine --version
(machine) $ exit
$

The (machine) at the start of the prompt says you are in it: there machine is this client. exit leaves it, back to the shell you were in. To run one command there without starting a shell:

1
machine-env -- machine --version

That form runs one command in that environment and starts no shell, for scripts.

Tab completion

In machine-env, Tab completes commands, options and the names of your runs. To have it in every shell, add the line for your shell to its startup file. The installer prints the one for yours when it finishes.

1
2
3
eval "$(machine completion bash)"     # ~/.bashrc
eval "$(machine completion zsh)" # ~/.zshrc
machine completion fish | source # ~/.config/fish/config.fish

Disks hold x86_64 programs

A machine is an x86_64 computer, so its disks hold linux/amd64 programs. Docker on ARM builds arm64 images by default, so ask for linux/amd64:

1
2
docker build --platform linux/amd64 -t myapp:latest .
docker pull --platform linux/amd64 myapp:latest

The docs cover Compose projects and binaries.

Check the download

The installer already verifies every download. To check by hand, download the files without installing them, with your version in place of YYYYMMDD-HHMM (machine --version shows it):

1
2
mkdir machine-check && cd machine-check
curl https://testflows.com/machine/install -fsS | MACHINE_VERSION=YYYYMMDD-HHMM bash -s -- --download

That fetches machine-linux-arm64, its checksum, and two signatures of the checksum. We sign only the checksum, so verify the signature first, with either tool.

With GPG, the key's fingerprint must match the GPG fingerprint. gpg then prints Good signature; its warning that the key is not certified is normal.

1
2
3
4
curl -fsSO https://testflows.com/machine/keys/machine-client-gpg.asc
gpg --show-keys --fingerprint machine-client-gpg.asc
gpg --import machine-client-gpg.asc
gpg --verify machine-linux-arm64.sha256.asc machine-linux-arm64.sha256

With openssl, a good signature prints Verified OK:

1
2
curl -fsSO https://testflows.com/machine/keys/machine-client-rsa.pub.pem
openssl dgst -sha256 -verify machine-client-rsa.pub.pem -signature machine-linux-arm64.sha256.sig machine-linux-arm64.sha256

Last, check the file against the checksum, and against the client you installed. If a check fails, delete the client and install again.

1
2
sha256sum -c machine-linux-arm64.sha256
cmp machine-linux-arm64 "$(command -v machine)"

To read the installer before you run it, pipe it to less instead of bash.

Uninstall

Sign out, then delete the client and what it stored.

1
2
3
machine logout
rm ~/.local/bin/machine ~/.local/bin/machine-env
rm -rf ~/.cache/machine ~/.testflows/machine

Install

Run this in Terminal.

1
curl https://testflows.com/machine/install -fsS | bash

It verifies the download and installs the client under ~/.local/share/machine/. It writes machine-env to ~/.local/bin. It never asks for your password. Run the same command again to update.

Macs with an Intel processor are not supported.

macOS already has a machine command. The installer keeps this client off your PATH so it does not hide that one. Use machine-env, below, to run this one.

Automated install

For automated installations, use your API key:

1
curl https://testflows.com/machine/install -fsS | TESTFLOWS_MACHINE_API_KEY=<key> bash

The installer also reads the key from the environment. It must be exported: a variable set without export is not passed to the installer. A CI secret is exported already.

1
2
export TESTFLOWS_MACHINE_API_KEY=<key>
curl https://testflows.com/machine/install -fsS | bash

Then

The installer signs out when it is done. Sign the client in with machine login. The docs walk through your first run.

macOS has its own machine command

macOS ships /usr/bin/machine, which prints the processor type, such as arm64. Putting this client on your PATH would hide the system one for every other program, so the installer does not. machine-env is the way in. It starts a shell in which machine is this client and leaves the rest of your system alone. The prompt starts with (machine), your usual shell setup is loaded, and exit leaves. It supports zsh and bash.

1
2
3
4
5
$ machine-env
(machine) $ machine login
(machine) $ machine --version
(machine) $ exit
$

The (machine) at the start of the prompt says you are in it: there machine is this client. exit leaves it, back to the shell you were in. To run one command there without starting a shell:

1
machine-env -- machine --version

That form runs one command in that environment and starts no shell, for scripts and CI. Outside it, machine is the system's command, and machine --version prints a processor type. Inside it, which machine shows ~/.local/share/machine/bin/machine. If your shell cannot find machine-env, run ~/.local/bin/machine-env, or put ~/.local/bin on your PATH. That directory holds machine-env alone, so nothing is hidden:

1
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Then open a new terminal. The installer offers to add this line for you when it finds the directory missing from your PATH: it asks first, and writes nothing unless you say yes. Linux and every other system get the same machine-env file.

Tab completion

In machine-env, Tab completes commands, options and the names of your runs. There is nothing to add to a startup file: outside machine-env, machine is the system's command, and a completion line there would run that one.

Disks hold x86_64 programs

A machine is an x86_64 computer, so its disks hold linux/amd64 programs. Docker on ARM builds arm64 images by default, so ask for linux/amd64:

1
2
docker build --platform linux/amd64 -t myapp:latest .
docker pull --platform linux/amd64 myapp:latest

The docs cover Compose projects and binaries.

Check the download

The installer already verifies every download. To check by hand, download the files without installing them, with your version in place of YYYYMMDD-HHMM (machine --version shows it):

1
2
mkdir machine-check && cd machine-check
curl https://testflows.com/machine/install -fsS | MACHINE_VERSION=YYYYMMDD-HHMM bash -s -- --download

That fetches machine-darwin-arm64.tar.gz, its checksum, and two signatures of the checksum. We sign only the checksum, so verify the signature first, with either tool. Macs ship with openssl but not gpg.

With GPG, the key's fingerprint must match the GPG fingerprint. gpg then prints Good signature; its warning that the key is not certified is normal.

1
2
3
4
curl -fsSO https://testflows.com/machine/keys/machine-client-gpg.asc
gpg --show-keys --fingerprint machine-client-gpg.asc
gpg --import machine-client-gpg.asc
gpg --verify machine-darwin-arm64.tar.gz.sha256.asc machine-darwin-arm64.tar.gz.sha256

With openssl, a good signature prints Verified OK:

1
2
curl -fsSO https://testflows.com/machine/keys/machine-client-rsa.pub.pem
openssl dgst -sha256 -verify machine-client-rsa.pub.pem -signature machine-darwin-arm64.tar.gz.sha256.sig machine-darwin-arm64.tar.gz.sha256

Last, check the archive against the checksum. If it fails, delete it and install again.

1
shasum -a 256 -c machine-darwin-arm64.tar.gz.sha256

To read the installer before you run it, pipe it to less instead of bash.

Uninstall

Sign out, then delete the client and what it stored. An install from before the client was kept off your PATH also has ~/.local/bin/machine, which rm -f removes.

1
2
3
machine logout
rm -f ~/.local/bin/machine ~/.local/bin/machine-env
rm -rf ~/.local/share/machine ~/.testflows/machine

Install

The client runs inside WSL, the Linux that comes with Windows. If you don't have WSL yet, install it from PowerShell, then restart:

1
wsl --install

Open your Linux distribution and follow the steps for Linux (x64), or Linux (ARM64) on Windows on ARM. Not sure which? uname -m prints x86_64 or aarch64.

Automated install

For automated installations, use your API key:

1
curl https://testflows.com/machine/install -fsS | TESTFLOWS_MACHINE_API_KEY=<key> bash

The installer also reads the key from the environment. It must be exported: a variable set without export is not passed to the installer. A CI secret is exported already.

1
2
export TESTFLOWS_MACHINE_API_KEY=<key>
curl https://testflows.com/machine/install -fsS | bash

Then

The installer signs out when it is done. Sign the client in with machine login. The docs walk through your first run.

Other systems

Linux (x64 and ARM64) and Macs with Apple Silicon are supported. On Windows, use WSL.

Need another platform? Tell us which one.

Release keys

Every release's checksum is signed with two keys: a GPG key, whose fingerprint is published as the GPG fingerprint, and an RSA key for openssl.

If the keys change, this page and the installer carry the new ones. A check that fails with an old key should pass once you download again.

Upgrade

An installed client upgrades itself. machine upgrade runs the installer with the client's own sign-in, so it asks for nothing, and the client stays signed in. machine upgrade --list shows the versions there are, and machine upgrade YYYYMMDD-HHMM installs one of them:

1
2
3
machine upgrade
machine upgrade --list
machine upgrade YYYYMMDD-HHMM

A client older than 20261106-1345 has no machine upgrade. It upgrades with the install command above.

A specific version

The installer gets the latest release. --list shows the versions there are, newest first, and --version installs one of them:

1
2
curl https://testflows.com/machine/install -fsS | bash -s -- --list
curl https://testflows.com/machine/install -fsS | bash -s -- --version YYYYMMDD-HHMM

Set MACHINE_INSTALL_DIR to install somewhere other than ~/.local/bin. --no-signature and --no-checksum skip checks; a normal install needs neither.