Getting Started

This page takes you from nothing to a rendered project directory in about five minutes.

Install

Download a release binary

Binaries are published for Linux and macOS on amd64 and arm64. Grab the archive for your platform from the Releases page, or straight from the package registry:

VERSION=v0.2.0
ARCHIVE=deckctl_Linux_x86_64.tar.gz   # or deckctl_Linux_arm64 / deckctl_Darwin_x86_64 / deckctl_Darwin_arm64

curl -fsSLO "https://gitlab.com/api/v4/projects/80491491/packages/generic/deckctl/${VERSION}/${ARCHIVE}"
tar -xzf "${ARCHIVE}"
sudo mv deckctl /usr/local/bin/
deckctl --version

Each release also ships a deckctl_<tag>_checksums.txt you can verify against:

curl -fsSLO "https://gitlab.com/api/v4/projects/80491491/packages/generic/deckctl/${VERSION}/deckctl_${VERSION}_checksums.txt"
sha256sum --check --ignore-missing "deckctl_${VERSION}_checksums.txt"

Install with go install

go install gitlab.com/oreo-hub/services/deckctl@v0.2.0

Note

go install requires Go 1.26 or newer, and the version must be a v-prefixed tag — that is what Go modules resolve. The tags 0.1.0 through 0.1.3 predate the module rename and are not installable this way.

Build from source

git clone https://gitlab.com/oreo-hub/services/deckctl.git
cd deckctl
go build -o deckctl .

Shell completion

deckctl is a Cobra CLI, so completion scripts come for free:

deckctl completion fish > ~/.config/fish/completions/deckctl.fish
deckctl completion bash > /etc/bash_completion.d/deckctl
deckctl completion zsh  > "${fpath[1]}/_deckctl"

1. Create a template

A template is just a directory with a deckctl.yaml sidecar in it. Files whose names end in .tpl, .tmpl, .jinja or .j2 are rendered through Jinja2 and lose the suffix; everything else is copied byte-for-byte.

mkdir -p ~/templates/go-service

~/templates/go-service/deckctl.yaml

variables:
  - name: app_name
    description: "Name of the application"
    type: str
    default: "myapp"
  - name: port
    description: "HTTP listen port"
    type: int
    default: 8080

~/templates/go-service/main.go.tpl

package main

import (
  "fmt"
  "net/http"
)

func main() {
  fmt.Println("starting {{ app_name }}")
  _ = http.ListenAndServe(":{{ port }}", nil)
}

2. Register the source

deckctl source add --name local --type local --path ~/templates

Run deckctl source add with no flags to be prompted for each field instead. Confirm it landed:

deckctl source list

3. See what is available

deckctl template list --source local

┌────────────┬────────────────────────────┐
│ Name       │ Path                       │
├────────────┼────────────────────────────┤
│ go-service │ /home/you/templates/go-... │
└────────────┴────────────────────────────┘

4. Inspect a template’s variables

Before applying anything, ask the template what it expects:

deckctl template variables go-service --source local

┌──────────┬──────┬─────────┬─────────┬─────────────────────────┐
│ Name     │ Type │ Default │ Choices │ Description             │
├──────────┼──────┼─────────┼─────────┼─────────────────────────┤
│ app_name │ str  │ myapp   │         │ Name of the application │
│ port     │ int  │ 8080    │         │ HTTP listen port        │
└──────────┴──────┴─────────┴─────────┴─────────────────────────┘

5. Preview, then apply

--dry-run prints the full rendered output without touching the filesystem:

deckctl template apply go-service ./billing \
  --source local \
  --var app_name=billing \
  --dry-run

Drop --dry-run to write it:

deckctl template apply go-service ./billing --source local --var app_name=billing

RENDER  main.go

Applied "go-service": 1 rendered, 0 copied → ./billing

Any variable that has neither a --var nor a default is prompted for interactively.

6. Check the history

Every successful apply is recorded:

deckctl history list
deckctl history list -o json

Next steps

• Core concepts — how sources, templates, sidecars and the cache fit together.
• Configuring sources — add a GitLab group as a source.
• Authoring templates — the full sidecar surface.
• CLI Reference — every command and flag.