Use native time.Time type for timestamp flags

Replace opaque string types with proper time.Time for the
recreate-vms-created-before and vms-created-before flags. This provides
type safety, validation at parse time, and clearer error messages for
invalid RFC 3339 timestamps.

- Add TimeArg type with UnmarshalFlag for parsing RFC 3339 timestamps
- Update DeployOpts and RecreateOpts to use TimeArg
- Update director UpdateOpts and RecreateOpts to use time.Time
- Add comprehensive tests for TimeArg parsing and formatting

Author: Alphasite

cmd/deploy.go

@@ -104,7 +104,7 @@ func (c DeployCmd) Run(opts DeployOpts) error {
 	updateOpts := boshdir.UpdateOpts{
 		RecreatePersistentDisks:  opts.RecreatePersistentDisks,
 		Recreate:                 opts.Recreate,
-		RecreateVMsCreatedBefore: opts.RecreateVMsCreatedBefore,
+		RecreateVMsCreatedBefore: opts.RecreateVMsCreatedBefore.Time,
 		Fix:                      opts.Fix,
 		SkipDrain:                opts.SkipDrain,
 		DryRun:                   opts.DryRun,

cmd/deploy_test.go

@@ -2,6 +2,7 @@ package cmd_test
 
 import (
 	"errors"
+	"time"
 
 	"github.com/cppforlife/go-patch/patch"
 	. "github.com/onsi/ginkgo/v2"
@@ -89,7 +90,7 @@ var _ = Describe("DeployCmd", func() {
 
 		It("deploys manifest allowing to recreate VMs created before a timestamp", func() {
 			deployOpts.Recreate = true
-			deployOpts.RecreateVMsCreatedBefore = "2026-01-01T00:00:00Z"
+			deployOpts.RecreateVMsCreatedBefore = opts.TimeArg{Time: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)}
 
 			err := act()
 			Expect(err).ToNot(HaveOccurred())
@@ -100,7 +101,7 @@ var _ = Describe("DeployCmd", func() {
 			Expect(bytes).To(Equal([]byte("name: dep\n")))
 			Expect(updateOpts).To(Equal(boshdir.UpdateOpts{
 				Recreate:                 true,
-				RecreateVMsCreatedBefore: "2026-01-01T00:00:00Z",
+				RecreateVMsCreatedBefore: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
 			}))
 		})
 

cmd/opts/opts.go

@@ -505,7 +505,7 @@ type DeployOpts struct {
 
 	Recreate                 bool                `long:"recreate"                                description:"Recreate all VMs in deployment"`
 	RecreatePersistentDisks  bool                `long:"recreate-persistent-disks"               description:"Recreate all persistent disks in deployment"`
-	RecreateVMsCreatedBefore string              `long:"recreate-vms-created-before"             description:"Only recreate VMs created before the given RFC 3339 timestamp (requires --recreate)"`
+	RecreateVMsCreatedBefore TimeArg             `long:"recreate-vms-created-before"             description:"Only recreate VMs created before the given RFC 3339 timestamp (requires --recreate)"`
 	Fix                      bool                `long:"fix"                                     description:"Recreate an instance with an unresponsive agent instead of erroring"`
 	FixReleases              bool                `long:"fix-releases"                            description:"Reupload releases in manifest and replace corrupt or missing jobs/packages"`
 	SkipDrain                []boshdir.SkipDrain `long:"skip-drain" value-name:"[INSTANCE-GROUP[/INSTANCE-ID]]"  description:"Skip running drain and pre-stop scripts for specific instance groups" optional:"true" optional-value:"*"`
@@ -942,9 +942,9 @@ type RestartOpts struct {
 type RecreateOpts struct {
 	Args AllOrInstanceGroupOrInstanceSlugArgs `positional-args:"true"`
 
-	SkipDrain        bool   `long:"skip-drain" description:"Skip running drain and pre-stop scripts"`
-	Fix              bool   `long:"fix"        description:"Recreate an instance with an unresponsive agent instead of erroring"`
-	VMsCreatedBefore string `long:"vms-created-before" description:"Only recreate VMs created before the given RFC 3339 timestamp"`
+	SkipDrain        bool    `long:"skip-drain" description:"Skip running drain and pre-stop scripts"`
+	Fix              bool    `long:"fix"        description:"Recreate an instance with an unresponsive agent instead of erroring"`
+	VMsCreatedBefore TimeArg `long:"vms-created-before" description:"Only recreate VMs created before the given RFC 3339 timestamp"`
 
 	Canaries    string `long:"canaries" description:"Override manifest values for canaries"`
 	MaxInFlight string `long:"max-in-flight" description:"Override manifest values for max_in_flight"`

cmd/opts/time_arg.go

@@ -0,0 +1,31 @@
+package opts
+
+import (
+	"time"
+
+	bosherr "github.com/cloudfoundry/bosh-utils/errors"
+)
+
+type TimeArg struct {
+	time.Time
+}
+
+func (a *TimeArg) UnmarshalFlag(data string) error {
+	t, err := time.Parse(time.RFC3339, data)
+	if err != nil {
+		return bosherr.Errorf("Invalid RFC 3339 timestamp '%s': %s", data, err)
+	}
+	a.Time = t
+	return nil
+}
+
+func (a TimeArg) IsSet() bool {
+	return !a.Time.IsZero()
+}
+
+func (a TimeArg) AsString() string {
+	if a.IsSet() {
+		return a.Time.Format(time.RFC3339)
+	}
+	return ""
+}

cmd/opts/time_arg_test.go

@@ -0,0 +1,66 @@
+package opts_test
+
+import (
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	. "github.com/cloudfoundry/bosh-cli/v7/cmd/opts"
+)
+
+var _ = Describe("TimeArg", func() {
+	Describe("UnmarshalFlag", func() {
+		It("parses valid RFC 3339 timestamps", func() {
+			var arg TimeArg
+			err := arg.UnmarshalFlag("2026-01-01T00:00:00Z")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(arg.Time).To(Equal(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)))
+		})
+
+		It("parses RFC 3339 timestamps with timezone offset", func() {
+			var arg TimeArg
+			err := arg.UnmarshalFlag("2026-06-15T14:30:00-07:00")
+			Expect(err).ToNot(HaveOccurred())
+			Expect(arg.Time.UTC()).To(Equal(time.Date(2026, 6, 15, 21, 30, 0, 0, time.UTC)))
+		})
+
+		It("returns error for invalid timestamps", func() {
+			var arg TimeArg
+			err := arg.UnmarshalFlag("not-a-timestamp")
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("Invalid RFC 3339 timestamp"))
+		})
+
+		It("returns error for non-RFC3339 date formats", func() {
+			var arg TimeArg
+			err := arg.UnmarshalFlag("2026-01-01")
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("Invalid RFC 3339 timestamp"))
+		})
+	})
+
+	Describe("IsSet", func() {
+		It("returns false for zero time", func() {
+			var arg TimeArg
+			Expect(arg.IsSet()).To(BeFalse())
+		})
+
+		It("returns true for non-zero time", func() {
+			arg := TimeArg{Time: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)}
+			Expect(arg.IsSet()).To(BeTrue())
+		})
+	})
+
+	Describe("AsString", func() {
+		It("returns empty string for zero time", func() {
+			var arg TimeArg
+			Expect(arg.AsString()).To(Equal(""))
+		})
+
+		It("returns RFC 3339 formatted string for non-zero time", func() {
+			arg := TimeArg{Time: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)}
+			Expect(arg.AsString()).To(Equal("2026-01-01T00:00:00Z"))
+		})
+	})
+})

cmd/recreate.go

@@ -39,7 +39,7 @@ func newRecreateOpts(opts RecreateOpts) (boshdir.RecreateOpts, error) {
 			Canaries:         opts.Canaries,
 			MaxInFlight:      opts.MaxInFlight,
 			Converge:         true,
-			VMsCreatedBefore: opts.VMsCreatedBefore,
+			VMsCreatedBefore: opts.VMsCreatedBefore.Time,
 		}
 		return recreateOpts, nil
 	}

cmd/recreate_test.go

@@ -2,6 +2,7 @@ package cmd_test
 
 import (
 	"errors"
+	"time"
 
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -116,15 +117,15 @@ var _ = Describe("RecreateCmd", func() {
 		})
 
 		It("can set vms_created_before", func() {
-			recreateOpts.VMsCreatedBefore = "2026-01-01T00:00:00Z"
+			recreateOpts.VMsCreatedBefore = opts.TimeArg{Time: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)}
 
 			err := act()
 			Expect(err).ToNot(HaveOccurred())
 
 			Expect(deployment.RecreateCallCount()).To(Equal(1))
 
 			_, recreateOpts := deployment.RecreateArgsForCall(0)
-			Expect(recreateOpts.VMsCreatedBefore).To(Equal("2026-01-01T00:00:00Z"))
+			Expect(recreateOpts.VMsCreatedBefore).To(Equal(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)))
 		})
 
 		It("does not recreate if confirmation is rejected", func() {

director/deployment.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+	"time"
 
 	bosherr "github.com/cloudfoundry/bosh-utils/errors"
 )
@@ -138,7 +139,7 @@ func (d DeploymentImpl) Start(slug AllOrInstanceGroupOrInstanceSlug, opts StartO
 	if !opts.Converge {
 		return d.nonConvergingJobAction("start", slug, false, false, false)
 	}
-	return d.changeJobState("started", slug, false, false, false, false, opts.Canaries, opts.MaxInFlight, "")
+	return d.changeJobState("started", slug, false, false, false, false, opts.Canaries, opts.MaxInFlight, time.Time{})
 }
 
 func (d DeploymentImpl) Stop(slug AllOrInstanceGroupOrInstanceSlug, opts StopOpts) error {
@@ -150,15 +151,15 @@ func (d DeploymentImpl) Stop(slug AllOrInstanceGroupOrInstanceSlug, opts StopOpt
 	if opts.Hard {
 		state = "detached"
 	}
-	return d.changeJobState(state, slug, opts.SkipDrain, opts.Force, false, false, opts.Canaries, opts.MaxInFlight, "")
+	return d.changeJobState(state, slug, opts.SkipDrain, opts.Force, false, false, opts.Canaries, opts.MaxInFlight, time.Time{})
 }
 
 func (d DeploymentImpl) Restart(slug AllOrInstanceGroupOrInstanceSlug, opts RestartOpts) error {
 	if !opts.Converge {
 		return d.nonConvergingJobAction("restart", slug, opts.SkipDrain, false, false)
 	}
 
-	return d.changeJobState("restart", slug, opts.SkipDrain, opts.Force, false, false, opts.Canaries, opts.MaxInFlight, "")
+	return d.changeJobState("restart", slug, opts.SkipDrain, opts.Force, false, false, opts.Canaries, opts.MaxInFlight, time.Time{})
 }
 
 func (d DeploymentImpl) Recreate(slug AllOrInstanceGroupOrInstanceSlug, opts RecreateOpts) error {
@@ -173,7 +174,7 @@ func (d DeploymentImpl) nonConvergingJobAction(action string, slug AllOrInstance
 	return d.client.NonConvergingJobAction(action, d.name, slug.Name(), slug.IndexOrID(), skipDrain, hard, ignoreUnresponsiveAgent)
 }
 
-func (d DeploymentImpl) changeJobState(state string, slug AllOrInstanceGroupOrInstanceSlug, skipDrain bool, force bool, fix bool, dryRun bool, canaries string, maxInFlight string, vmsCreatedBefore string) error {
+func (d DeploymentImpl) changeJobState(state string, slug AllOrInstanceGroupOrInstanceSlug, skipDrain bool, force bool, fix bool, dryRun bool, canaries string, maxInFlight string, vmsCreatedBefore time.Time) error {
 	return d.client.ChangeJobState(
 		state, d.name, slug.Name(), slug.IndexOrID(), skipDrain, force, fix, dryRun, canaries, maxInFlight, vmsCreatedBefore)
 }
@@ -387,7 +388,7 @@ func (c Client) NonConvergingJobAction(action string, deployment string, instanc
 	return nil
 }
 
-func (c Client) ChangeJobState(state, deploymentName, job, indexOrID string, skipDrain bool, force bool, fix bool, dryRun bool, canaries string, maxInFlight string, vmsCreatedBefore string) error {
+func (c Client) ChangeJobState(state, deploymentName, job, indexOrID string, skipDrain bool, force bool, fix bool, dryRun bool, canaries string, maxInFlight string, vmsCreatedBefore time.Time) error {
 	if len(state) == 0 {
 		return bosherr.Error("Expected non-empty job state")
 	}
@@ -426,8 +427,8 @@ func (c Client) ChangeJobState(state, deploymentName, job, indexOrID string, ski
 		query.Add("max_in_flight", maxInFlight)
 	}
 
-	if vmsCreatedBefore != "" {
-		query.Add("recreate_vm_created_before", vmsCreatedBefore)
+	if !vmsCreatedBefore.IsZero() {
+		query.Add("recreate_vm_created_before", vmsCreatedBefore.Format(time.RFC3339))
 	}
 
 	path := fmt.Sprintf("/deployments/%s/jobs", deploymentName)
@@ -529,8 +530,8 @@ func (c Client) UpdateDeployment(manifest []byte, opts UpdateOpts) error {
 		query.Add("recreate_persistent_disks", "true")
 	}
 
-	if opts.RecreateVMsCreatedBefore != "" {
-		query.Add("recreate_vm_created_before", opts.RecreateVMsCreatedBefore)
+	if !opts.RecreateVMsCreatedBefore.IsZero() {
+		query.Add("recreate_vm_created_before", opts.RecreateVMsCreatedBefore.Format(time.RFC3339))
 	}
 
 	if opts.Fix {

director/deployment_test.go

@@ -5,6 +5,7 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+	"time"
 
 	semver "github.com/cppforlife/go-semi-semantic/version"
 	. "github.com/onsi/ginkgo/v2"
@@ -552,10 +553,10 @@ var _ = Describe("Deployment", func() {
 					})
 
 					It("changes state with vms_created_before filter", func() {
-						timestamp := "2026-01-01T00:00:00Z"
+						timestamp := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
 						recreateOpts.VMsCreatedBefore = timestamp
 
-						query := fmt.Sprintf("state=%s&recreate_vm_created_before=%s", state, url.QueryEscape(timestamp))
+						query := fmt.Sprintf("state=%s&recreate_vm_created_before=%s", state, url.QueryEscape(timestamp.Format(time.RFC3339)))
 
 						ConfigureTaskResult(
 							ghttp.CombineHandlers(
@@ -989,10 +990,10 @@ var _ = Describe("Deployment", func() {
 		})
 
 		It("succeeds updating deployment with recreate_vm_created_before flag", func() {
-			timestamp := "2026-01-01T00:00:00Z"
+			timestamp := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
 			ConfigureTaskResult(
 				ghttp.CombineHandlers(
-					ghttp.VerifyRequest("POST", "/deployments", "recreate=true&recreate_vm_created_before="+url.QueryEscape(timestamp)),
+					ghttp.VerifyRequest("POST", "/deployments", "recreate=true&recreate_vm_created_before="+url.QueryEscape(timestamp.Format(time.RFC3339))),
 					ghttp.VerifyBasicAuth("username", "password"),
 					ghttp.VerifyHeader(http.Header{
 						"Content-Type": []string{"text/yaml"},

director/interfaces.go

@@ -215,13 +215,13 @@ type RecreateOpts struct {
 	SkipDrain        bool
 	DryRun           bool
 	Converge         bool
-	VMsCreatedBefore string
+	VMsCreatedBefore time.Time
 }
 
 type UpdateOpts struct {
 	Recreate                 bool
 	RecreatePersistentDisks  bool
-	RecreateVMsCreatedBefore string
+	RecreateVMsCreatedBefore time.Time
 	Fix                      bool
 	SkipDrain                SkipDrains
 	Canaries                 string