Commands

Tarsail commands use this shape:

tarsail [global options] <command> [command options]

Global options

Option	Value	Description
--config	path	Path to the Tarsail config file. Default: tarsail.yml.
--identity-file	path	SSH private key file used for remote access.
--ssh-key	path	Alias for --identity-file.
--ask-password	boolean	Prompt once for the remote user’s SSH password.
--verbose	boolean	Show verbose command output where available.
--yes	boolean	Answer yes to confirmation prompts that support it.
-v, --version	boolean	Show Tarsail version and exit.

--identity-file and --ask-password cannot be used together.

--identity-file supports ~/ expansion and is resolved to an absolute path before use.

init

Create a minimal config file.

tarsail init

With a custom path:

tarsail --config tarsail.production.yml init

init refuses to overwrite an existing config file.

It detects a Compose file in this order:

1. compose.yaml
2. compose.yml
3. docker-compose.yaml
4. docker-compose.yml

If none is found, it writes compose.yaml.

Generated config:

project: my-app

target:
  name: prod
  host: example.com
  user: deploy
  port: 22
  path: /opt/my-app

compose:
  file: compose.yaml

deploy:
  keep_releases: 3

doctor

Check local and remote deployment readiness.

tarsail doctor

Common forms:

tarsail --config tarsail.production.yml doctor
tarsail --identity-file ~/.ssh/my-app-deploy-key doctor
tarsail --ask-password doctor

Local checks:

• config loads;
• Compose file exists;
• Docker command is available;
• Docker Compose is available;
• Docker daemon is reachable;
• Compose images are discoverable.

Remote checks:

• SSH connects;
• target path is writable;
• required shared files exist;
• Docker is available;
• Docker Compose is available.

doctor may create the basic remote target layout when checking path writability:

releases/
incoming/
shared/

deploy

Build, bundle, upload, load, activate, and start the app.

tarsail deploy

Common forms:

tarsail --identity-file ~/.ssh/my-app-deploy-key deploy
tarsail --ask-password deploy
tarsail --config tarsail.production.yml --ask-password deploy

Steps:

1. check local environment;
2. check remote server;
3. upload configured env and secret files;
4. build images;
5. create bundle;
6. upload bundle;
7. load images;
8. start Compose app;
9. read status.

The generated release ID is available to local and remote Compose as TARSAIL_RELEASE_ID.

status

Show remote Docker Compose status for the active release.

tarsail status

Equivalent remote operation:

cd <target.path>
docker compose -p <project> --env-file current/.tarsail.env --env-file shared/.env -f current/compose.yaml ps

The shared env file is included only when compose.env_file is configured.

logs

Show remote Compose logs.

tarsail logs

Service-specific logs:

tarsail logs web

Options:

Option	Value	Description
--tail	number	Number of log lines to show. Default: 200. Allowed range: 1 to 10000.
-f	boolean	Follow logs.

Examples:

tarsail logs --tail 100
tarsail logs --tail 500 web
tarsail logs -f web

Service name validation allows letters, numbers, dot, underscore, and hyphen.

rollback

Reactivate the previous release.

tarsail rollback

Rollback:

• reads the current release from the current symlink;
• chooses the previous valid release by release metadata;
• loads images from that release;
• updates current;
• runs Compose;
• prints status.

Rollback does not restore data stores, Docker volumes, shared/ files, or external services.

prune

Delete old non-current release directories.

tarsail prune

Skip confirmation:

tarsail prune --yes

or:

tarsail --yes prune

The number of kept releases comes from:

deploy:
  keep_releases: 3

Allowed range for keep_releases is 1 to 20.

version

Show the installed Tarsail version.

tarsail version

Release binaries use a date-plus-hash version string such as 20260622-194500-a1b2c3d4e5f6.

Equivalent:

tarsail -v
tarsail --version

Verbose version output includes commit and build time when the binary was built by the GitHub Release workflow:

tarsail --verbose version

help

Show command usage:

tarsail help
tarsail --help
tarsail -h