@shipstatic/ship

CLI and SDK for ShipStatic — deploy static websites, landing pages, and prototypes instantly from the terminal or code.

Deploy in seconds — no install, no account

npx @shipstatic/ship ./dist

That's it. Your site is live on *.shipstatic.com. No sign-up, no config, no global install. Got Node? You're ready.

The output includes a claim URL — visit it to keep the site permanently. Anonymous deployments are public and expire in 3 days.

import Ship from '@shipstatic/ship';

const ship = new Ship();
const result = await ship.deploy('./dist');
// result.deployment → live URL (happy-cat-abc1234.shipstatic.com)
// result.claim      → visit to keep permanently

Install (optional, for repeat use)

npm install -g @shipstatic/ship   # global CLI — drop the `npx @shipstatic/ship` prefix

As a project dependency: npm install @shipstatic/ship

Every example in this README uses the bare ship command. If you haven't installed it globally, prefix any of them with npx @shipstatic/ship (or npx -y @shipstatic/ship in non-interactive environments).

All Commands — Free API Key

For permanent deployments and full control over your sites and domains, get a free API key from my.shipstatic.com/api-key.

ship config    # paste your API key when prompted

const ship = new Ship({ token: 'ship-your-api-key' });

Deployments

ship ./dist                                        # Deploy (shortcut)
ship ./dist --domain www.example.com               # Deploy and serve it there
ship ./dist --ttl 1h                               # Expires in an hour
ship ./dist --label production --label v1.0.0      # Deploy with labels
ship deployments list
ship deployments list --limit 20                   # Page size; a hint shows the next cursor
ship deployments list --cursor <cursor>            # Continue from a previous page
ship deployments get <deployment>
ship deployments set <deployment> --label production
ship deployments delete <deployment>

ship.deploy(input, options?)               // Shortcut for deployments.upload()
ship.deployments.upload(input, options?)
ship.deployments.list(options?)            // { limit?, cursor? } — response carries the next cursor
ship.deployments.get(deployment)
ship.deployments.set(deployment, { labels })
ship.deployments.delete(deployment)

Domains

ship domains set www.example.com                   # Reserve domain (no deployment yet)
ship domains set www.example.com <deployment>      # Link domain to deployment
ship domains set www.example.com --label prod      # Update labels only
ship domains get www.example.com
ship domains list                                  # --limit / --cursor paginate here too
ship domains validate www.example.com
ship domains verify www.example.com
ship domains records www.example.com
ship domains dns www.example.com
ship domains share www.example.com
ship domains delete www.example.com

ship.domains.set(name, { deployment?, labels? })   // Upsert — create, repoint, or label
ship.domains.get(name)
ship.domains.list(options?)                 // { limit?, cursor? }
ship.domains.validate(name)
ship.domains.verify(name)
ship.domains.records(name)
ship.domains.dns(name)
ship.domains.share(name)
ship.domains.delete(name)

domains.set() is a merge-upsert — omitted fields are preserved on update, defaulted on create. Once linked, a domain cannot be unlinked ({ deployment: null } → 400). Switch deployments or delete the domain instead.

Domain names are normalized by the API — any case, Unicode accepted:

ship.domains.set('WWW.Example.COM');   // → www.example.com
ship.domains.set('www.münchen.de');    // → Unicode supported

Tokens

ship tokens create --ttl 30d --label ci            # Or 3600, 90s, 1h — one grammar
ship tokens list
ship tokens get <token>
ship tokens delete <token>

ship.tokens.create({ ttl?, labels? })
ship.tokens.list()
ship.tokens.get(token)
ship.tokens.delete(token)

Account

ship whoami
ship account get
ship config
ship ping

ship.account.get()            // → whoami
ship.ping()                   // → { timestamp } (server clock; reachability is the absence of a throw)
ship.getLimits()              // → platform plan limits (cached)

CLI Reference

Composability

The -q flag outputs only the resource identifier — perfect for piping and scripting:

ship tokens create -q is the one exception: it prints the token secret, which is shown once and never again.

# Deploy and link domain in one pipe
ship ./dist -q | ship domains set www.example.com

# Deploy and open in browser
open https://$(ship ./dist -q)

# Batch delete all deployments
ship deployments list -q | xargs -I{} ship deployments delete {} -q

Ephemeral deployments

ship ./dist --ttl 1h          # gone in an hour
ship ./dist --ttl 7d          # a week-long preview
ship ./dist --ttl 3600        # bare seconds work too

The platform reclaims the deployment when the time is up. Seconds, or a
<n><unit> duration (s/m/h/d) — the same grammar ship tokens create --ttl uses. Bounded at one year.

Two rules, both refused before anything uploads. It needs a token: an
anonymous deployment already expires on the platform's own schedule, so there
is no deployer to choose a different one. And it cannot be combined with
--domain: a domain is a commitment and a deadline is its opposite, so the
API refuses to point a domain at a deployment that expires.

To keep something longer, deploy it again — there is no way to extend a
deployment's life, and no way to shorten it after the fact.

--domain is the same two calls as one command:

ship ./dist --domain www.example.com

Both spellings are supported and neither replaces the other. The pipe composes interactively — any two commands, wherever -q gives you the value the next one wants. --domain is one process, one exit code, and one --json, which is what CI needs: a run: block is bash -e without pipefail, so a pipeline reports only the last command's status and a failed deploy is masked. It answers as the domain, exactly as ship domains set does — DNS records and setup link included on a new external domain — and it needs a token, which it checks before uploading anything.

Shell Completion

ship completion install
ship completion uninstall

Global Flags

Available on every command:

Deploy Flags

Available on ship <path> and ship deployments upload:

CLI Environment Variables

SDK Reference

Authentication

// No token — deploy only: lands in the public account with a claim URL, 3-day expiry
const ship = new Ship();

// API key — durable, full account
const ship = new Ship({ token: 'ship-your-api-key' });

// Deploy token — scoped to deploys, optional TTL, revocable
const ship = new Ship({ token: 'deploy-your-token' });

// OAuth access token — delegated, short-lived, sent verbatim
const ship = new Ship({ token: accessToken });

// Token provider — invoked per request; refresh lives with you
const ship = new Ship({ token: () => mintToken() });

// Cookie session — first-party browser apps
const ship = new Ship({ session: true });

// Set or rotate the token after construction
ship.setToken('ship-your-api-key');

Retries

Failed requests are retried automatically: transport failures (including a
timeout) and 500/502/503/504, twice by default, with full-jitter exponential
backoff. maxRetries is the knob; 0 disables it.

const ship = new Ship({ token: 'ship-your-api-key', maxRetries: 5 });

Deliberately never retried: a maintenance 503 (its message says when to come
back), 429 (the rate limiter has answered), PUT/DELETE (a repeat can
misreport a lost success as a failure), anything stopped by a signal you
supplied, and any other non-GET without an Idempotency-Key — with the key,
a deploy replays its stored result instead of creating a second one.

timeout is the ceiling on one ATTEMPT. For a hard overall deadline pass your
own signal (AbortSignal.timeout(ms)), which is never retried past.

Deploy Options

ship.deploy(input, {
  labels?: string[],
  password?: string,          // Password-protect the deployment (6–128 chars)
  ttl?: number,               // Seconds until it expires (needs a token; max 1 year)
  signal?: AbortSignal,       // Abort to cancel the deploy
  pathDetect?: boolean,       // Auto-optimize paths (default: true)
  spaDetect?: boolean,        // Auto-detect SPA (default: true)
  via?: string,               // Client identifier
});

Expiring deployments

Pass ttl in seconds and the platform reclaims the deployment when the time is up — 1 second to one year. The wire carries the duration and the API stamps expires against its own clock, so the answer says when:

const result = await ship.deploy('./dist', { ttl: 3600 });
// result.expires → unix seconds, one hour after result.created

Needs a credential — an anonymous deployment already expires on the platform's own schedule. And a deployment carrying a ttl cannot be linked to a domain: the API refuses, which is what stops a domain pointing at something that is about to be reclaimed. There is no way to extend or shorten a deployment after the fact; redeploy instead.

Password protection

Pass password (6–128 characters) to gate the deployment behind a prompt. Visitors are asked for the password before they can view the site, including on any custom domains pointing at it. To remove protection, redeploy without a password.

ship --password 'your-passphrase' ./dist

await ship.deploy('./dist', { password: 'your-passphrase' });

The CLI also reads SHIP_PASSWORD from the environment when --password is not given.

Browser Usage

import Ship from '@shipstatic/ship';

const ship = new Ship({ token: 'ship-your-api-key' });

// From file input
const deployment = await ship.deploy(fileInput.files);

// From StaticFile array
const deployment = await ship.deploy([
  { path: 'index.html', content: new Blob(['<html>…</html>']) }
]);

Events

ship.on('request', (url, init) => {});          // once per attempt
ship.on('retry', (error, url, attempt) => {});  // an attempt failed, another is coming
ship.on('response', (response, url) => {});     // the call succeeded
ship.on('error', (error, url) => {});           // the call failed, terminally
ship.off('request', handler);

One call emits retry* (error | response) — every failure is announced, and
the event name says whether it ended the call. attempt counts from 1, so it
names both the attempt that failed and which retry is happening.

Custom fetch

Pass fetch to override the transport function used for every API call. Defaults to globalThis.fetch. Useful for wrapping requests with tracing, retries, or request signing, and for injecting a Cloudflare service-binding Fetcher from a Worker so calls reach a sibling Worker in-process instead of through the public hostname.

This is also the seam for corporate proxies: Node's built-in fetch ignores HTTP(S)_PROXY environment variables, so behind a proxy inject a proxy-aware transport (e.g. undici's EnvHttpProxyAgent as the dispatcher, or Node 24+'s NODE_USE_ENV_PROXY=1).

import type { Fetch } from '@shipstatic/ship';

const traced: Fetch = (input, init) =>
  globalThis.fetch(input, { ...init, headers: { ...init?.headers, 'X-Trace-Id': 'abc-123' } });

const ship = new Ship({ fetch: traced });

// Cloudflare Worker with a service binding to the API.
// Any parseable apiUrl works — service bindings dispatch by binding identity, not hostname.
const ship = new Ship({
  apiUrl: 'https://api',
  fetch: env.API.fetch.bind(env.API),
});

Error Handling

import { isShipError, ErrorType } from '@shipstatic/types';

try {
  await ship.deploy('./dist');
} catch (error) {
  if (isShipError(error)) {
    error.isAuthError();        // semantic category
    error.isNetworkError();     // semantic category — nothing was exchanged
    error.isClientError();      // semantic category (Business | Config | File | Validation)
    error.type === ErrorType.Validation;  // specific-type check
    error.type === ErrorType.Timeout;     // a deadline expired — inside isNetworkError()
    error.status === 429;       // status check
  }
}

Configuration

The CLI (ship) resolves its token in this order:

1. CLI flag: --token
2. Environment variable: SHIP_TOKEN
3. Config file: ~/.shiprc (run ship config to create one)

--config <file> reads any path you name instead of ~/.shiprc, which is how per-environment
configs work (ship --config dev.shiprc ...). The file is strict JSON; an empty one means "no
config".

No repository file is ever read. A .shiprc or package.json "ship" key in your working
directory is ignored — cloning a repo can never change which account you deploy to, or which
host your token is sent to.

The SDK (new Ship(...)) resolves its token in this order:

1. Constructor option: new Ship({ token })
2. Environment variable: SHIP_TOKEN

--api-url / SHIP_API_URL / apiUrl resolve the same way for the API endpoint.

The SDK never reads .shiprc or package.json — file resolution is a CLI feature, not an SDK feature. This keeps new Ship({}) safe to use from embedded contexts (MCP, n8n, library wrappers) without inheriting the host developer's personal credentials.

SHIP_TOKEN=ship-your-api-key ship deployments list

TypeScript

import type { ShipClientOptions, DeploymentOptions, ShipEvents } from '@shipstatic/ship';
import type { Deployment, Domain, Account, StaticFile } from '@shipstatic/types';

AI Agents

This package includes a SKILL.md file — a portable skill definition that AI agents (Claude Code, Codex, etc.) use to deploy sites with ship autonomously.

Part of the ShipStatic platform.