Install the CLI
shipwick is the Shipwick command-line client. This page covers installing it on your laptop or in CI, keeping it current with shipwick upgrade, saving the agent's URL and token with shipwick login, working with several servers, and how the CLI decides which agent to talk to.
Start here. The CLI is the first thing to install, because with it on your laptop the server is installed from there: shipwick server install [email protected] --agent-domain agent.example.com --dashboard-domain dashboard.example.com runs the installer over SSH and saves the token for you; see Install on a server. The quickest way to the CLI on macOS and Linux:
curl -fsSL https://get.shipwick.com | sh -s -- --cliOn Windows, in PowerShell:
irm https://get.shipwick.com/windows | iexThe server installer also puts shipwick on the server, and since 0.5 signs it in to its own agent when the API has a hostname; see On the server.
Homebrew
On macOS and Linux:
brew install shipwick/tap/shipwickUpgrade with brew upgrade shipwick; shipwick upgrade recognizes a Homebrew installation and prints that line instead of replacing the binary itself. Completions for bash, zsh and fish are installed along with it. The formula installs the same binaries as the installer below, verified against the same checksums; it lives in shipwick/homebrew-tap and is updated with each release.
The installer
curl -fsSL https://get.shipwick.com | sh -s -- --cliWith --cli, the installer installs shipwick and nothing else. It needs neither root nor Docker. It downloads the binary for your platform (Linux or macOS, amd64 or arm64) from the latest release, verifies it against the release's checksums.txt, and moves it to /usr/local/bin. If the checksum does not match, nothing is installed.
Shipwick installer (shipwick/shipwick@latest)
✓ Installed the shipwick CLI to /usr/local/bin/shipwick
Next: shipwick loginIf /usr/local/bin is not writable, the installer uses sudo to move the binary into place. To install somewhere else, set SHIPWICK_BIN_DIR to a directory on your PATH:
curl -fsSL https://get.shipwick.com | SHIPWICK_BIN_DIR="$HOME/.local/bin" sh -s -- --cliTo install a specific version, set SHIPWICK_VERSION:
curl -fsSL https://get.shipwick.com | SHIPWICK_VERSION=v1.1.0 sh -s -- --cliWindows
Since 0.9 the CLI installs on Windows with one line, in Windows PowerShell 5.1 or PowerShell 7:
irm https://get.shipwick.com/windows | iexIt downloads shipwick_windows_amd64.exe — or the Arm64 build, on a machine with an Arm processor — and checksums.txt from the latest release, verifies the binary's SHA-256 against the one the release lists, puts it at %LOCALAPPDATA%\Programs\shipwick\shipwick.exe and adds that directory to your PATH, once. Terminals that are already open keep the PATH they started with until they are opened anew. A mismatch installs nothing. A shipwick.exe already on your PATH ahead of that directory — one put somewhere by hand — is named, because it would go on being the one that runs.
Where cosign (2.5 or later) is installed, checksums.txt is first verified against the release's signature, with the release workflow at exactly that tag as the identity, and the installer stops if it is not the workflow's; without cosign it says in one line that the signature was not checked. SHIPWICK_REQUIRE_SIGNATURE=1 turns that, and a release without a signature, into a refusal, as for the Unix installer. See Verify a release.
A release of your choice: set SHIPWICK_VERSION before the command, or save the script — scripts/install.ps1, a file of every release from 0.10.0 on — and run it with -Version; -Destination names another directory:
$env:SHIPWICK_VERSION = 'v1.1.0'; irm https://get.shipwick.com/windows | iex
.\install.ps1 -Version v1.1.0 -Destination C:\tools\shipwickRunning it again upgrades, as does shipwick upgrade, below, which picks the build for the machine also when the shipwick that runs is the x64 one. Until 0.9 the way was to download the .exe from the releases page and put it on your PATH; that still works.
From source
With Go 1.27 or later, from a checkout of the repository:
go build -o bin/shipwick ./cli/cmd/shipwick # or: make buildCheck the installation
shipwick --versionUpgrade
shipwick upgrade replaces the running binary with the latest release, then compares the server's version with it:
shipwick upgrade✓ Upgraded shipwick v0.3.1 → v1.1.0
/usr/local/bin/shipwick
The server runs v0.3.1; v1.1.0 is available. On the server run:
curl -fsSL https://get.shipwick.com | shThe release is downloaded from GitHub and verified against the release's checksums.txt before anything changes; the new binary is written next to the old one and renamed over it only once its SHA-256 matches. Since 0.8, where cosign (2.5 or later) is installed, checksums.txt is first verified against the release's signature, a signature that does not verify changes nothing, and a release from 0.8.0 on that has no signature is refused; without cosign the command says The release's signature was not checked: cosign is not installed on this machine. and goes by the checksums. See Verify a release. On Windows the replaced binary is left behind as shipwick.old.exe and removed the next time shipwick runs. If the directory is not writable, the command says so and suggests sudo shipwick upgrade, or running the installer again.
Without --version the latest release is installed, never a pre-release. Since 0.9, shipwick upgrade --version <tag> installs exactly that release, a pre-release included, in place of whatever runs now, with the same checksum and signature verification: the way to try a release candidate, and the way back from one. The server is then compared with that release, and the installer line the command prints names it. A pre-release ahead of the latest release counts as current afterwards: upgrade --check and doctor do not offer the release it precedes until that release is out. A development build — shipwick --version reads dev, or v0.8.1-3-gabcdef for a build made past a tag — is not a release: it is neither upgraded nor told that a release is available, and both commands say that it is a development build.
shipwick upgrade --version v1.1.0-rc.1The command upgrades only the CLI. The server is upgraded by running the installer on the server, which needs Docker there, or with shipwick server install user@host from your machine; shipwick upgrade tells you when the server is behind, and says The server runs v1.1.0, the latest release. when it is not — or ahead of the latest release (v1.1.0) for a server on a pre-release. A server that cannot be reached is one line, not an error.
A shipwick installed with Homebrew is left to Homebrew:
shipwick v0.3.1 was installed with Homebrew; v1.1.0 is available.
Upgrade with: brew upgrade shipwick--check only reports:
shipwick upgrade --checkshipwick v0.3.1 is installed; v1.1.0 is available.
Upgrade with: shipwick upgradeWhen there is nothing to do, the first line reads shipwick v1.1.0 is up to date.
Log in
shipwick login saves the agent's URL and the API token for later commands. After shipwick server install you are logged in already: it saved the token as a context. You need login when the installer ran on the server itself, on a second machine, or with a token someone created for you.
shipwick login --url https://agent.example.comAPI token:
✓ Logged in to https://agent.example.com (vps-1, agent v1.1.0)
saved as context default in /home/you/.config/shipwick/config.yamlIt asks for the token without echoing it, verifies the token against the agent, and only then writes the config file. If the agent rejects the token, nothing is saved. Without --url, login asks for the URL too and offers the current one as the default.
Any token works: the root token the installer printed, or one created with shipwick token create. What the CLI may do afterwards follows the token's role; shipwick server status shows which token and role you are using. See Create tokens for CI and teammates.
In a script, pipe the token in:
printf %s "$TOKEN" | shipwick login --url https://agent.example.com --token-stdinFor a hostname whose DNS record or certificate does not exist yet, --no-check (since 0.5) saves the URL and the token as given, without a request to the agent:
printf %s "$TOKEN" | shipwick login --url https://agent.example.com --token-stdin --no-check✓ Saved https://agent.example.com as context default in /home/you/.config/shipwick/config.yaml
not checked against the agent; try it with: shipwick server statusThe config file is <user config dir>/shipwick/config.yaml — ~/.config/shipwick/config.yaml on Linux. login prints the path it wrote. Set SHIPWICK_CONFIG to use another location.
To confirm that the CLI reaches the agent:
shipwick server statusTo check the whole setup, from the versions to whether each domain's DNS points at the server and answers over HTTPS:
shipwick doctorIt prints one line per check with what to do about it, and exits non-zero when something is broken; see Your first deployment. When the agent itself does not answer, the agent's line tells the causes apart: a connection that times out after ten seconds is a firewall in front of the server, on a server that was just installed the provider's; a connection refused is nothing listening, the proxy down; a TLS handshake that fails is a proxy without a certificate for the hostname yet, with Caddy's log as the place to look.
CI jobs usually need no login at all: they set two environment variables instead. See Deploy from CI.
On the server
Since 0.5 there is nothing to set up on the server itself when the API has a hostname. The installer saves https://<agent hostname> and the token as a context of the user who runs it, through shipwick login --token-stdin --no-check, and shipwick ps works there as it does on a laptop. The login is not checked against the agent because, on a new server, the hostname may have neither a DNS record nor a certificate yet; the commands work once it has both.
- With no server saved for that user yet, the context is named
default. - Run again, the installer puts the current token back into the context that points at this server, and leaves every other context, and which one is current, as they were. When another context is current, its summary shows the command with the context's name:
shipwick --context <name> ps. - When the user has other servers saved and none of them is this one, nothing is changed, and the installer prints the command that adds it:
shipwick login --context here --url https://agent.example.com.
Without a hostname for the API nothing is saved: the agent publishes no port, so there is no address on the server to log in to. A command run there then says so instead of suggesting an SSH tunnel, which would lead nowhere on the server itself:
cannot reach the Shipwick agent at http://127.0.0.1:9000
…
The agent on this server publishes no port. Give it a hostname (SHIPWICK_AGENT_DOMAIN in /opt/shipwick/.env, then run the installer again), or see "Reach the API without a hostname" in the handbook, Installation.The ways in without a hostname are in Reach the API without a hostname.
Several servers
Each shipwick login saves a server under a name, a context. Without --context, the name is default; shipwick server install saves the server it installed under its hostname. A second server gets a name of its own and becomes the current one:
shipwick login --context staging --url https://staging.example.comCommands talk to the current context. --context picks another one for a single command, SHIPWICK_CONTEXT for a whole shell, and shipwick context use changes the current one:
shipwick deploy --context staging
shipwick context use prod✓ Switched to prod (https://agent.example.com)| Command | |
|---|---|
shipwick context ls | The saved servers and their URLs; * marks the current one |
shipwick context use <name> | Make a saved server the current one |
shipwick context rm <name> | Forget a server and its token. Asks first; --yes skips the question |
shipwick context current | Print the name of the current server |
NAME URL
* prod https://agent.example.com
staging https://staging.example.comWhile more than one context is saved, output that names the server — server status, warnings — adds the context's name, so that a command run against the wrong server is visible as such. A config file written before contexts existed, with url and token at the top level, still loads as the context default.
How the CLI finds the agent
The URL and the token are resolved separately. The first source that has a value wins.
| URL | Token | |
|---|---|---|
| 1. Flag | --url | Never a flag |
| 2. Environment | SHIPWICK_AGENT_URL | SHIPWICK_AGENT_TOKEN |
| 3. Saved context | yes | yes |
| 4. Default | http://127.0.0.1:9000 | — |
The saved context is the one --context names, else the one SHIPWICK_CONTEXT names, else the current one.
The default URL suits an agent on the same machine and one reached through an SSH tunnel. If you did not give the agent a hostname, see Reach the API without a hostname.
The saved token belongs to the saved URL. If --url or SHIPWICK_AGENT_URL points shipwick at a different agent, the saved token is not sent there; set SHIPWICK_AGENT_TOKEN for that agent, or log in to it under a context of its own.
How the CLI handles the token
An admin token is equivalent to root SSH access to the server, and shipwick treats every token that way:
- The token is never accepted as a command-line flag. Arguments are visible to other users through
psand are kept in shell history. loginreads the token without echo, or from standard input with--token-stdin.- The config file is written with mode
0600, in a directory created with mode0700. On Windows it lives in the profile'sAppDatawith the profile's own permissions (the user, SYSTEM and Administrators). - A saved token is only sent to the agent it was saved for.
- A redirect from the agent's URL is not followed (since 0.10): the agent never answers with one, so it is something in front of the agent, and the token is not sent where it points. The error names the target and says so.
shipwickwarns on standard error whenever the token is about to travel over plain HTTP to anything other than the local machine. Use HTTPS or an SSH tunnel.- A token asked to do more than its role allows is refused by the agent, and
shipwicksays which role it has and which one the command needs.
Behind a proxy, shipwick follows HTTPS_PROXY, HTTP_PROXY and NO_PROXY for the agent and for GitHub, and since 0.6 SHIPWICK_CA_FILE names a PEM file of certificate authorities trusted in addition to the system's, for an agent whose certificate a company's own authority issued. See Run behind a corporate proxy or without internet.
What's next
- Install on a server: one command from here,
shipwick server install. - Deploy your first application.
- Create tokens for CI and teammates.
- The full command list is in the shipwick reference.