Skip to content
SHC Docs

CLI symbols

Seven symbols carry the grammar inside a flag’s value, and each means one thing wherever it appears, except /, which has two meanings told apart by where it sits. A flag prefers a richer value over a second flag, so learn these once and every value reads the same way.

symbolread it asmeaningexample
=isthe thing on the left is set to the rightweb=3
:itsa part inside the thing on its leftweb:8080 is web’s port 8080, db:location=nbg1 is db’s own rule, pgdata=ceph:50Gi is 50Gi of ceph
@atwhich one or where: a version, an environment, a connection, a placenextcloud@30, 2@hel
/undera path below, after a name: in a hostname, after @, in a repo/app nameapp.example.com/api, 2@eu/hel, bitspur/frappe
/perafter a bare count in --scale: that many in each fence of the kind2/location, 1/node
+withan option switched on53+udp
!notat the end it removesblog.example.com!
,andanother item2@eu,1@us

A flag that sets something per service has one shape:

<service>[:<port>]=<value>[+<option>][@<where>]

The service comes first for per-service settings. Exposure starts with the outside address and puts the service after =.

A symbol inside a literal value belongs to the value. The dots in a hostname are the hostname’s. What follows @ in a version is a version and nothing else, so nextcloud@30+2 pins packaged revision 2 of version 30 and the + there is not an option. A URL keeps its own @, : and /.

<repo>/<app>[@<version>]

An app reads like an image reference: the repo it comes from, a slash, the app, and @ the version. -r/--repo is the long form of the repo half.

Terminal window
shc install bitspur/[email protected]
shc update bitspur/[email protected] -t corp -e prod
shc repoint photos apps/immich

The slash keeps its other meaning first. When the app before it publishes the name after it as an add-on or a vApp, shc install nextcloud/deck is that add-on, and when a deployment of that name exists, shc update nc/[email protected] is that vApp instance. Otherwise the first half is a repo the install must be able to see. A repo in the token and a different -r/--repo are refused with X400076REPTWO; the same repo stated twice is accepted.

@<name> names a place. A location path is a place, and so is every prefix of it: hel, eu/hel, hetzner/eu/hel. A name that is no location is refused, and the refusal lists the locations.

How a deployment is reached once the flag is accepted, the ledger, the listen rules and the refusals are Published ports.

--expose <outside>[+<option>...][@<where>][=<service>[:<container port>]]

Repeatable; comma lists are accepted. <outside> is a port number, or a hostname with an optional path (hostname[:port][/path]). A hostname with an outside port is an L4 listener that also gets a DNS record. A path on that form (db.example.com:5432/x) is refused with X400495EXPPTH: a port has no path.

A value that is only digits is a port, so 8080 is L4 port 8080 and must be from 1 to 65535. A hostname must contain a letter or a dot: wiki and 8080.example.com are hostnames, and a hostname that is only digits cannot be added or removed through --expose.

Options and placement belong to the outside part, before =, as in 36094+udp@(node=home01)=echo:9999. The first = outside parentheses separates the target. An = inside @(...) belongs to the node selector.

No outside port means HTTP(S) through Traefik. The target on the right says which service or service selector answers, and may name its container port. Leave it out to use the app default: the service marked x-shc-primary, else the first service in file order, with its default port. An explicit target must resolve to one ingress candidate. A service selector over labels other than group has no ports of its own, so its target names one, app.example.com=web:8080. A target that is neither a service nor a service selector of the app is refused with X400498EXPTGT, which lists both.

Terminal window
shc install wiki --expose wiki.example.com
shc install wiki --expose wiki.example.com=web
shc install wiki --expose wiki.example.com/docs=web:8080
shc update wiki --expose metrics.example.com=:9000
shc update wiki --expose wiki.example.com/a+b
shc update wiki --expose wiki.example.com/@alice

An outside port is an L4 listener. The same flag publishes it; +udp is UDP, and @<connection> sends it through that connection’s load balancer. A fully omitted target uses the app default service and port. A named service without a container port uses the outside port as its container port; 8080=:80 selects the one service that declares container port 80. A service selector takes the same place as a service: 5432=postgres, with postgres: role=primary:1, reaches whichever replica is primary now and follows a failover with no update. Some service of the app must declare its container port, and the cluster must run service VIPs (X400499EXPVIP). A port the node itself owns is refused with X400992PRTOWN: sshd’s 22 and any port its config adds, shcd’s 4001-4003 and 8000, the WireGuard ports 4243 and 4244 over UDP, 53 where shcd answers DNS, and the edge’s 80 and 443.

Terminal window
shc install postgres --expose 5432
shc install postgres --expose 5432=db
shc install gitea --expose 8022=gitea:22
shc install syslog --expose 514+udp=syslog:514
shc install postgres --expose 5432@hz-lb=db
shc install postgres --expose 5432+spread
shc install mailcow --expose '25+local=postfix-mailcow:25'
shc install wazuh --expose 514+udp+private=wazuh-manager:514
shc install postgres --expose '5432@(edge=true)'
shc install postgres --expose 5432@eu/hel

+spread sends a connection to any ready replica. A publish without +spread prefers a replica on the node that accepted the connection. +local answers only on nodes that hold a ready replica and never forwards, so the app sees the client’s address; it cannot be combined with +spread. +private takes the port on each node’s private address only, never a public one. @(edge=true) listens on the nodes whose labels match that node selector. @eu/hel is a location path and listens on the nodes in that location. A name with no slash, @hel1, is a location when a node is in that location and no connection has the name. It is that connection’s load balancer when the name is a connection. A name that is both is refused with X409137PUBAMB. An L4 publish that names no @ follows the publish.listen node selector, and every node when that key is unset.

Two deployments cannot listen on one port and protocol on one node. Install, update, and a label edit that would cause that are refused with X409136PUBOVR, which names the deployment that already listens and the nodes. On a cluster whose fabric mode is shc and whose fabric range does not overlap the service VIP range, a published port is an SHC listen rule on each listening node, a connection publish included. The rendered compose has no ports: entry for it, so the port does not answer on 127.0.0.1 from the node itself. A connection publish whose owner is a proxy connection, or whose owner is not recorded, matches the node’s private address. An app’s own ports: entries publish nothing there: the render declares their container ports, and the install warns with X200141PUBTPL naming the --expose that would publish each one.

A hostname with an outside port (db.example.com:5432=db) is that listener plus a DNS record from the tenant’s DNS connection, the same managed-DNS plane an HTTP host uses. No hostname means no record. @<connection> points the record at that connection’s load-balancer endpoints. A plain publish points it at the nodes that listen: exposure=internet uses each listening node’s public address, drops a private or loopback address, and defers with X200980DNSDEF when none is left. Any other exposure uses dns.lan_address, then dns.public_address, then each listening node’s underlay address. An L4 host never follows the system Traefik. An L4 hostname another deployment already serves, as a route host or an L4 host, is refused with X409142PUBHST. A removal names the outside port, protocol and connection; db.example.com:5432! and 5432! remove the same mapping.

On shc update a trailing ! removes one entry by its outside part. A removal never names a node selector. Protocol is part of a port entry’s identity: 514! and 514+tcp! remove only TCP, and 514+udp! removes only UDP.

Terminal window
shc update wiki --expose old.example.com!
shc update wiki --expose 'old.example.com!,wiki.example.com/docs!'
shc update postgres --expose 5432!
shc update syslog --expose 514+tcp!
shc update syslog --expose 514+udp!

A bare ! removes every expose entry the same command does not name. The entries beside it are then the whole set, in the order given, and the first HTTP route is the canonical origin. Alone, it leaves the deployment with no exposure.

Terminal window
shc update wiki --expose '!' --expose wiki.example.com --expose docs.example.com=web:8080
shc update wiki --expose '!'
--scale <name>=<n>
--scale <name>=<n>@<place>[,<n>@<place>...]
--scale <service>=<n>/<kind>

A count, exact counts per place, or a count per value of a kind. 2/location is two replicas in every location, on different nodes where the location has them, and a location added later gets its two without a new value. 1/node is one on every node. The / here is per, so it comes straight after the count; a path keeps its / after @. The name is a service, or a group a {% members %} block stamps. A group takes a count or counts per place.

Terminal window
shc install wiki --scale web=3
shc update wiki --scale db=2@home,1@far
shc update wiki --scale db=2@hetzner/eu/hel,1@us
shc update wiki --scale proxy=1/node
shc install postgres --scale postgres=2/location
--where <node selector>
--where <service>:<node selector>
--where <service>!
--where '!'

Repeatable, and --prefer takes the same forms. A bare node selector is the deployment-wide rule. <service>:<node selector> is that service’s own rule, and the service is a service or a group, as in --scale. A trailing ! drops that service’s own rule, so it falls back to the deployment-wide one. A bare ! drops every rule of the flag.

Terminal window
shc update wiki --where location=hel1 --where db:location=nbg1
shc update wiki --prefer web:tier=edge
shc update wiki --where 'db!'
--zone <zone>[!]
--zone '!'

Repeatable; comma lists are accepted. A name adds the zone. A trailing ! removes it. A bare ! alone leaves the connection with no zones. The zones named beside a bare ! are the whole set.

Terminal window
shc connection zones cloudflare -t corp --zone example.org
[<service>][:<port>][=<local port>]

<service>:<port> is the service’s port. =<local port> sets the local port. An all-digit value is a remote port. Leave the local port out and one is chosen.

Terminal window
shc forward postgres web:5432=15432

No old spelling is read. Each is refused with a code that prints the value as it is written now.

typedrefused withwrite
--host wiki.example.comX400226FLGOLD--expose wiki.example.com
--hosts-exactX400226FLGOLD--expose '!' beside every route and port to keep
--route web:8080=wiki.example.comX400226FLGOLD--expose wiki.example.com=web:8080
--port 53/udp!X400226FLGOLD--expose 53+udp!
--scale db=home:2,far:1X400225SCLOLD--scale db=2@home,1@far
--scale proxy=per:locationX400225SCLOLD--scale proxy=1/location
--scale pg=2+per@locationX400225SCLOLD--scale pg=2/location
--add example.orgX400551ZNEOLD--zone example.org
--remove xX400551ZNEOLD--zone x!
--set a,bX400551ZNEOLD--zone '!' --zone a,b
15432:5432X400911FWDOLD5432=15432
15432:webX400911FWDOLDweb=15432
15432:web:5432X400911FWDOLDweb:5432=15432
--rename blog:blog2X400449RCVOLD--rename blog=blog2
--from-backup blog.bak:blog2X400449RCVOLD--from-backup blog.bak=blog2
--override host=old.example:new.exampleX400449RCVOLD--override host:old.example=new.example
--rename a:bX400649CLNOLD--rename a=b
cluster fabric explain acme/prod/webapp 10.84.1.130X400384FBROLDwebapp -t acme -e prod
adapter migrate lw --adapter runtipi --version 1 --from acme/linkwarden@prodX400968ADPOLD--stack linkwarden -t acme -e prod

A deployment that stored a scale in a retired spelling is refused the same way when the value is read. One shc update --scale in the new spelling replaces it. Stored routes are not text and need nothing.

flaggrammar
shc install <app>[/<add-on>][@<version>]/ under, @ at
shc install, shc update, shc repoint: <repo>/<app>[@<version>]/ under: the app under that repo, as -r <repo>; @ at
-i, --integrate[<plug>=]<provider>[@<environment>], <plug>=@<connection>; <plug>! on update
-C, --connection<name>=<connection>
--var, -c, --config-set<key>=<value>; <key>! on update
--cpu-quota, --memory-quota<service>=<value>
shc recover --rename<old>=<new>
shc recover --from-backup<backup>[=<target>]
shc recover --override[<stack>:]host:<old>=<new> or [<stack>:]hosts=<new>
shc clone --rename<old>=<new>[,<old>=<new>...]
shc cluster fabric explain <from> <to>a fabric address, or <stack>[:<service>]; -t/-e name the tenant and environment, --target-tenant/--target-environment place <to>
shc adapter migrate --stackan SHC stack, in the tenant and environment from -t/-e; --from stays <path> or ssh://[user@]host