.shc.yaml deployfiles as a CLI primitive
Archived, shipped. Now described in shc deploy.
.shc.yaml deployfiles as a CLI primitive
Section titled “.shc.yaml deployfiles as a CLI primitive”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.
1. The gap
Section titled “1. The gap”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.
2. The primitive
Section titled “2. The primitive”New verb (or install -f alias, naming ruling owed):
shc deploy -f deploy/ioverse.shc.yaml -e devshc deploy -f deploy/ioverse.shc.yaml -e review --slug feat-login-42shc deploy -f a.shc.yaml -f b.shc.yaml -e prod # multiple stacksshc deploy -f deploy/ioverse.shc.yaml -e dev --dry-run # print resolved argv, touch nothing2.1 File shape
Section titled “2.1 File shape”stack: ioverseapp: deploy/shc/ioverse # package dir relative to the file; git: {url, ref, path} laterpublic: truedomain: ioverse.promanager.vipvars: # --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.
2.2 Resolution rules
Section titled “2.2 Resolution rules”${VAR}interpolation in scalar values only. Sources, later wins: file-adjacent.env(opt-in via--env-file, repeatable) → process environment →--set key=valueoverrides.- 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-runprints the fully resolved install/update argv and the interpolated var table (secrets masked), the plan-lite that makes the file reviewable.
2.3 Behavior
Section titled “2.3 Behavior”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.
2.4 The estate half (shipped 0.0.61)
Section titled “2.4 The estate half (shipped 0.0.61)”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:
| key | renders | notes |
|---|---|---|
catalog: gitea | install gitea | mutually exclusive with app:; the discrimination is LEXICAL |
repo: shc | -r shc | catalogue only; install path only |
version: "1.27" | install [email protected] | catalogue only; without it the install pins latest |
tenant: corp | shc -t corp install … | ROOT position: -t is a persistent flag on shc, not on install |
integrate: {oidc: KEYCLOAK} | -i oidc=KEYCLOAK | a map keyed by CONSUMER PLUG, sorted by plug |
gated: true|false | --gated / --open | tri-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.yamlstack: postgres stack: giteatenant: corp tenant: corpcatalog: postgres catalog: gitearepo: shc repo: shcpublic: false version: "1.27"environments: domain: castclaws.com prod: {} public: true gated: false integrate: postgres: postgres oidc: KEYCLOAK vars: backend: postgres surfaces: - gitea:3000@git.{host} environments: prod: {}$ shc deploy -f deploy/postgres.shc.yaml -f deploy/gitea.shc.yaml -e prod --dry-runshc -t corp install postgres -s postgres -e prod -r shcshc -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=postgres3. The CI template becomes a proxy
Section titled “3. The CI template becomes a proxy”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.
4. Why CLI-side and not daemon-side
Section titled “4. Why CLI-side and not daemon-side”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:
installis create-only. A secondshc installagainst the same (stack, environment) is refused:modules/app/errors.go’sX409003STKEXS, “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 -fwould therefore mean “install, except with-f, in which case sometimes update”: a flag that silently switches a verb’s semantics, which is the exact classregisterInstallFlags’ own-ccomment exists to refuse.- The arity conflicts.
installrequires 1–2 positionals; a deployfile install takes none.-fwould have to make a required argument forbidden, and each of install’s ~35 flags would acquire an unwritten “ignored / merged when-fis 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 asshc deploy --help. A deployfile is toshcwhat a helmfile is to helm, and helmfile did not overloadhelm 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’sdeploy/ioverse.shc.yamlcarriesapp: deploy/shc/ioverse, which read file-relative would resolve todeploy/deploy/shc/ioverseand 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-runmasks 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.
5.3 Rulings §2 did not raise
Section titled “5.3 Rulings §2 did not raise”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 declarestagingwithout waiting for a CLI release. Onlyprod(the apex) andreview(caller-supplied slug) are exceptions. autoStopInmaps to--ttlon 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’sauto_stop_inand 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.
5.5 The proxy is wired (SHC-940)
Section titled “5.5 The proxy is wired (SHC-940)”§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 anapp:file. --hosts-exactdeletes. The old path only adds routes; the verb makes the file the whole route set. promanager dev serves three*.dev.public.promanager.viproutes 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.