Skip to content

cli-reference.md

Latest commit

 

History

History
196 lines (137 loc) · 4.73 KB

cli-reference.md

File metadata and controls

196 lines (137 loc) · 4.73 KB

CLI Reference

This page summarizes the user-facing GitOpsCTL commands. Run gitopsctl <command> --help for the exact help text from your build.

Global Flags

Flag Default Description
--api-url http://127.0.0.1:8080 Base URL used by commands that talk to a running controller API.
--events-file empty Append command/controller integration events as JSON lines.
--events-webhook empty POST integration events to an HTTP endpoint.
--events-webhook-bearer empty Bearer token for webhook requests.
--events-webhook-secret empty HMAC signing secret for webhook requests.
--events-webhook-retries 2 Retry attempts for webhook events.
--events-webhook-backoff 750ms Base retry backoff.
--events-webhook-timeout 12s HTTP timeout per webhook attempt.

Global flags come before or after the subcommand depending on Cobra parsing, but placing them before the command is the least surprising form:

gitopsctl --api-url http://127.0.0.1:8080 sync-app --name nginx-demo

Controller

start

Starts the controller and API server.

gitopsctl start --api-address :8080

Flags:

Flag Default Description
--api-address, -a :8080 Listen address for REST API, SSE, and metrics.

Applications

register-apps

Registers an application in configs/applications.json.

gitopsctl register-apps \
  --name nginx-demo \
  --repo https://github.com/aeswibon/gitopsctl.git \
  --branch main \
  --path examples/manifests \
  --cluster local-dev \
  --interval 30s \
  --sync-policy auto

Important flags:

Flag Short Required Description
--name -n Yes Application name.
--repo -r Yes Git repository URL.
--path -p Yes Manifest path inside the repo.
--cluster -c Yes Registered cluster name.
--branch -b No Git branch, default main.
--interval -i No Polling interval, default 5m.
--sync-policy No auto or manual, default auto.
--webhook-url No Per-app notification webhook.
--webhook-secret No Per-app webhook signing secret.
--dry-run No Preview without saving.
--force No Overwrite an existing app entry.

list-apps

Lists registered applications.

gitopsctl list-apps

status-apps

Shows application status and sync metadata.

gitopsctl status-apps

sync-app

Requests immediate reconciliation through the running API server.

gitopsctl --api-url http://127.0.0.1:8080 sync-app --name nginx-demo

approve-app

Approves a commit for a manual-sync application.

gitopsctl --api-url http://127.0.0.1:8080 approve-app \
  --name nginx-demo \
  --commit <commit-hash>

unregister

Removes an application registration.

gitopsctl unregister --name nginx-demo

Clusters

register-cluster

Registers a Kubernetes cluster in configs/clusters.json.

gitopsctl register-cluster \
  --name local-dev \
  --kubeconfig ~/.kube/config \
  --allowed-namespaces demo

Important flags:

Flag Short Required Description
--name -n Yes Cluster name.
--kubeconfig -k No Kubeconfig path. Auto-detected from $KUBECONFIG or ~/.kube/config when omitted.
--allowed-namespaces No Comma-separated namespace allow-list.
--test No Validate kubeconfig loading during registration.
--dry-run No Preview without saving.
--force No Overwrite an existing cluster entry.

list-clusters

Lists registered clusters.

gitopsctl list-clusters

status-clusters

Shows cluster connectivity status.

gitopsctl status-clusters

check-cluster

Requests a health check through the running API server.

gitopsctl --api-url http://127.0.0.1:8080 check-cluster --name local-dev

unregister-cluster

Removes a cluster registration.

gitopsctl unregister-cluster --name local-dev

Dashboard and Events

dashboard

Opens the terminal dashboard.

gitopsctl dashboard --api-url http://127.0.0.1:8080

tail-events

Reads a JSONL event file.

gitopsctl tail-events --file configs/events.jsonl --from-start

Useful flags:

Flag Default Description
--file configs/events.jsonl Event file path.
--follow true Continue reading appended events.
--from-start false Print existing lines first.
--poll-interval 400ms File polling interval.