Skip to content
turnoutturnout

Getting Started

Install

Section titled “Install”

One line on Windows (PowerShell):

Terminal window
irm https://raw.githubusercontent.com/lacodda/turnout/main/tools/install.ps1 | iex

One line on macOS / Linux:

Terminal window
curl -fsSL https://raw.githubusercontent.com/lacodda/turnout/main/tools/install.sh | sh

Via npm:

Terminal window
npm i -g turnout-cli

Via cargo:

Terminal window
cargo install turnout

Or download the archive for your platform from Releases (Windows x86_64, Linux x86_64, macOS arm64), unpack and put turnout on your PATH.

Installer options

Section titled “Installer options”

Both scripts read two environment variables:

Variable Effect
TURNOUT_VERSION Install this tag (e.g. v0.10.1) instead of the newest release
TURNOUT_INSTALL_DIR Where the binary lands; defaults to %LOCALAPPDATA%\Programs\turnout on Windows and ~/.local/bin elsewhere

The tn alias

Section titled “The tn alias”

The installers and the npm package also set up tn as a short second name, so tn use web staging is the same as turnout use web staging. It is skipped when something else in your PATH already answers to tn; set TURNOUT_NO_ALIAS=1 to opt out entirely. Installing through cargo install gives you turnout only - add your own alias if you want the short form.

First run

Section titled “First run”
Terminal window
turnout setup

The wizard shows where turnout will keep its data and creates the directory:

OS Data directory
Windows %LOCALAPPDATA%\lacodda\turnout
macOS ~/Library/Application Support/lacodda/turnout
Linux ~/.local/share/lacodda/turnout

Set the TURNOUT_DATA_DIR environment variable to override the location (useful for tests and scripting). Pass --yes to skip prompts.

Once a day turnout also checks whether a newer release exists and mentions it at the end of a command. The lookup runs in the background, so it never delays anything; TURNOUT_UPDATE_CHECK=0 switches it off. See the update check.

Check the state

Section titled “Check the state”
Terminal window
turnout status

Shows the data directory, the four catalogs - apps, servers, credentials, paths - and whether the gateway is running.

Describe your first app and server

Section titled “Describe your first app and server”
Terminal window
cd ~/dev/myapp
turnout app add        # wizard: detects the project type, proposes commands
turnout server add     # wizard: URL, SSH host, credential, TLS policy

That is enough for the dev gateway. Deploying also needs to know who logs in and where files land:

Terminal window
turnout credential add prod-deploy --user deploy
turnout path add wwwroot --dir /var/www/myapp --restart "systemctl restart myapp"
turnout server edit prod --credential prod-deploy --deploy-path myapp=wwwroot

Or let one wizard walk all of it, offering to create the credential and path as it goes:

Terminal window
turnout deploy-setup myapp

See turnout app, turnout server, turnout credential and turnout path for the full command reference.

A working day

Section titled “A working day”
Terminal window
turnout gateway start          # once: the gateway routes apps to their stands
turnout use myapp staging      # bind the app to a stand
turnout dev                    # from the project dir: UI local, API on staging
turnout pass copy prod-deploy  # password on the clipboard when the stand asks
turnout use myapp prod-eu      # switch stands - no restarts, no env edits

Next steps

Section titled “Next steps”