Appendix A: CLI reference

Flags, subcommands, environment variables, and config schemas for tela, telad, and telahubd. For narrative explanations, see the User Guide and How-to Guides.

tela

The client CLI. Opens WireGuard tunnels to machines through a hub and binds local TCP listeners for their services. Requires no admin rights or kernel drivers.

tela connect

tela connect -hub <hub> -machine <machine> [flags]
tela connect -profile <name>

When neither -ports nor -services is specified, all ports the agent advertises are forwarded. Each machine gets a deterministic loopback address at localhost:PORT; each service binds at its configured local port, or a fallback port if that is taken.

tela machines

tela machines -hub <hub> [-token <token>]

tela services

tela services -hub <hub> -machine <machine> [-token <token>]

tela status

tela status -hub <hub> [-token <token>]

tela remote

tela remote add <name> <portal-url>   # add a hub directory remote
tela remote remove <name>
tela remote list

tela profile

tela profile list
tela profile show <name>
tela profile create <name>
tela profile delete <name>

tela pair

tela pair -hub <hub-url> -code <code>

Exchanges a pairing code for a hub token and stores it in the credential store.

tela admin

Remote hub management. Requires an owner or admin token.

Token resolution order: -token flag > TELA_OWNER_TOKEN > TELA_TOKEN > credential store.

access -- unified identity and per-machine permissions view

tela admin access [-hub <hub>] [-token <token>]
tela admin access grant <id> <machine> <perms>    # perms: connect,register,manage
tela admin access revoke <id> <machine>
tela admin access rename <id> <new-id>
tela admin access remove <id>

tokens -- token identity CRUD

tela admin tokens list
tela admin tokens add <id> [-role owner|admin]
tela admin tokens remove <id>
tela admin rotate <id>                             # regenerate a token

portals -- portal registrations on the hub

tela admin portals list
tela admin portals add <name> -portal-url <url>
tela admin portals remove <name>

pair-code -- one-time onboarding codes

tela admin pair-code <machine> [-type connect|register] [-expires <duration>] [-machines <list>]

agent -- remote management of telad through the hub

tela admin agent list
tela admin agent config -machine <id>
tela admin agent set -machine <id> <json>
tela admin agent logs -machine <id> [-n 100]
tela admin agent restart -machine <id>
tela admin agent update -machine <id> [-version <v>]
tela admin agent channel -machine <id>
tela admin agent channel -machine <id> set <channel>    # dev, beta, stable, or a custom channel name

hub -- lifecycle management of the hub itself

tela admin hub status
tela admin hub logs [-n 100]
tela admin hub restart
tela admin hub update [-version <v>]
tela admin hub channel
tela admin hub channel set <channel>                    # dev, beta, stable, or a custom channel name

tela channel

tela channel                                          # show current channel and latest version
tela channel set <channel>                            # dev, beta, stable, or a custom channel name
tela channel set <ch> -manifest-base <url>            # override manifest URL prefix
tela channel show [-channel <ch>]                     # print the channel manifest
tela channel download <binary> [-channel <ch>] [-o <path>] [-force]
tela channel -h | -? | -help | --help                 # print help (works after any subcommand too)

tela update

tela update                              # update from the configured channel
tela update -channel <name>              # one-shot channel override (accepts any valid channel name)
tela update -dry-run
tela update -h | -? | -help | --help     # print help

tela files

File operations on machines with file sharing enabled. Requires an active tela connect session.

tela mount

Starts a WebDAV server exposing file shares from connected machines. Requires an active tela connect session.

tela mount                     # start WebDAV server on port 18080
tela mount -port 9999
tela mount -mount T:           # Windows: map drive letter
tela mount -mount ~/tela       # macOS/Linux: mount to directory

When -mount is omitted, the WebDAV server starts but no OS mount is performed. Manual mount commands:

net use T: http://localhost:18080/            # Windows
mount_webdav http://localhost:18080/ /Volumes/tela  # macOS
gio mount dav://localhost:18080/              # Linux (GNOME)

tela service

Manage tela as a native OS service for always-on tunnel scenarios.

tela service install -config <profile.yaml>
tela service start
tela service stop
tela service restart
tela service status
tela service uninstall

Config location when installed as a service:

tela version

tela version

Connection profile schema

Profiles define multiple hub/machine connections that launch in parallel with tela connect -profile <name>.

Profile location:

Schema:

id: ""                                # stable UUID, generated on first load
name: "work-servers"                  # human-readable label (informational)
mtu: 1100                             # WireGuard MTU for all connections in this profile
mount:
  mount: "T:"                         # drive letter (Windows) or directory path
  port: 18080                         # WebDAV listen port
  auto: false                         # auto-mount on connect
dns:
  loopback_prefix: "127.88"           # first two octets of the loopback range
connections:
  - hub: wss://hub.example.com        # hub URL or short name
    hubId: ""                         # stable hub UUID (populated lazily)
    machine: web01
    agentId: ""                       # stable agent UUID (populated lazily)
    token: ${WEB_TOKEN}               # ${VAR} expansion is supported
    address: ""                       # override loopback address (must be in 127.0.0.0/8)
    services:
      - remote: 22                    # forward by port number
        local: 2201                   # optional local port remap
      - name: postgres                # forward by service name (resolved via hub API)

Top-level fields:

Connection entry fields:

* Each service entry needs either remote or name, not both.

Hub name resolution

When -hub is a short name (not ws:// or wss://), tela resolves it in order:

1. Configured remotes (via tela remote add): queries each remote's /api/hubs. First match wins.
2. Local hubs.yaml fallback.
3. Error if unresolved.

Environment variables

Config and credential storage

Token lookup order: -token flag > TELA_TOKEN env var > credential store.

tela login wss://hub.example.com    # store a token
tela logout wss://hub.example.com   # remove stored credentials

telad

The agent daemon. Registers machines with a hub and forwards TCP connections to local services.

Flags

Port spec format

port[:name[:description]]

Examples: 22, 22:SSH, 22:SSH:OpenSSH server, 22:SSH,3389:RDP

Config file (telad.yaml)

hub: wss://hub.example.com
token: <default-token>

update:
  channel: dev     # dev, beta, stable, or a custom channel name

machines:
  - name: web01
    displayName: "Web Server 01"
    hostname: web01.internal   # override OS hostname (useful in containers)
    os: linux                  # defaults to runtime OS
    tags: [production, web]
    location: "US-East"
    owner: ops-team
    target: 127.0.0.1          # set to a remote IP for gateway mode
    token: <override>          # per-machine token override
    services:
      - port: 22
        name: SSH
        description: "OpenSSH server"
    # ports: [22, 3389]        # alternative to services; generates minimal entries

Machine fields

* Either ports or services is required. If both are present, services takes precedence.

File share config

shares:
  - name: shared
    path: /home/shared       # absolute path; created on startup if missing
    writable: false
    maxFileSize: 50MB
    maxTotalSize: 1GB
    allowDelete: false
    allowedExtensions: []    # empty = all allowed
    blockedExtensions: [".exe", ".bat", ".cmd", ".ps1", ".sh"]
  - name: uploads
    path: /home/uploads
    writable: true
    allowDelete: true

Each entry in shares is a named share. Clients navigate to a share by name before browsing files.

The deprecated fileShare: (singular) key is accepted and synthesized as a share named legacy. It will be removed in 1.0.

Upstream config

upstreams:
  - port: 41000
    name: service1
    target: localhost:41000
  - port: 1433
    name: db
    target: int-db.local:1433

Gateway config

gateway:
  port: 8080
  routes:
    - path: /api/
      target: 4000
    - path: /metrics/
      target: 4100
    - path: /
      target: 3000

telad service subcommands

Config location when installed as a service:

telad channel

telad channel [-config <path>]                           # show current channel and latest version
telad channel set <channel> [-config <path>]             # switch agent channel (dev, beta, stable, or custom)
telad channel set <ch> -manifest-base <url>              # override manifest URL prefix
telad channel show [-channel <ch>] [-config <path>]      # print the channel manifest
telad channel -h | -? | -help | --help                   # print help (works after any subcommand too)

Set operations write to telad.yaml under update.channel (and update.sources[<channel>] if a manifest base is given). -config also reads from TELAD_CONFIG in the environment.

telad update

telad update                              # update from the configured channel
telad update -channel <name>              # one-shot channel override (accepts any valid channel name)
telad update -dry-run                     # show what would happen
telad update -h | -? | -help | --help     # print help

Environment variables

Credential store

Store a token so it does not need to appear in config files or shell history:

sudo telad login -hub wss://hub.example.com   # Linux/macOS (requires elevation)
telad login -hub wss://hub.example.com         # Windows (run as Administrator)
telad logout -hub wss://hub.example.com

Token lookup order: -token flag > TELA_TOKEN env var > system credential store > user credential store.

telahubd

The hub server. Listens for WebSocket connections from agents and clients, relays encrypted traffic, and serves the admin API and web console.

Flags

Environment variables

Config file (telahubd.yaml)

port: 80
udpPort: 41820
udpHost: ""        # set when behind a proxy that does not forward UDP
name: myhub
wwwDir: ""         # omit to use embedded console

update:
  channel: dev     # dev, beta, stable, or a custom channel name

auth:
  tokens:
    - id: alice
      token: <hex>
      hubRole: owner   # owner | admin | viewer | "" (user)
  machines:
    "*":
      registerToken: <hex>
      connectTokens: [<hex>]
      manageTokens: [<hex>]
    barn:
      registerToken: <hex>
      connectTokens: [<hex>]
      manageTokens: [<hex>]

Precedence: environment variables override YAML, YAML overrides built-in defaults.

Config file location when running as a service:

telahubd user subcommands

Local token management on the hub machine. All subcommands accept -config <path>.

Changes take effect immediately. No hub restart required.

telahubd portal subcommands

telahubd service subcommands

telahubd channel

telahubd channel [-config <path>]                        # show current channel and latest version
telahubd channel set <channel> [-config <path>]          # switch hub channel (dev, beta, stable, or custom)
telahubd channel set <ch> -manifest-base <url>           # override manifest URL prefix
telahubd channel show [-channel <ch>] [-config <path>]   # print the channel manifest
telahubd channel -h | -? | -help | --help                # print help (works after any subcommand too)

-config defaults to the platform-standard path (/etc/tela/telahubd.yaml on Linux/macOS, %ProgramData%\Tela\telahubd.yaml on Windows), so operators rarely need to pass it. Set operations write update.channel (and update.sources[<channel>] if a manifest base is given) into the hub's YAML config.

telahubd update

telahubd update                              # update from the configured channel
telahubd update -channel <name>              # one-shot channel override (accepts any valid channel name)
telahubd update -dry-run                     # show what would happen
telahubd update -h | -? | -help | --help     # print help

Firewall requirements

No inbound ports are needed on machines running telad.

Admin API

All admin endpoints require an owner or admin token via Authorization: Bearer <token>.

Unified access (identity + per-machine permissions)

Token management

Portal management

Agent management and pairing

Self-update

Public endpoints