CLI reference

The connector ships as a single binary named clicklink; the commands you run live under clicklink clctl. This page covers the commands used during installation and day-to-day operation. Run any command with --help for its full help text. Flags in the troubleshoot and preflight subtrees can also be supplied through CLCTL_* environment variables (named in each flag’s help output) or ~/.clicklink/clctl.yaml.

clicklink clctl init

Bootstraps the connector from an enrollment token, a saved enrollment bundle, or an out-of-band signed certificate. One invocation stages configuration, provisions ClickHouse access, obtains the mTLS client certificate, deploys (Helm chart or systemd units), and verifies health. Re-running is safe: config and the cluster UUID are preserved, credentials are overwritten atomically, and an existing client key is reused unless you pass --force. See onboarding for the full flow.

Entry points

Exactly one of the three entry points is required; they are mutually exclusive.

Common flags

Signing flags (phase 1 only)

Kubernetes-only flags

Valid only with --target helm.

VM-only flags

Valid only with --target systemd.

Flag conflicts

• --handoff, --enroll, and --signed-cert are mutually exclusive; exactly one is required.
• The Kubernetes-only flags are rejected unless --target helm; --server and --ca-data are rejected under --target helm (the Helm flow reads the workstation’s kubeconfig).
• --no-auto-sign and --sign-endpoint are mutually exclusive with each other, and both (plus --api-private-ca) are rejected with --signed-cert.
• --operators and --no-gateway are mutually exclusive.
• --skip-provision rejects --ch-pod, --ch-user-suffix, --server, --ca-data, and --ch-admin-password-stdin (nothing provisions).

clicklink clctl preflight

Runs the connector’s check suite, grouped by category: config, files, network, clickhouse, systemd, access, disk, redaction. Each check reports pass, warn, fail, or skip. Exit code 0 means all checks passed (warnings are non-blocking); exit code 2 means one or more checks failed.

The command runs locally by default. With --k8s-namespace it runs the connector pod’s own binary via kubectl exec and renders the report locally (systemd checks are always skipped in pods). With the remote channel flags it runs the installed binary on a remote VM instead.

The --k8s-* flags and the remote channel flags are mutually exclusive; pick one target.

clicklink clctl troubleshoot session

Enables, disables, and inspects the support session: the time-boxed window during which the troubleshooter accepts commands. When no session is active, the daemon refuses all commands even while its WebSocket is connected. See support sessions.

The commands operate in one of two modes:

• Local file (default): reads and writes the session state file on the host the troubleshooter runs on (default /var/lib/clicklink/session.json).
• Gateway: with --gateway-url, acquires an OIDC ID token and calls the troubleshooter’s session gateway instead, from your workstation.

Shared flags

session enable

Enabling fails while a session is already active; disable it first or wait for expiry.

session disable

Deactivates the session immediately. A no-op when no session is active.

session status

Shows whether the session is active, who enabled it, and when it expires. --output (-o) selects table (default) or json.

On Kubernetes, reach the gateway over a port-forward:

kubectl -n <connector-namespace> port-forward \
  statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 1h --reason "support ticket 1234"

clicklink clctl troubleshoot gateway trust

On a VM the session gateway serves a self-signed TLS certificate. This command records the certificate’s SHA-256 fingerprint in ~/.clicklink/clctl.yaml so the session commands can verify it; a pinned fingerprint that stops matching fails closed. Trust is established out of band in one of two ways:

• With the remote channel flags, the certificate is read directly off the VM over the already-authenticated channel and pinned.
• Without a channel, pass --gateway-fingerprint with the SHA-256 value the connector logged when it generated the certificate; the fetched certificate is pinned only if it matches. Omitting the flag prints the presented fingerprint without pinning anything.

clicklink clctl troubleshoot gateway trust \
  --gateway-url https://<vm-host>:8443 \
  --gateway-fingerprint <sha256-from-connector-log>

On Kubernetes, pinning is not used: expose the gateway through an Ingress with a CA-issued certificate, or use a port-forward.

clicklink clctl troubleshoot audit tail

Prints the last entries of the troubleshooter audit log: newline-delimited JSON, one entry per command the daemon accepted or blocked. The command opens the log read-only and never modifies it.

The connector’s runtime image has no shell, so on Kubernetes this command is the supported reader:

kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
  /clicklink clctl troubleshoot audit tail

Access provisioning

clicklink clctl scraper access provision and clicklink clctl troubleshoot access provision create, and with --force rotate, a component’s per-instance access bundle: the read-only ClickHouse user and its grants, plus the Kubernetes ServiceAccount, RBAC, and token the component uses. init runs this inline during install; the standalone commands are the re-run and rotation path.

Rotate an instance’s credentials for one component:

clicklink clctl scraper access provision --target helm \
  --target-namespace <connector-namespace> \
  --instance <instance-name> --instance-namespace <clickhouse-namespace> \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
  --force

Remote channel flags

preflight, gateway trust, and access provision accept a shared set of flags that select how a VM target is reached: