CLI User Guide¶

This guide covers how to use the kubectl-hibernator plugin for managing HibernatePlan resources. It provides practical commands for inspecting plans, controlling hibernation operations, managing restore data, and viewing executor logs.

Installation¶

One-Line Installer (Recommended)¶

The fastest way to install kubectl-hibernator is using the install script:

curl -sSL https://hibernator.ardikabs.com/install-cli.sh | bash

This automatically detects your operating system and architecture, downloads the latest release, verifies the checksum, and installs to /usr/local/bin.

Install a specific version:

curl -sSL https://hibernator.ardikabs.com/install-cli.sh | bash -s -- --version v1.5.0

Install to a custom directory:

curl -sSL https://hibernator.ardikabs.com/install-cli.sh | bash -s -- --install-dir ~/bin

Manual Installation¶

Alternatively, download the binary for your platform from the GitHub Releases page and place it on your PATH.

Linux (amd64)Linux (arm64)macOS (amd64)macOS (arm64)

curl -Lo kubectl-hibernator \
  https://github.com/ardikabs/hibernator/releases/download/v1.5.0/kubectl-hibernator-linux-amd64
chmod +x kubectl-hibernator
sudo mv kubectl-hibernator /usr/local/bin/

curl -Lo kubectl-hibernator \
  https://github.com/ardikabs/hibernator/releases/download/v1.5.0/kubectl-hibernator-linux-arm64
chmod +x kubectl-hibernator
sudo mv kubectl-hibernator /usr/local/bin/

curl -Lo kubectl-hibernator \
  https://github.com/ardikabs/hibernator/releases/download/v1.5.0/kubectl-hibernator-darwin-amd64
chmod +x kubectl-hibernator
sudo mv kubectl-hibernator /usr/local/bin/

curl -Lo kubectl-hibernator \
  https://github.com/ardikabs/hibernator/releases/download/v1.5.0/kubectl-hibernator-darwin-arm64
chmod +x kubectl-hibernator
sudo mv kubectl-hibernator /usr/local/bin/

Verify the installation:

kubectl hibernator version

Automatic Version Check¶

The CLI automatically checks for updates when you run kubectl hibernator version. If a newer version is available (including release candidates), you'll see a message with installation instructions:

📦 A new version is available: v1.6.0-rc.1
   Current version: v1.5.0 (abc1234)
   Install with:
   curl -sSL https://hibernator.ardikabs.com/install-cli.sh | bash -s -- --version v1.6.0-rc.1

Key behaviors: - Release Candidate Preference: When available, the CLI prefers release candidate versions (e.g., v1.6.0-rc.1) over stable versions, giving you access to the latest features. - Offline Safe: If the version check fails (no internet connection, GitHub API rate limit, etc.), the command completes silently without errors. - Dev Builds Skipped: Development builds (built from source without version tags) skip the update check entirely.

Global Flags¶

These flags are available on every subcommand:

Flag	Description
`--kubeconfig`	Path to the kubeconfig file. Defaults to `$KUBECONFIG` or `~/.kube/config`.
`-n, --namespace`	Kubernetes namespace. Defaults to the current context namespace.
`--json`	Output in JSON format.

Commands¶

`list`¶

List all HibernatePlan resources with their current phase and next scheduled event.

Aliases: ls

kubectl hibernator list
kubectl hibernator list -A
kubectl hibernator ls -n production

Flag	Description
`-A, --all-namespaces`	List plans from all namespaces.

`describe`¶

Display comprehensive details about a HibernatePlan including schedule, execution strategy, targets, and status history.

kubectl hibernator describe my-plan
kubectl hibernator describe my-plan --json

`preview`¶

Preview the schedule and upcoming hibernation/wakeup events for a plan. Useful for validating schedule configuration before or after applying.

Aliases: schedule

kubectl hibernator preview my-plan
kubectl hibernator preview my-plan --events 10
kubectl hibernator preview --file plan.yaml

Flag	Description
`-f, --file`	Path to a local HibernatePlan YAML file. Loads from cluster if not provided.
`--events`	Number of upcoming events to display (default: `5`).

`override`¶

Manually override the schedule of a HibernatePlan, forcing it toward a target phase (hibernate or wakeup). The override is persistent — the plan stays locked until explicitly deactivated or until the deadline expires. See Manual Actions for full details.

# Force hibernation
kubectl hibernator override my-plan --to hibernate

# Force wakeup
kubectl hibernator override my-plan --to wakeup

# Deactivate override and restore schedule control
kubectl hibernator override my-plan --disable

# Override with automatic expiration (2 hours)
kubectl hibernator override my-plan --to wakeup --seconds 7200

# Override until a specific time using natural language
kubectl hibernator override my-plan --to hibernate --until "tomorrow at 8am"

# Override with dry-run to preview changes
kubectl hibernator override my-plan --to wakeup --until "in 30 minutes" --dry-run

Flag	Description
`--to`	Target phase: `hibernate` or `wakeup`. Required when activating.
`--disable`	Deactivate the override and restore normal schedule control. Mutually exclusive with `--to`, `--seconds`, and `--until`.
`--seconds`	Duration in seconds for the override to remain active. Mutually exclusive with `--until`.
`--until`	Deadline for the override. Supports natural language (e.g., `in 30 minutes`, `tomorrow at 6am`) or RFC3339 format. Mutually exclusive with `--seconds`.
`--dry-run`	Preview what would happen without making changes.

Warning

Without --seconds or --until, this is not a one-shot action. The plan will stay locked at the target phase until you explicitly run kubectl hibernator override <plan> --disable or the deadline expires.

`restart`¶

Re-trigger the last executor operation on a plan that is already at a stable phase (Active or Hibernated). This is a one-shot action — the annotation is consumed atomically by the controller. See Manual Actions for full details.

kubectl hibernator restart my-plan
kubectl hibernator restart my-plan -n production
kubectl hibernator restart my-plan --dry-run

The plan must have completed at least one full hibernation cycle (.status.currentOperation must be recorded).

Flag	Description
`--dry-run`	Preview what would happen without making changes.

Fresh restart

To discard the locked cycle intent and start a new hibernation cycle, add the hibernator.ardikabs.com/fresh=true annotation alongside restart=true. See Manual Actions for details. CLI support for --fresh is tracked separately.

`retry`¶

Trigger a manual retry of a plan stuck in the Error phase. The controller clears the error state and re-attempts the failed operation.

kubectl hibernator retry my-plan
kubectl hibernator retry my-plan --dry-run

Note

retry only applies to plans in Error phase. For plans in Active or Hibernated phase, use restart instead.

Flag	Description
`--dry-run`	Preview what would happen without making changes.

Flag	Description
`--dry-run`	Preview what would happen without making changes.

`revert`¶

Selectively wake up targets that were successfully hibernated on a plan stuck in Error phase after a failed hibernation. Targets that failed are skipped. See Manual Actions for full details.

kubectl hibernator revert my-plan
kubectl hibernator revert my-plan --dry-run
kubectl hibernator revert my-plan --wait

Flag	Description
`--dry-run`	Preview which targets would be reverted without making changes.
`--wait`	Wait for the revert operation to complete (polls every 5s, up to 10m).

`suspend`¶

Suspend a HibernatePlan for a specified duration, preventing all hibernation operations until the deadline expires. See Plan Suspension for details on the suspension mechanism.

# Suspend for 2 hours
kubectl hibernator suspend my-plan --seconds 7200 --reason "production deployment"

# Suspend until a specific time (RFC3339 format)
kubectl hibernator suspend my-plan --until "2026-01-15T06:00:00Z" --reason "maintenance window"

# Suspend using natural language
kubectl hibernator suspend my-plan --until "in 2 hours" --reason "maintenance window"

# Suspend until tomorrow morning
kubectl hibernator suspend my-plan --until "tomorrow at 8am" --reason "scheduled maintenance"

# Suspend until a specific date/time
kubectl hibernator suspend my-plan --until "2026-01-15 14:30" --reason "holiday freeze"

# Preview suspension without applying
kubectl hibernator suspend my-plan --until "in 30 minutes" --reason "test" --dry-run

Flag	Description
`--seconds`	Duration in seconds to suspend. Mutually exclusive with `--until`.
`--until`	Deadline for suspension. Supports natural language (e.g., `in 30 minutes`, `tomorrow at 6am`), date/time formats (e.g., `2026-01-15 14:30`), or RFC3339 format (e.g., `2026-01-15T06:00:00Z`). Mutually exclusive with `--seconds`.
`--reason`	Reason for suspension (default: `"User initiated"`).
`--dry-run`	Preview what would happen without making changes.

Natural Language Formats for --until:

The --until flag supports multiple user-friendly formats for both suspend and override commands:

Format Type	Examples
Relative	`in 30 minutes`, `in 2 hours`, `in 1 day`
Tomorrow	`tomorrow`, `tomorrow at 6am`, `tomorrow at 14:30`
Next	`next Monday`, `next week`
Date	`2026-01-15`, `Jan 15, 2026`
Date+Time	`2026-01-15 14:30`, `Jan 15, 2026 2:30pm`
RFC3339	`2026-01-15T14:30:00Z` (recommended for scripts)

Note

All times are interpreted in your local timezone and stored as UTC internally.

`resume`¶

Resume a suspended HibernatePlan, restoring normal schedule evaluation immediately. Clears spec.suspend as well as the suspend-until and suspend-reason annotations.

kubectl hibernator resume my-plan
kubectl hibernator resume my-plan --dry-run

Flag	Description
`--dry-run`	Preview what would happen without making changes.

`logs`¶

View controller logs filtered by plan context. Automatically discovers the controller pod and filters log entries relevant to the specified plan and its executions.

kubectl hibernator logs my-plan
kubectl hibernator logs my-plan --follow
kubectl hibernator logs my-plan --target my-cluster
kubectl hibernator logs my-plan --tail 100
kubectl hibernator logs my-plan --level error

Flag	Description
`--target`	Filter logs by target name.
`--level`	Filter by level: `error` (logs with error field) or `info` (logs without errors). Other values match everything.
`--tail`	Number of recent log lines to fetch (default: `500`). Ignored with `--follow`.
`-f, --follow`	Stream logs continuously until interrupted.

`restore`¶

Manage restore points — the captured resource state during hibernation that is used to restore resources during wakeup. Restore data is stored in a ConfigMap named hibernator-restore-<plan-name>.

Understanding Restore Point Timestamps¶

Restore point data contains two important timestamps that serve different purposes:

Timestamp	Description
Captured At	The timestamp when the hibernator captured and initiated the save operation to the ConfigMap. This tracks when the data was captured from the hibernator's perspective.
Reported At	The time when the executor callback was triggered for a specific resource (via `ReportStateCallback`). This tracks when each resource's state was initially reported during the shutdown process.

Key Differences: - Captured At is set per-target when the hibernator initiates the ConfigMap update. It serves as a historical marker for auditing and freshness checks. - Reported At is set per-resource when the executor reports the state (via callback) during the shutdown process. Multiple resources may be reported at different times within the same hibernation cycle. - Reported At is used for idempotency tracking — it helps determine if a resource has already been reported in the current hibernation cycle. - Captured At tracks when the hibernator captured the data, useful for historical analysis and determining data freshness.

Example Flow:

Hibernation Cycle:
  1. Executor discovers resource A → Reports state → Reported At = T1
  2. Executor discovers resource B → Reports state → Reported At = T2
  3. Hibernator captures and initiates save to ConfigMap → Captured At = T3

`restore list`¶

Display restore point summary or detailed resource list for a plan.

kubectl hibernator restore list my-plan
kubectl hibernator restore list my-plan -o wide
kubectl hibernator restore list my-plan --target eks-cluster -o wide
kubectl hibernator restore list my-plan -o json

Flag	Description
`-o, --output`	Output format: (empty) for summary, `wide` for detailed list, `json` for JSON.
`-t, --target`	Filter by a specific target name.

`restore inspect`¶

Display detailed restore point information for a specific resource within a target.

kubectl hibernator restore inspect my-plan --target eks-cluster --resource-id ng-main

Flag	Description
`-t, --target`	Target name (required).
`-r, --resource-id`	Resource identifier (required).

`restore init`¶

Initialize an empty restore point entry for a target. Useful for bootstrapping restore data before the first hibernation cycle.

kubectl hibernator restore init my-plan --target eks-cluster --executor eks
kubectl hibernator restore init my-plan -t db-prod -x rds --force

Flag	Description
`-t, --target`	Target name (required).
`-x, --executor`	Executor type: `eks`, `rds`, `ec2`, `karpenter`, etc. (required).
`--force`	Overwrite an existing restore point entry for the target.
`--dry-run`	Preview what would happen without making changes.

`restore patch`¶

Update specific fields in a resource's restore state using field operations or JSON merge patch.

# Field-level updates (dot notation)
kubectl hibernator restore patch my-plan -t eks -r ng-main \
  --set desiredCapacity=10

# Remove fields
kubectl hibernator restore patch my-plan -t eks -r ng-main \
  --remove config.deprecated

# JSON merge patch
kubectl hibernator restore patch my-plan -t eks -r ng-main \
  --patch '{"desiredCapacity": 10}'

# Preview changes without applying
kubectl hibernator restore patch my-plan -t eks -r ng-main \
  --set desiredCapacity=10 --dry-run

Flag	Description
`-t, --target`	Target name (required).
`-r, --resource-id`	Resource identifier (required).
`--set`	Set field value using dot notation (repeatable).
`--remove`	Remove field using dot notation (repeatable).
`--patch`	Inline JSON merge patch (RFC 7386).
`--patch-file`	Path to a JSON merge patch file.
`--dry-run`	Preview changes without applying.
`--yes`	Skip confirmation prompts (non-interactive use).

Note

Field operations (--set/--remove) and JSON merge patch (--patch/--patch-file) are mutually exclusive — use one mode per invocation.

`restore drop`¶

Remove a specific resource from a restore point. The next hibernation cycle will capture fresh restore data.

kubectl hibernator restore drop my-plan --target eks-cluster --resource-id ng-main
kubectl hibernator restore drop my-plan --target eks-cluster --resource-id ng-main --dry-run

Flag	Description
`-t, --target`	Target name (required).
`-r, --resource-id`	Resource identifier (required).
`--dry-run`	Preview what would happen without making changes.

Warning

drop applies immediately without a confirmation prompt. Use --dry-run first when scripting.

`restore export`¶

Write a target's restore entry (or a single resource state) to a local file. This is the backup half of the weekend partial-run workflow below.

kubectl hibernator restore export my-plan --target eks-cluster --file eks-full.json
kubectl hibernator restore export my-plan --target eks-cluster --resource-id ng-main --file ng-main.json

Flag	Description
`-t, --target`	Target name (required).
`-r, --resource-id`	Single resource ID to export (defaults to the whole target entry).
`--file`	Destination file path (required). Parent directories are created.

`restore import`¶

Write a file produced by restore export back into the restore point, replacing the target entry (or a single resource state) wholesale. A backup is refused when its embedded target name differs from --target, so cross-target imports cannot happen by accident.

kubectl hibernator restore import my-plan --target eks-cluster --file eks-full.json
kubectl hibernator restore import my-plan --target eks-cluster --resource-id ng-main --file ng-main.json
kubectl hibernator restore import my-plan --target eks-cluster --file eks-full.json --dry-run

Flag	Description
`-t, --target`	Target name (required).
`-r, --resource-id`	Single resource ID to import (defaults to the whole target entry).
`--file`	Source file path, as written by `restore export` (required).
`--dry-run`	Preview what would happen without making changes.
`--yes`	Skip confirmation prompts (non-interactive use).

`restore prune`¶

Mark every resource state in a target's restore entry excluded except the --keep list, so wakeup skips them. The payloads stay intact: importing the backup (or the next full hibernation) clears the markers. Use --delete to permanently remove instead.

kubectl hibernator restore prune my-plan --target eks-cluster --keep ng-weekend-a --keep ng-weekend-b
kubectl hibernator restore prune my-plan --target eks-cluster --keep ng-weekend-a --dry-run
kubectl hibernator restore prune my-plan --target eks-cluster --keep ng-weekend-a --delete --yes

Flag	Description
`-t, --target`	Target name (required).
`--keep`	Resource ID to keep (repeatable, at least one required).
`--dry-run`	Preview what would happen without making changes.
`--yes`	Skip confirmation prompts (non-interactive use).
`--delete`	Permanently delete non-kept resources instead of marking them excluded.

Weekend partial runs¶

ScheduleException target overrides disable whole targets; when only some resources within one target should run over the weekend, trim the restore data instead:

# Friday evening: snapshot the full restore data
kubectl hibernator restore export weekend-plan -t eks --file eks-full.json

# Trim to weekend runners only
kubectl hibernator restore prune weekend-plan -t eks --keep ng-weekend-a --keep ng-weekend-b --yes

# ... SAT/SUN partial runs happen ...

# Monday: restore the full snapshot
kubectl hibernator restore import weekend-plan -t eks --file eks-full.json --yes

`notification`¶

Manage and test HibernateNotification resources.

Aliases: notif

`notification list`¶

List all HibernateNotification resources with their subscribed events, sink count, watched plans, and last delivery status.

Aliases: ls

kubectl hibernator notification list
kubectl hibernator notification list -A
kubectl hibernator notification list -n production
kubectl hibernator notification list --plan my-plan
kubectl hibernator notification list --json

Flag	Description
`-A, --all-namespaces`	List notifications from all namespaces.
`--plan`	Filter notifications whose selector matches this HibernatePlan's labels.

`notification describe`¶

Display comprehensive details about a HibernateNotification, including its label selector, subscribed events, sink configurations (type, secret reference, template reference), and delivery status history.

kubectl hibernator notification describe my-notification
kubectl hibernator notification describe my-notification -n production
kubectl hibernator notification describe my-notification --plan my-plan
kubectl hibernator notification describe my-notification --json

Flag	Description
`--plan`	Check whether this notification's selector matches the given HibernatePlan's labels.

`notification send`¶

Send a test notification by resolving the sink configuration, rendering the template, and delivering the message. This command runs locally — it calls the sink endpoint directly without involving the controller.

Aliases: trigger

# Send a test notification (auto-selects sink when only one is configured)
kubectl hibernator notification send my-notification --event Success

# Send to a specific sink
kubectl hibernator notification send my-notification --event Start --sink slack-alerts

# Dry-run: render message without sending
kubectl hibernator notification send my-notification --event Failure --dry-run

# Populate payload from a real plan's current status
kubectl hibernator notification send my-notification --event Success --plan my-plan

# Use a local config file instead of reading from the cluster Secret
kubectl hibernator notification send my-notification --event Start --config-file ./slack-config.json

# Use a local Go template file instead of the cluster ConfigMap
kubectl hibernator notification send my-notification --event Success --template-file ./custom.gotpl

# Local mode: no cluster access needed
kubectl hibernator notification send --event Success --sink-type slack --config-file ./slack-config.json

# Local mode with a plan YAML from disk
kubectl hibernator notification send --event Failure --sink-type telegram --config-file ./telegram.json --plan-file ./my-plan.yaml

# Override phase in synthetic payload
kubectl hibernator notification send my-notification --event Start --phase Hibernating

Flag	Short	Description
`--event`	`-e`	Event type to simulate (case-insensitive). Required. One of: `Start`, `Success`, `Failure`, `Recovery`, `PhaseChange`.
`--sink`		Sink name to send to. Auto-selected if only one sink is configured.
`--sink-type`		Sink type for local mode: `slack`, `telegram`, or `webhook`. Requires `--config-file`.
`--plan`	`-p`	Populate payload from this HibernatePlan's current cluster status. Mutually exclusive with `--plan-file`.
`--plan-file`	`-f`	Local YAML file of a HibernatePlan to populate payload from. Mutually exclusive with `--plan`.
`--config-file`	`-c`	Local JSON file for sink config (bypasses reading from the cluster Secret).
`--template-file`	`-t`	Local Go template file (overrides the cluster ConfigMap template).
`--dry-run`		Render the message but do not send it. Prints the rendered output.
`--phase`		Phase to use in the synthetic payload. Defaults to a phase inferred from the event.

Local mode

When --sink-type and --config-file are both provided, the command runs fully locally without any Kubernetes API access. The notification-name argument is optional in this mode. Combine with --plan-file to test against a real plan definition from disk.

`version`¶

Print the CLI plugin version.

kubectl hibernator version
kubectl hibernator version --json

Flag	Description
`--json`	Output machine-readable JSON (`version`, `commit`) instead of human text. Skips the update check.

CLI User Guide¶

Installation¶

One-Line Installer (Recommended)¶

Manual Installation¶

Automatic Version Check¶

Global Flags¶

Commands¶

list¶

describe¶

preview¶

override¶

restart¶

retry¶

revert¶

suspend¶

resume¶

logs¶

restore¶

Understanding Restore Point Timestamps¶

restore list¶

restore inspect¶

restore init¶

restore patch¶

restore drop¶

restore export¶

restore import¶

restore prune¶

Weekend partial runs¶

notification¶

notification list¶

notification describe¶

notification send¶

version¶

`list`¶

`describe`¶

`preview`¶

`override`¶

`restart`¶

`retry`¶

`revert`¶

`suspend`¶

`resume`¶

`logs`¶

`restore`¶

`restore list`¶

`restore inspect`¶

`restore init`¶

`restore patch`¶

`restore drop`¶

`restore export`¶

`restore import`¶

`restore prune`¶

`notification`¶

`notification list`¶

`notification describe`¶

`notification send`¶

`version`¶