Home/Docs/Get started

Deploy from the terminal

The wrenship command builds your site on your machine the way Wrenship would and publishes it. No build minutes. Works in CI and from AI coding agents.

You need Node.js 18 or newer. There's nothing to install: npx fetches the CLI.

npx wrenship login

Your browser opens a Wrenship page with a code. Check it matches the terminal, pick the workspace the CLI may deploy to, and press Approve. The sign-in lasts 90 days and works for that one workspace. You can see and revoke it in Settings → CLI & API tokens.

Deploy

From your project folder:

npx wrenship deploy

The first deploy creates the project, links the folder (in .wrenship/project.json, kept out of Git) and prints the live URL. Later deploys go to the same project.

There are three ways to deploy:

Command	Where it builds	Build minutes
`wrenship deploy`	On your machine, the way Wrenship would (the default)	None
`wrenship deploy --remote`	On Wrenship, from the uploaded source	Yes
`wrenship deploy --prebuilt dist`	Nowhere: the folder you built is published as it is	None
`wrenship deploy --preview`	On Wrenship, at a temporary preview URL (7 days); production doesn't change	Yes

Projects that run server code (SSR, API routes) are always built on Wrenship, so deploy switches to --remote for them by itself.

A local build is the same build

A build on your machine gives the same site as a build on Wrenship:

Same commands. The install and build commands and the output folder come from the project's settings on Wrenship, or from the same detection Wrenship uses for a new project.
Same files. The build runs in a clean copy of your folder, without node_modules, .git or .env files. Wrenship would receive the same files.
Same variables. Environment variables come from the project on Wrenship. Public build variables that happen to be set in your shell (VITE_…, NEXT_PUBLIC_…, PUBLIC_…) are left out.
Checked first. Before building, the CLI checks your Node version against the project's engines field, that the package manager from your lockfile is available, and that you have a lockfile at all.

Wrenship builds with Node 22. Another version gives a warning, and a version the project's engines doesn't allow stops the deploy. The build log in the dashboard records how a deploy was built, for example Built locally (npm ci && npm run build) with Node 22.18.0.

--in-place builds in your folder instead of a clean copy. It's faster, but your own .env files and node_modules are used.

Choose the free address

A new project gets https://<name>.wrenship.site. For .wrenship.space instead:

npx wrenship deploy --domain space

--domain only matters for the first deploy. To change it later, see Custom domains.

Commands

Command	What it does
`wrenship login` / `logout` / `whoami`	Sign in through the browser, sign out, show who you are
`wrenship deploy [folder]`	Build and publish. Options: `--name`, `--project`, `--domain`, `--remote`, `--prebuilt`, `--preview`, `--in-place`, `--no-wait`
`wrenship link <project>`	Make this folder deploy to an existing project
`wrenship projects`	List the workspace's projects
`wrenship deployments`	List the linked project's deployments
`wrenship logs [deployment]`	Follow a build log
`wrenship rollback <deployment>`	Put an earlier deployment live again
`wrenship env ls`	List environment variables (secret values stay hidden)
`wrenship env set KEY=value`	Add or change a variable. `--secret`, `--environment production\|preview\|all`
`wrenship env rm KEY`	Remove a variable
`wrenship open`	Open the linked project's site

CI and AI agents

Set WRENSHIP_TOKEN and add --json. Every command then prints one JSON object, and exits with a non-zero code when the deploy fails:

WRENSHIP_TOKEN=wrs_pat_… npx wrenship deploy --json

{"ok":true,"project_id":"prj_…","deployment_id":"dep_…","status":"ready","url":"https://my-site.wrenship.site","built":"local"}

Get a token with wrenship login on your machine, or under Settings → CLI & API tokens. Store it as a secret in your CI.

AI coding agents with a terminal, such as Claude Code, Codex, Cursor, Antigravity or Kiro, can run the same commands. Tell them: "Deploy this folder with npx wrenship deploy --json and give me the URL." To let them deploy without a terminal, connect them as an AI app instead.

GitHub Actions

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: wrenship/deploy-action@v1
        with:
          token: ${{ secrets.WRENSHIP_TOKEN }}
          project: my-site

The action builds in the GitHub runner the way Wrenship would and publishes the result, so it uses no build minutes. Its inputs:

Input	Meaning
`token`	Required. Your Wrenship token, stored as a secret
`project`	Project id or name. Without it, a new project is created
`prebuilt`	A folder you already built (`dist`, `build`…) to publish as it is
`remote`	`true` to build on Wrenship instead of in the runner
`domain`	`space` for a new project on `.wrenship.space`
`directory`	The project folder, if it isn't the repository root

It sets the outputs url and deployment-id, and fails the job when the deploy fails.

If you'd rather not keep a token in CI, connect the repository instead: every push deploys without any workflow file.

Troubleshooting

"This project needs Node …". Your Node version doesn't match the project's engines. Switch versions (for example with nvm use 22), or build on Wrenship with --remote.
"uses pnpm through corepack, which isn't installed". Newer Node versions no longer include corepack. Run npm install -g corepack.
The site looks different from a Wrenship build. Deploy once with --remote and compare. Most differences come from a different Node version or a missing lockfile.
Building without a secret. A Developer can't read secret values, so a local build runs without them and the CLI says which. Ask an Admin, or use --remote.