Skip to content
SHC Docs

.shc.yaml deployfiles as a CLI primitive

Archived, shipped. Now described in shc deploy.

Status: BUILT: shc deploy is on ce main as c999913 (2026-08-13); the cicd template proxies to it since SHC-940 (2026-09-25, §5.5). The ask is the owner’s, stated 2026-08-13: “can shc.yaml be a primitive supported by shc. so you can shc install and reference an shc.yaml file? which will resolve envs or even envs in a .env? and then the gitlab template is just a light proxy on top of that?” This page specified it; §5 records what was built, the rulings §2 left open, and the two places reality contradicted this page.

Baselines (MEASURED, 2026-08-13 night). Cluster hel1.hetzner.promanager.vip on shc 0.0.52 → 0.0.53-dev; CLI install flag surface read from the live node (--var/--host/--public/ --ttl/--gated/quotas; no values-file flag of any kind); the first real consumer of the pattern is promanager/ioverse (six public surfaces, review/dev/test/prod fan-out), deployed all night through bitspur/selfhosted-cloud/cicd → templates/shc-deploy.yml. A CI-side deployfile implementation (templates/shc-deployfile.yml + shc-deployfile/generate.sh, yq + envsubst in the job) is landing in the cicd repo in parallel with this page.

Baseline re-measured 2026-08-13 morning, before building. Still true, on both the source and the wire: rg 'shc\.yaml|deployfile' over all of ce returns nothing, ce declares no deploy cobra command, and corp compose01 (then 1:0.0.56~SNAPSHOT-6fa6401acb) answered shc deploy --help with unknown command "deploy" for "shc" and shc install --help with no values-file flag. The CI half had moved on (templates/shc-deployfile.yml + shc-deployfile/generate.sh landed as cicd 624c5fe / ad005ec) so the split at that moment was: CI path real and in production, CLI primitive not started.


An SHC app package already carries its values (vars.yaml) and its schema (app.yaml). What has no home is the deployment wiring: which stack, which environments exist, which hosts each environment binds, which flags the install needs. Today that wiring lives in GitLab CI variables and in whatever --var/--host strings a human or a pipeline assembles. The consequence is that every CI system (and every human doing an ad-hoc install) re-implements the same rendering: env fan-out conventions, ${VAR} substitution, flag assembly.

That rendering is not CI logic. It is deployment logic, and it belongs in the CLI.

New verb (or install -f alias, naming ruling owed):

shc deploy -f deploy/ioverse.shc.yaml -e dev
shc deploy -f deploy/ioverse.shc.yaml -e review --slug feat-login-42
shc deploy -f a.shc.yaml -f b.shc.yaml -e prod # multiple stacks
shc deploy -f deploy/ioverse.shc.yaml -e dev --dry-run # print resolved argv, touch nothing
deploy/ioverse.shc.yaml
stack: ioverse
app: deploy/shc/ioverse # package dir relative to the file; git: {url, ref, path} later
public: true
domain: ioverse.promanager.vip
vars: # --var key=value, after interpolation
images.one: ${CI_REGISTRY_IMAGE}/one:${CI_COMMIT_SHORT_SHA}
surfaces: # --host bindings; {host} is the per-environment base
- one:3000@{host}
- frappe-nginx:8080@api.{host}
environments:
review: { autoStopIn: 3 days } # maps to --ttl (daemon-enforced lease teardown)
dev: {}
test: {}
prod: {}

Host fan-out is the convention the cicd templates already shipped: review → {host} = <slug>.review.<domain> (slug is caller input, git context is not the daemon’s business), dev/test → prefixed, prod → the apex.

  • ${VAR} interpolation in scalar values only. Sources, later wins: file-adjacent .env (opt-in via --env-file, repeatable) → process environment → --set key=value overrides.
  • An undefined ${VAR} is a refusal, not an empty string; the vault-empty-credentials incident of 2026-08-13 (X500111VLTUNR, dev install rendered with empty passwords during a daemon restart) is the cautionary tale for silent empties.
  • --dry-run prints the fully resolved install/update argv and the interpolated var table (secrets masked), the plan-lite that makes the file reviewable.

deploy is exactly the install-or-update dance the cicd template does in shell today: shc ls probe → install <dir> -s <stack> -e <env> with --host/--var/--public on first contact, update (with the same host re-assertion) after. One stack per file; multiple -f = the stacks in file order. Exit non-zero if any stack fails; --keep-going for fleets of independent stacks.

Explicit non-goals: no prune (“file deleted ⇒ uninstall”), no drift detection, no cross-stack dependency graph. Those are state semantics; the ops-repo terraform root (or a future shc fleet apply with prune, a separate proposal) owns them. A deployfile is the app-repo primitive: the pipeline that runs it is the reconciler.

The schema above says everything an APP REPO needs and nothing an ESTATE needs. An estate deployment installs a package it does not build, lives in a named tenant, and is wired to the stacks around it, and none of those three could be said, so an ops repo that wanted .shc.yaml had to keep a terraform root beside it and render the same deployment twice. Six keys close that:

keyrendersnotes
catalog: giteainstall giteamutually exclusive with app:; the discrimination is LEXICAL
repo: shc-r shccatalogue only; install path only
version: "1.27"install [email protected]catalogue only; without it the install pins latest
tenant: corpshc -t corp install …ROOT position: -t is a persistent flag on shc, not on install
integrate: {oidc: KEYCLOAK}-i oidc=KEYCLOAKa map keyed by CONSUMER PLUG, sorted by plug
gated: true|false--gated / --opentri-state; ABSENT emits neither and the package’s access: default stands

domain: also became required only when the file declares surfaces:; a headless stack (an estate’s postgres) publishes no HTTP host, and the base it would fan out from is not a thing it has.

The non-goals are unchanged, and two of these keys sit next to the line. integrate: only ever ASSERTS: dropping a line does not disconnect the edge, because that would mean diffing the declared set against the deployed one, which is drift reconciliation. Removal stays shc update <stack> -i <plug>!, typed deliberately. And there is no depends_on: and no wait_healthy:; install/update already block until every container is healthy (compose up -d --wait, then the CLI follows the operation to its terminal frame), and deploy runs its plans sequentially, so file order is the ordering primitive. Every key above renders to a flag shc install has taken for releases; the daemon surface (§4) is untouched.

Version skew. A file using these keys is a hard parse refusal on shc ≤ 0.0.60, and no key can fix that retroactively; an old strict decoder refuses the version-declaring key itself. What 0.0.61 adds is X400419DPFVER: from here on an unknown key is answered with the schema this binary knows and the release the estate keys landed in, instead of go-yaml’s field tenant not found in type commands.deployfileRaw. Ship the CLI to the estate before committing files that use them.

An estate, in full: the two files are deployed with one command, and no package exists on disk anywhere:

# deploy/postgres.shc.yaml # deploy/gitea.shc.yaml
stack: postgres stack: gitea
tenant: corp tenant: corp
catalog: postgres catalog: gitea
repo: shc repo: shc
public: false version: "1.27"
environments: domain: castclaws.com
prod: {} public: true
gated: false
integrate:
postgres: postgres
oidc: KEYCLOAK
vars:
adminEmail: [email protected]
backend: postgres
surfaces:
- gitea:3000@git.{host}
environments:
prod: {}
$ shc deploy -f deploy/postgres.shc.yaml -f deploy/gitea.shc.yaml -e prod --dry-run
shc -t corp install postgres -s postgres -e prod -r shc
shc -t corp install [email protected] -s gitea -e prod -r shc --public --open \
-i oidc=KEYCLOAK -i postgres=postgres --host gitea:[email protected] \
--var [email protected] --var backend=postgres

Once estates carry a release with the verb, the cicd deployfile template’s generator stops parsing YAML and emitting flag strings; a deploy job becomes:

shc_ssh "sudo -n shc deploy -f '$FILE' -e '$ENV' --slug '$CI_COMMIT_REF_SLUG'"

with GitLab keeping what only GitLab has: environment: blocks (deployments/environments UI, on_stop, auto_stop_in), rules, and the review-app lifecycle hooks. Feature-detect (shc deploy --help) lets the template proxy on new estates and fall back to CI-side rendering on old ones, same pattern as the --cleanup-dns fallback that landed in .shc-stop tonight.

Auth rides the existing roadmap unchanged: ssh + sudo -n shc today, shc ctx login --token with a scoped PAT when docs/internal/pat-mcp-design.md ships. The verb is transport-neutral by construction; it renders argv for the same daemon API the CLI already speaks.

The daemon already has a values story (package vars + vault refs). The deployfile is caller-side config: it exists to turn a file plus an environment name into an argv, and its interpolation inputs (CI variables, .env) live on the caller’s side of the ssh boundary. Keeping it in the CLI means zero daemon surface, zero migration, and --dry-run works offline.

5. What was built, and the rulings this page left open

Section titled “5. What was built, and the rulings this page left open”

ce c999913: modules/app/commands/{deploy,deployfile,deployfile_errors}.go plus modules/app/errors_deployfile.go, with 30 tests across three files. Zero daemon surface, exactly as §4 argued.

5.1 The naming ruling: deploy, and install gets nothing

Section titled “5.1 The naming ruling: deploy, and install gets nothing”

§2 owed a ruling between shc deploy -f and shc install -f. It is deploy, a distinct verb, and install grows no values-file flag of any spelling. The owner’s phrasing (“so you can shc install and reference an shc.yaml file”) asked for the CAPABILITY with the verb that was to hand; the capability ships, the overload does not, because:

  • install is create-only. A second shc install against the same (stack, environment) is refused: modules/app/errors.go’s X409003STKEXS, “stack {name} already exists in environment {environment}”. A deployfile’s whole contract is install-or-update convergence, where running twice is the normal case. install -f would therefore mean “install, except with -f, in which case sometimes update”: a flag that silently switches a verb’s semantics, which is the exact class registerInstallFlags’ own -c comment exists to refuse.
  • The arity conflicts. install requires 1–2 positionals; a deployfile install takes none. -f would have to make a required argument forbidden, and each of install’s ~35 flags would acquire an unwritten “ignored / merged when -f is present” rule.
  • The estate already says “deploy” for this operation: .shc-deploy, shc:deploy, deploy_review:<stack>, SHC_DEPLOY_VARS, and §3 of this page writes the feature-detect as shc deploy --help. A deployfile is to shc what a helmfile is to helm, and helmfile did not overload helm install.

deploy_command_test.go pins the ruling and carries TestInstallVerbStaysCreateOnly, which fails if install ever becomes convergent, at which point the premise is gone and the ruling deserves revisiting.

5.2 Two places this page was wrong, corrected in the build

Section titled “5.2 Two places this page was wrong, corrected in the build”
  • app: resolves against the WORKING DIRECTORY, not the deployfile. §2.1’s comment says “package dir relative to the file”, but this page’s own reference implementation contradicts it: ioverse’s deploy/ioverse.shc.yaml carries app: deploy/shc/ioverse, which read file-relative would resolve to deploy/deploy/shc/ioverse and match nothing. The generator does [ -d "$app" ] from the repo root. The CLI follows reality; the refusal (X400412DPFAPP) names the working directory it resolved against, because that is the mistake nine times in ten.
  • --dry-run masks credential-shaped var values. §2.2 asks for “the fully resolved argv” and “the var table (secrets masked)”, which cannot both hold of a var that is a secret; the argv carries it. A dry run is a document people paste into merge requests and CI logs, so masking wins in both places. The mask keys off the var NAME and is a courtesy, not a control; real secrets belong in vault refs, which never travel through argv at all.
  • stack: is not interpolated. It is the deployment’s identity; it keys (tenant, stack, environment) and names jobs and GitLab environments through the generator. A stack name that varies with an environment variable cannot say what it deploys, and the failure mode is a duplicate stack rather than an error. Every other scalar (app, domain, surfaces, vars, autoStopIn) interpolates.
  • Interpolation is per-scalar, not whole-file. The generator runs envsubst over the whole document before yq parses it, so a value carrying a colon or a newline can restructure the YAML. Parsing first and substituting into scalars cannot. This buys the two properties the generator explicitly cannot have (its own header records the first): a literal $ survives; the grammar is braced-only and $$ escapes, and unset is distinguishable from empty, which is what §2.2’s refusal rule actually requires. envsubst renders both as nothing, so the refusal is not implementable on top of it at all.
  • An environment name outside {review, dev, test, prod} is not an error. It fans out like dev and test do (<name>.<domain>), so a repo can declare staging without waiting for a CLI release. Only prod (the apex) and review (caller-supplied slug) are exceptions.
  • autoStopIn maps to --ttl on BOTH install and update. A bare update never touches an existing lease, so stamping only on first contact would expire an active review app three days after its first push however often it was redeployed. Both GitLab’s spelling (3 days) and Go’s (72h) are accepted, since the field now feeds both GitLab’s auto_stop_in and a daemon-enforced lease.

5.4 One improvement over the shell it replaces

Section titled “5.4 One improvement over the shell it replaces”

The install-or-update fork is decided by an exact (stack, environment) match against /api/resource/Stack. The CI base probes with shc ls | awk '$0 ~ s && $0 ~ e', a substring test that reads stack io as present when only ioverse is, and environment dev as present when only review-dev-thing is. Picking the wrong side of that fork is a failed deploy in both directions.

§3’s proxy is wired as of cicd !4 (SHC-940, 2026-09-25). A generated deploy job still rsyncs the package to ~/shc-apps/<stack>-<env>/, then ships the deployfile to ~/shc-apps/<stack>-<env>.tree/ at its checkout path with app: linked to that package, and runs shc deploy -f <file> -e <env> [--slug <slug>] from the tree. Every ${VAR} the file references is resolved at generate time, in the parent pipeline, and handed over as --set. The generator still decides which jobs and GitLab environments exist; it no longer decides what deploys.

The feature-detect is stronger than --help: the job asks the node for shc deploy --dry-run first and proxies only when that plan carries the SHC environment, the host list and the lease the generator already told GitLab. Otherwise it runs the CI-side install/update and prints why (SHC_DEPLOY_PATH=fallback: <reason>). Two update rules exist because the verb and the old path genuinely differ on a live stack, measured on the promanager estate (shc 0.0.75):

  • A bare update re-renders the RECORDED source. Up to 0.0.75 the update argv carries no --from, so an import-created stack (public/promanager dev, /var/lib/shc/_i1import/promanager) would take new --vars over its import snapshot. The proxy skips an update unless the recorded source is the shipped package or the plan carries --from. ce !80 (SHC-941) renders --from <app dir> on every update of an app: file.
  • --hosts-exact deletes. The old path only adds routes; the verb makes the file the whole route set. promanager dev serves three *.dev.public.promanager.vip routes its deployfile never declared, so the proxy skips any update that would drop or re-order a live route.

Still missing from the verb, all in ce !80 (SHC-941) and live once an estate carries it: --node for a first path install on a multi-node estate (X409078PTHNOD; the fallback install takes SHC_NODE), and the generator’s default review lease (3 days) plus autoStopIn: never. Until then a review environment with no autoStopIn deploys CI-side. The CLI also refuses integrations: (the generator’s alias), so a file that wants the proxy says integrate:.

First live run: promanager main pipeline 2881305839 (2026-09-25). landing and console dev deployed through shc deploy, both with nested vars:; promanager dev and console-db dev fell back on the recorded-source rule.