### Run demo content generator

Source: https://github.com/windshiftapp/core/blob/main/scripts/demo/README.md

Run the demo content generator directly without Docker. It builds the frontend, builds the backend binary, creates a new demo.db database, starts the server on port 8080, completes initial setup, generates all demo content, and keeps the server running.

```bash
cd scripts/demo
node generate-demo.js
```

--------------------------------

### Install windshift-runner with install.sh

Source: https://github.com/windshiftapp/core/blob/main/deploy/windshift-runner/README.md

Installs the runner using the install.sh script, either with prebuilt binaries via --bin-dir or by building from a core checkout with --core. The script checks docker/git, installs binaries to /usr/local/bin, creates the windshift-runner system user, and is idempotent.

```bash
# prebuilt binaries sitting next to install.sh (or pass --bin-dir DIR)
sudo ./install.sh --bin-dir /path/to/dist

# …or build from a core checkout present on the host (needs Go):
sudo ./install.sh --core /path/to/core
```

--------------------------------

### Example commands for running windshift with different log settings

Source: https://github.com/windshiftapp/core/blob/main/LOGGING.md

Example bash commands showing how to run the windshift binary with debug logging, JSON output, and environment variables.

```bash
# Run with debug logging
./windshift --log-level=debug

# Run with JSON output (useful for log aggregation)
./windshift --log-format=json

# Using environment variables
LOG_LEVEL=debug LOG_FORMAT=json ./windshift
```

--------------------------------

### Start local preview servers with docker compose

Source: https://github.com/windshiftapp/core/blob/main/plugin-src/trmnl/README.md

Starts the local preview servers for the tasks and summary plugins. Requires Ruby >= 3.4, which macOS does not ship, so use the container. Both services read WINDSHIFT_URL and WINDSHIFT_TOKEN from .env; the .trmnlp.yml files interpolate them into the plugin's custom fields.

```sh
cp .env.example .env      # then fill in URL + token
docker compose up tasks   # http://localhost:4567
docker compose up summary # http://localhost:4568
```

--------------------------------

### Install windshift-runner via hosted script

Source: https://github.com/windshiftapp/core/blob/main/deploy/windshift-runner/README.md

Use the one-liner provided by the orchestrator to install the runner. This script handles SELinux configuration, data directories, environment files, and registration.

```bash
curl -fsSL https://windshift.example.com/api/runner-install.sh | sudo bash -s -- --token wsrt_...
```

--------------------------------

### Run setup-demo.sh for local or production deployment

Source: https://github.com/windshiftapp/core/blob/main/scripts/demo/README.md

Run the setup script from the scripts/demo directory. Use 'localhost' for local testing with a self-signed certificate, or a hostname like 'demo.example.com' for production deployment with Let's Encrypt.

```bash
cd scripts/demo

# Local testing (self-signed certificate)
./setup-demo.sh localhost

# Production deployment with Let's Encrypt
./setup-demo.sh demo.example.com
```

--------------------------------

### Local development commands

Source: https://github.com/windshiftapp/core/blob/main/frontend/README.md

Commands for local development: install dependencies with npm ci, start the Vite dev server, run the production build, and run Biome lint and format checks.

```sh
npm ci         # use ci, not install — respects the lockfile
npm run dev    # vite dev server
npm run build  # production build (what release.sh runs)
npm run check  # biome lint + format check
```

--------------------------------

### Configure and start windshift-runner service

Source: https://github.com/windshiftapp/core/blob/main/deploy/windshift-runner/README.md

Configures and starts the windshift-runner service. Requires editing runner.env to set WS_API_URL, token, and image, then pulling the agent image and starting the systemd unit.

```bash
sudo "$EDITOR" /etc/windshift-runner/runner.env   # set WS_API_URL, token, image
docker pull <WSRUNNER_IMAGE>
sudo systemctl start windshift-runner
journalctl -u windshift-runner -f                 # watch it register + claim
```

--------------------------------

### Logfmt output format example

Source: https://github.com/windshiftapp/core/blob/main/LOGGING.md

Example of key-value logfmt output compatible with many log analysis tools.

```text
level=INFO msg="service started" version=1.0.0
level=DEBUG msg="creating session" component=sso user_id=123
```

--------------------------------

### Structured logging with slog

Source: https://github.com/windshiftapp/core/blob/main/LOGGING.md

Examples of structured log calls using slog.Debug, slog.Info, slog.Warn, and slog.Error with structured attributes.

```go
slog.Debug("item create request received")
slog.Info("service started", slog.String("version", version))
slog.Warn("cache initialization failed", slog.Any("error", err))
slog.Error("permission check failed",
    slog.Int("user_id", userID),
    slog.Int("workspace_id", workspaceID),
    slog.Any("error", err))
```

--------------------------------

### Using t.Logf in test files

Source: https://github.com/windshiftapp/core/blob/main/LOGGING.md

Example of using t.Logf instead of slog in test files.

```go
func TestSomething(t *testing.T) {
    t.Logf("Debug info: %v", data)
}
```

--------------------------------

### Text output format example

Source: https://github.com/windshiftapp/core/blob/main/LOGGING.md

Example of human-readable colored output in text format.

```text
INFO  service started                       version=1.0.0
DEBUG creating session                      component=sso user_id=123
WARN  cache initialization failed           error="connection refused"
```

--------------------------------

### Linux usage (./windshift, ./cmd/ws/ws workspace list)

Source: https://github.com/windshiftapp/core/blob/main/BUILD.md

Run the built server and ws client on Linux. The server is started in the background and the ws client lists workspaces.

```bash
# After building
./windshift &
./cmd/ws/ws workspace list
```

--------------------------------

### Windows usage (windshift.exe, cmd\ws\ws.exe workspace list)

Source: https://github.com/windshiftapp/core/blob/main/BUILD.md

Run the built server and ws client on Windows. The server is started and the ws client lists workspaces.

```bash
# After building
windshift.exe
cmd\ws\ws.exe workspace list
```

--------------------------------

### Manually run docker compose with HOSTNAME

Source: https://github.com/windshiftapp/core/blob/main/scripts/demo/README.md

Manually start the demo with Docker Compose from the project root. Set HOSTNAME to your domain (e.g., 'localhost' for local testing) and specify the compose file path.

```bash
# From project root (core/)
HOSTNAME=localhost docker compose -f scripts/demo/docker-compose.yml up --build
```

--------------------------------

### Verify windshift-runner service with systemctl and journalctl

Source: https://github.com/windshiftapp/core/blob/main/deploy/windshift-runner/README.md

Check the runner service status and follow its logs. After startup, the logs should show 'registered as instance N in pool M' followed by 'worker started'.

```bash
systemctl status windshift-runner
```

```bash
journalctl -u windshift-runner -f
```

--------------------------------

### Build with Makefile (make all, make clean, make build, make frontend, make help)

Source: https://github.com/windshiftapp/core/blob/main/BUILD.md

Use the Makefile for the recommended build workflow. The commands cover full builds, clean rebuilds, server-only and frontend-only builds, and listing available targets.

```bash
# Build everything (frontend + server)
make all

# Clean and rebuild
make clean && make all

# Build server only
make build

# Build frontend only
make frontend

# Show all available make targets
make help
```

--------------------------------

### Manual build (npm ci, go build, ws client)

Source: https://github.com/windshiftapp/core/blob/main/BUILD.md

Manual build steps for frontend, server, and ws client. Requires Go 1.27.0 and Node.js 24.18.0 with npm 11.16.0 as pinned in the project files.

```bash
# Build frontend
cd frontend
npm ci
npm run build
cd ..

# Build server (current platform)
go build -o windshift main.go

# Build ws client (current platform)
cd cmd/ws
go build -o ws
cd ../..
```

--------------------------------

### JSON output format example

Source: https://github.com/windshiftapp/core/blob/main/LOGGING.md

Example of machine-readable JSON output for log aggregation systems.

```json
{"level":"INFO","msg":"service started","version":"1.0.0"}
{"level":"DEBUG","msg":"creating session","component":"sso","user_id":123}
```

--------------------------------

### Release with release.sh (release, build, push, --dry-run, --skip-frontend, --help)

Source: https://github.com/windshiftapp/core/blob/main/BUILD.md

Use release.sh for full release builds, local builds, Docker pushes, dry runs, skipping frontend builds, and help. Requires Docker + Buildx for cross-compilation.

```bash
# Full release with binaries + Docker + GitHub release
./release.sh release -v v1.0.0 -n releases/v1.0.0.md

# Build binaries and packages locally (no publish)
./release.sh build -v v1.0.0

# Build and push Docker images only
./release.sh push -v v1.0.0-dev

# Dry run to preview actions
./release.sh release -v v1.0.0 -n releases/v1.0.0.md --dry-run

# Skip frontend build (use existing dist/)
./release.sh build --skip-frontend

# Show help
./release.sh --help
```

--------------------------------

### Manually build frontend and backend binary

Source: https://github.com/windshiftapp/core/blob/main/scripts/demo/README.md

Manually build the frontend and backend binary when the generator is run with --no-build. The frontend must be built before the Go binary so the binary embeds the current frontend/dist/index.html.

```bash
cd frontend && npm run build
cd .. && go build -tags '!test' -ldflags '-s -w' -o windshift .
```

--------------------------------

### Create a backup with backup.sh

Source: https://github.com/windshiftapp/core/blob/main/deploy/backup-restore.md

Run from the Compose directory. The backup path must be an absolute, normalized host path without a colon because it is passed to Docker's -v syntax. The created directory is mode 700 and contains data.tar.gz, manifest.env, and checksums.sha256; PostgreSQL backups also contain database.dump.

```bash
cd deploy

./backup.sh backup /srv/windshift-backups/windshift-$(date -u +%Y%m%dT%H%M%SZ)
```

--------------------------------

### Performance logging with grouped timing attributes

Source: https://github.com/windshiftapp/core/blob/main/LOGGING.md

Example of using slog.Group to group timing attributes for performance-critical sections.

```go
slog.Debug("item creation performance",
    slog.Int("item_id", itemID),
    slog.Group("timings_ms",
        slog.Float64("validation", 1.23),
        slog.Float64("transaction", 4.56),
        slog.Float64("total", 7.89),
    ))
```

--------------------------------

### Run windshift-runner as a container

Source: https://github.com/windshiftapp/core/blob/main/deploy/windshift-runner/README.md

Starts the runner as a container using the provided runner-compose.yml, driving the host Docker daemon through the mounted socket (Docker-out-of-Docker).

```bash
docker compose -f runner-compose.yml up -d
```

--------------------------------

### Demo generator usage options

Source: https://github.com/windshiftapp/core/blob/main/scripts/demo/README.md

Usage options for the demo generator. Use --port to change the port, --db to specify a custom database file, --no-server to use an existing server, --stop-server to stop after generation, --binary to set the binary output path, --no-build to skip rebuilding, and --help for help.

```bash
# Custom port
node generate-demo.js --port 3000

# Custom database
node generate-demo.js --db my-demo.db

# Use existing server (for CI/testing)
node generate-demo.js --no-server --base-url http://localhost:8080

# Stop server after generation
node generate-demo.js --stop-server

# Custom binary output path (the script builds this binary before running it)
node generate-demo.js --binary /path/to/windshift

# Use an already-built binary without rebuilding
node generate-demo.js --no-build --binary /path/to/windshift

# Help
node generate-demo.js --help
```

--------------------------------

### Override min-release-age cooldown

Source: https://github.com/windshiftapp/core/blob/main/frontend/README.md

Overrides the min-release-age guard for a single install to pull a fresh release urgently, such as a same-day security patch. The override is per-invocation and should not be added to .npmrc.

```sh
npm install <pkg> --min-release-age=0
```

--------------------------------

### Build ws-carrier image locally

Source: https://github.com/windshiftapp/core/blob/main/deploy/coding-agent/README.md

Commands to build the ws-carrier image using either make or docker.

```bash
make coding-agent-image
# or
docker build -f deploy/coding-agent/Dockerfile -t windshift/ws-carrier:local .
```

--------------------------------

### Build windshift-runner and windshift-triage binaries

Source: https://github.com/windshiftapp/core/blob/main/deploy/windshift-runner/README.md

Builds the windshift-runner and windshift-triage static Go binaries on a build machine or in CI. Requires a Go toolchain and a core checkout.

```bash
cd core
CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o dist/windshift-runner  ./windshift-runner
CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o dist/windshift-triage ./cmd/windshift-triage
```

--------------------------------

### Cross-compile with Makefile (build-linux, build-windows, build-windows-arm64)

Source: https://github.com/windshiftapp/core/blob/main/BUILD.md

Cross-compile the server for Linux, Windows, and Windows on ARM64 using the Makefile targets. These produce the binaries listed in the development build output.

```bash
# Cross-compile for Linux
make build-linux

# Cross-compile for Windows
make build-windows

# Cross-compile for Windows on ARM64
make build-windows-arm64
```

--------------------------------

### Run focused validation commands from core

Source: https://github.com/windshiftapp/core/blob/main/docs/collection-query-contract.md

Run the focused validation commands from the core directory. The first two commands execute Go tests with the overlay script, the second adding a PostgreSQL DSN. The third runs Go service tests, the fourth runs frontend tests via the overlay script, the fifth runs E2E tests with artifacts kept, and the sixth runs the Go linter with a five-minute timeout.

```sh
../core-tests/overlay.sh . -- -tags=test -count=1 -run 'TestEmptyCollection|TestCollectionMetadata|TestItemsBatch' ./tests
```

```sh
TEST_DB_TYPE=postgres TEST_POSTGRES_DSN='postgresql://localhost:5432/postgres?sslmode=disable' ../core-tests/overlay.sh . -- -tags=test -count=1 -run 'TestEmptyCollection|TestCollectionMetadata|TestItemsBatch' ./tests
```

```sh
../core-tests/overlay.sh . -- -tags=test -count=1 -run 'TestItemCRUDService|TestCollection.*Board|TestConfiguration' ./internal/services
```

```sh
../core-tests/run-overlay-script.sh . scripts/run-frontend-tests.sh src/lib/features/collections src/lib/stores/collectionContext.test.js src/lib/stores/collectionCompletion.test.js src/lib/stores/searchStore.test.js
```

```sh
E2E_KEEP_ARTIFACTS=1 ../core-tests/run-e2e.sh tests/collection-empty-query.spec.ts tests/collection-completed-visibility.spec.ts tests/collection-search-columns.spec.ts --retries=0
```

```sh
./scripts/run-golangci-lint.sh run --timeout=5m
```

--------------------------------

### Docker Compose commands for logs, stop, restart, rebuild, and reset

Source: https://github.com/windshiftapp/core/blob/main/scripts/demo/README.md

Common Docker Compose commands for managing the demo. Use 'logs -f' to follow logs, 'down' to stop, 'restart' to restart, 'up --build -d' to rebuild after code changes, and 'down -v' for a complete reset that removes all data including certificates.

```bash
# View logs
docker compose logs -f

# Stop the demo
docker compose down

# Restart
docker compose restart

# Rebuild (after code changes)
docker compose up --build -d

# Complete reset (removes all data including certificates)
docker compose down -v
```