Metadata-Version: 2.5
Name: terrace-cli
Version: 0.1.0
Summary: Command-line client for Terrace: deploy a project folder, get a URL
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.28
Requires-Dist: pathspec>=1.1
Requires-Dist: ruamel-yaml>=0.18
Description-Content-Type: text/markdown

# terrace

The command-line client for [Terrace](https://terrace.dev): point it at a
project folder and it builds and deploys it, with sign-in and sharing handled
by Terrace.

```bash
brew install soin08/terrace/terrace
```

or, with any Python 3.12+:

```bash
pipx install terrace-cli
```

Then:

```bash
terrace login
terrace deploy
```

`terrace --help` lists every command.

## Static sites

`terrace deploy` recognizes a static site by its `package.json`: a `build`
script plus Vite, Astro, Create React App or the Angular CLI. It then builds the
site on your machine (`npm install` only when `node_modules` is missing, then
`npm run build`; `pnpm` or `yarn` when their lockfile is present) and uploads
the output folder. Files the server already holds are not sent again, so a
redeploy that changed one file sends one file. A local build takes only the
app's variables named `VITE_*`, `NEXT_PUBLIC_*`, `PUBLIC_*`, `REACT_APP_*`,
`NUXT_PUBLIC_*`, `GATSBY_*` or `ASTRO_*`; a build that needs any other
variable has to run on the server with `--remote`.

A folder of plain HTML is a static site too: an `.html` page at its root, and
no `package.json` or other sign of an app (`requirements.txt`, `go.mod`, a
`Dockerfile`, …). Nothing is built; its files are uploaded as they are, less
`terrace.yml`, `AGENTS.md`, `.gitignore`, `.terraceignore` and whatever those
ignore files leave out. `/docs/` serves `docs/index.html`, and an address with
no file gets a 404: the site's own `404.html` when it has one. A folder with a
single page and no `index.html` serves that page at `/` as well.

Add `--remote` to build on the server instead:

```bash
terrace deploy --remote
```

For any other build, or an output folder the CLI does not know, name it in
`terrace.yml`:

```yaml
static: dist
```

or, with a fallback for paths that match no file (`index` serves `index.html`
for a single-page app, `404` serves the site's `404.html`, or a plain not-found
page when there is none, with status 404):

```yaml
static:
  dir: public
  fallback: "404"
```

## Pulling the source back

Every deploy keeps a snapshot of the source it was built from.
`terrace pull payroll` writes the latest one into `./payroll`; name another
folder as a second argument, or an older snapshot with `--snapshot ID`. A folder
that already has files in it is left alone unless you pass `--force`, which
overwrites files that clash and deletes nothing. Deploy the result again with
`terrace deploy ./payroll`.
