Skip to content

cliq

cliq is Sartiq's unified devops CLI — one self-contained Go binary that covers the day-to-day operations a backend/full-stack dev reaches for: spinning up the local stack, managing the shared seed dataset, standing up per-branch preview environments, running the e2e suite, and opening a shell on an environment VM.

It ships from releases.sartiq.com/cliq/ and self-updates.

Flag-level reference: every flag and edge case lives next to the code in the cliq repo README. This page is the feature catalog — what each command does, when to reach for it, and how it fits the workflow. When in doubt, cliq <command> --help is always authoritative for your installed version.

Feature map

Command group What it does Reach for it when…
cliq local Bring up / tear down / inspect the full local stack (backend + compute + webapp) You want everything running on your laptop
cliq seed Pull, push, and verify the shared seed dataset (DB rows + image assets) You need realistic data, or want to publish a new canonical state
cliq preview Create & manage full-stack preview environments on a public URL You need to share a build, demo with real OAuth, or repro a prod-shaped bug
cliq ssh Open a cert-authed shell on a dev/staging/prod VM You need to poke at a long-lived environment directly
cliq e2e Run the Playwright e2e suite (full stack, or fast MSW mode) You're validating end-to-end behavior before a PR
cliq init / cliq login One-time config + credential setup First run, or after rotating a token
cliq upgrade / cliq changelog Self-update and read what changed A new release is out
cliq completion Install shell-completion scripts You want tab completion

Install

curl -fsSL https://releases.sartiq.com/cliq/install.sh | bash

The installer detects your OS/arch and drops the binary into ~/.local/bin/cliq — make sure that's on your PATH. To pin a version:

CLIQ_VERSION=v0.14.0 curl -fsSL https://releases.sartiq.com/cliq/install.sh | bash

(CLIQ_INSTALL_DIR and CLIQ_BASE_URL override the install dir and release host respectively.)

First-run setup

cliq init     # interactive wizard — captures local repo paths + Cloudflare account
cliq login    # creates + verifies a Cloudflare token, then optionally a GitHub PAT

cliq init captures, into ~/.config/sartiq/cliq/config.yaml:

  • Your local checkouts of shootify-backend, shootify-webapp, and shootify-compute-server — so cliq local, cliq e2e, and cliq preview know where each repo lives.
  • The Sartiq Cloudflare account ID.
  • The R2 bucket + prefix for the seed dataset (defaults sartiq-misc / seed-data).

cliq login is a detect-then-prompt flow — it reuses a known-good credential and only prompts when one is missing, expired, or you decline. It walks you through:

  1. A Cloudflare User API Token (profile-scoped, so it auto-invalidates when you leave the org). Needs Workers R2 Storage / Edit; cliq preview additionally needs Zone / DNS / Edit, and User Details / Read is optional for attribution.
  2. A GitHub classic PAT (optional — press Enter to skip if you don't use previews). Needs repo + write:packages / read:packages / delete:packages.

Run cliq login --verify to silently re-check existing credentials without prompts.

Where things live

Config: ~/.config/sartiq/cliq/config.yaml. Credentials: ~/.config/sartiq/cliq/credentials.yaml (mode 0600). A pre-0.3 ~/.config/cliq directory is migrated automatically on first run.

local — the local stack

Bring up, tear down, inspect, and clean the full local dev stack across backend, compute-server, and (in dev) webapp — without juggling three docker compose invocations by hand.

cliq local up                 # backend + compute (parallel, wait-for-healthy) + 'bun run dev' webapp
cliq local status             # what's running across every cliq-managed project (alias: ps)
cliq local logs backend -f    # tail one service in whichever project owns it (webapp = dev-server log)
cliq local down               # stop everything cliq brought up
cliq local clean --force      # nuke volumes + webapp build artifacts for a clean slate (destructive)

Profiles select what up/down operate on:

Profile What it brings up
dev (default) backend + compute (each via its own docker-compose.dev.yml) + bun run dev in the webapp
e2e compute on an internet-blocked internal network, backend rewired to in-stack compute, auto-seeded from the canonical dataset. No webapp (Playwright owns it during cliq e2e run).

Useful up flags: --no-webapp / --no-backend / --no-compute to opt out of a piece, --build to rebuild images first, and --task OPS-43 to run each repo from its worktrees/<TASK-ID>/* checkout (falls back to the main checkout per-repo; implies --build). down --volumes also removes named volumes.

seed — the shared test dataset

Local dev needs realistic data. The seed dataset — a curated Postgres dump plus an image-asset tree — lives in Cloudflare R2 at sartiq-misc/seed-data/ and mirrors into your local db (Postgres) and minio containers. pull and push are the two halves of the loop.

cliq seed pull        # restore the canonical seed into your local stack
cliq seed push        # publish your current local state as the new canonical
cliq seed verify      # check your local schema revision is shipped on origin/dev
cliq seed doctor      # diagnose the local stack (db + minio reachable, bucket OK)
  • pull is destructive on the DB side (drops + recreates the public schema, then restores the dump in a single transaction) and incremental on the asset side (ETag short-circuit — unchanged objects aren't re-downloaded). It refuses to run over an existing populated DB unless you pass --force. --skip-dump / --skip-assets do one side only.
  • push is destructive on the shared dataset — it overwrites the one canonical seed every dev pulls, with no backup. It makes you type the R2 prefix to confirm (--yes to skip, required in CI). As an unconditional pre-flight it runs the verify check: your local alembic head must already be on origin/dev, otherwise publishing would break everyone else's pull. There is no bypass — merge the migration to dev first.

See Storage → Local-Dev Seed Dataset for the dataset layout.

preview — per-branch environments

A preview is a short-lived, branch-scoped deployment of the full stack on a public <code>.preview.sartiq.com URL, running on the shared GCP preview-host VM. Reach for one when cliq local up isn't enough — to share a build with product, demo with real OAuth, exercise Cloudflare image transforms, or repro a bug that only shows up against real Postgres + R2.

Deep dive: the architecture, identifiers, lease-vs-auto-shutdown timers, image flow, and seeding are all documented in Preview Environments. This is the command summary.

Lifecycle

cliq preview create sar-23           # resolve branches, build images on CI, stand the stack up
cliq preview list                    # all active previews
cliq preview status sar-23           # one preview's detail
cliq preview logs sar-23 backend -f  # tail a service (backend|scheduler|celery_worker|
                                     #   compute_server|compute_worker|webapp)
cliq preview rebuild sar-23          # new code: re-resolve branches, fresh images, keep data
cliq preview recreate sar-23         # no rebuild: redeploy stack + pick up env changes
cliq preview seed sar-23             # re-seed DB + bucket from the canonical dataset
cliq preview destroy sar-23          # tear down + drop DB, bucket, image tags
  • create resolves a branch per repo by matching <code>* on origin, falling back to dev (override with --branch / --branch-<repo>). By default the host builds the images on GitHub Actions (faster push, dedups against dev's buildcache); pass --local-build to build + push from your laptop instead (useful when iterating on a Dockerfile not yet on dev). Seeds from the canonical dataset unless you pass --no-seed. --lease <hours> sets the initial lease; --yes accepts dev-branch fallbacks unprompted.
  • rebuild vs recreate: rebuild builds fresh images (use after pushing code); recreate just redeploys the existing images and re-snapshots env (use right after preview env set). Both keep the DB, bucket, and Redis index. Both take --services backend,webapp,… to act on a subset only.

Keeping a preview alive

Two independent timers — see Lease vs auto-shutdown:

cliq preview extend sar-23 2h     # push out the GC lease (when the preview is reaped)
cliq preview hold   sar-23 1h     # block the host's idle auto-shutdown (the VM stopping)

You generally want both before a demo.

Per-preview env values

The host owns the locked tier (DB/R2/secrets); cliq preview env manages the feature-tier env values layered on top. Writes affect future previews and existing ones on rebuild --refresh-env / recreate — they never silently mutate a running preview (each pins an immutable snapshot at create time).

cliq preview env list                          # current shared store (redacted)
cliq preview env set FOO bar --service backend # upsert into one or more services
cliq preview env sync --service backend        # diff your <repo>/.env into the store, apply missing keys
cliq preview env show  sar-23                  # the snapshot this preview is pinned to
cliq preview env diff  sar-23                  # what a --refresh-env rebuild would change

Keys must be UPPER_SNAKE_CASE; host-owned names (POSTGRES_*, R2_*, COMPUTE_SERVER_*, hostnames) are rejected server-side, so adding a feature env var never needs a cliq release.

Host wake & diagnostics

The preview-host idle auto-stops. Every preview subcommand probes /healthz first and dispatches the wake workflow on its own if the host is asleep — so you rarely run wake by hand.

cliq preview doctor    # check host reachability + Cloudflare/GitHub auth
cliq preview wake      # warm the host ahead of time (no-op if already awake)

Pass --no-wake to any preview (or ssh) command to fail fast instead of waiting through a ~5-min cold boot — handy in CI.

Tunnels

cliq preview tunnel opens an ad-hoc reverse tunnel exposing a localhost port at <slug>--tunnel.preview.sartiq.com through the same host (up stays foreground; list / rm manage slugs). See docs/spike-tunnel.md in the repo for the design.

ssh — shell into an environment VM

Open an interactive shell on a long-lived environment VM (backend | compute × dev | staging | production). Auth is a short-lived per-VM certificate minted by the preview-host CA — no per-dev SSH key is installed on the target, and a leaked cert is scoped to exactly one (server, env) pair.

cliq ssh backend --env production
cliq ssh compute --env dev

Like preview, it auto-wakes the preview-host (which issues the cert); --no-wake opts out.

e2e — the end-to-end suite

Run the webapp's Playwright suite against a real stack, with teardown handled for you. Ctrl+C is honored — the bun/Playwright child gets SIGINT, the stack is torn down, and no containers are orphaned.

cliq e2e run            # full stack: local up --profile e2e → test:e2e:real → local down
cliq e2e run --msw      # fast inner loop: mock the backend in-browser, no Docker
cliq e2e run --keep     # leave the stack up after tests (iterate)
cliq e2e run --no-up    # assume the e2e stack is already up
cliq e2e run --grep "checkout"   # pass-through to playwright --grep

--msw runs test:e2e with the backend mocked by a service worker — the fastest loop, no stack required. The default --no-msw flow runs test:e2e:real against backend + compute (compute mocked, outbound internet hard-blocked).

Staying current

cliq upgrade            # download + atomically replace the running binary
cliq upgrade --check    # report current vs. latest without installing
cliq upgrade --force    # reinstall current version (repair)
cliq changelog          # print the latest release section baked into this binary
cliq changelog --since 0.10.0   # everything newer than a given version

cliq upgrade reads the version pointer from releases.sartiq.com/cliq/latest/VERSION (it does not hit the GitHub Releases API — the repo is private). cliq also runs a background update probe on every invocation and prints a one-line notice when a newer version exists. If self-update ever breaks, re-running the install one-liner is always a safe fallback.

Shell completion

cliq completion install   # install per-user scripts and (for zsh) offer to wire it up
cliq completion zsh       # or print a script to stdout (also: bash, fish, powershell)

Config & credentials reference

File Holds Notes
~/.config/sartiq/cliq/config.yaml repo paths, account_id, bucket/prefix, preview_host_url, show_banner written by cliq init
~/.config/sartiq/cliq/credentials.yaml Cloudflare token, GitHub PAT mode 0600, written by cliq login

Set show_banner: false in config.yaml to silence the ASCII banner.